Merge branch 'release/0.0.2'

Author: gin0115

README.md

@@ -1,100 +1,161 @@
 # Pixie WPDB Query Builder for WordPress
 
-
-![alt text](https://img.shields.io/badge/Current_Version-0.0.1-yellow.svg?style=flat " ") 
-[![Open Source Love](https://badges.frapsoft.com/os/mit/mit.svg?v=102)]()
+[![GitHub issues](https://img.shields.io/github/release/gin0115/pixie-wpdb)](https://github.com/gin0115/pixie-wpdb/releases)
 ![](https://github.com/gin0115/pixie-wpdb/workflows/GitHub_CI/badge.svg " ")
 [![codecov](https://codecov.io/gh/gin0115/pixie-wpdb/branch/master/graph/badge.svg?token=4yEceIaSFP)](https://codecov.io/gh/gin0115/pixie-wpdb)
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/gin0115/pixie-wpdb/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/gin0115/pixie-wpdb/?branch=master)
+[![GitHub issues](https://img.shields.io/github/issues/gin0115/pixie-wpdb)](https://github.com/gin0115/pixie-wpdb/issues)
+[![Open Source Love](https://badges.frapsoft.com/os/mit/mit.svg?v=102)]()
 
+An expressive, query builder for WordPRess it can also be referred as a Database Abstraction Layer. Pixie WPDB supports WPDB ONLY and it takes care of query sanitization, table prefixing and many other things with a unified API.
+
+> **Pixie WPDB** is an adaption of `pixie` originally written by [usmanhalalit](https://github.com/usmanhalalit). [Pixie](https://github.com/usmanhalalit/pixie) is no longer under active development.
+
+# Features
+* [Fluent API](https://github.com/gin0115/pixie-wpdb/wiki/Query%20Methods)
+* [Nested Queries](https://github.com/gin0115/pixie-wpdb/wiki/Sub%20&%20Nested%20Queries)
+* [Multiple Connections](https://github.com/gin0115/pixie-wpdb/wiki/Home#setup-connection)
+* [Sub Queries](https://github.com/gin0115/pixie-wpdb/wiki/Sub%20&%20Nested%20Queries)
+* [JSON Support](https://github.com/gin0115/pixie-wpdb/wiki/Json%20Methods)
+* [Model Hydration](https://github.com/gin0115/pixie-wpdb/wiki/Result%20Hydration)
+* [Custom Alias Facade](https://github.com/gin0115/pixie-wpdb/wiki/Home#connection-alias)
+* [Raw SQL Expressions](https://github.com/gin0115/pixie-wpdb/wiki/Bindings%20&%20Raw%20Expressions)
+* [Value Type Binding](https://github.com/gin0115/pixie-wpdb/wiki/Bindings%20&%20Raw%20Expressions)
+* [Transaction Support](https://github.com/gin0115/pixie-wpdb/wiki/Transactions)
+* [Query Events](https://github.com/gin0115/pixie-wpdb/wiki/Query%20Events)
+
+```php
+$thing = QB::table('someTable')->where('something','=', 'something else')->first();
+```
 
-A lightweight, expressive, query builder for WordPRess it can also be referred as a Database Abstraction Layer. Pixie WPDB supports WPDB ONLY and it takes care of query sanitization, table prefixing and many other things with a unified API.
+# Install
 
-> **Pixie WPDB** is an adaption of `pixie` originally written by [usmanhalalit](https://github.com/usmanhalalit). [Pixie is not longer under active development ](https://github.com/usmanhalalit/pixie)
+## Perquisites
 
-## Requirements
- - PHP 7.1+
- - MySql 5.7+ or MariaDB 10.2+
+* WordPress 5.7+ (tested upto 5.9)
+* PHP 7.1+ (includes support for PHP8)
+* MySql 5.7+ or MariaDB 10.2+
+* Composer (optional)
 
-> Tested all combinations of PHP 7.1, 7.2, 7.3, 7.4, 8.0, 8.1 with MySql 5.7 & MariaBD 10.2, 10.3, 10.4, 10.5, 10.6, 10.7
+## Using Composer
 
+The easiest way to include Pixie in your project is to use [composer](http://getcomposer.org/doc/00-intro.md#installation-nix). 
 
-It has some advanced features like:
+```bash
+composer require gin0115/pixie-wpdb
+```
 
- - Query Events
- - Nested Criteria
- - Sub Queries
- - Multiple Database Connections.
+## Static Loader
 
-Additional features added to this version of Pixie
- - JSON Support (Select, Where)
- - Aggregation methods (Min, Max, Average & Sum)
- - Custom Model Hydration
- - Date based Where (Month, Day, Year & Date)
+If you are planning to just inlcude Pixie direct in your plugin, you can extract the `src` directory and add this to your `functions.php` or similar.
 
-The syntax is quite similar to Laravel's query builder.
+```php 
+require_once '/path/to/src/loader.php'; 
 
-## Example
-```PHP
-// Make sure you have Composer's autoload file included
-require 'vendor/autoload.php';
+```
+> Each class is checked if already loaded, to avoid conflicts if used on multiple plugins.
 
-// Create a connection, once only.
-$config = [
-    Connection::PREFIX => 'cb_', // Table prefix, optional
-];
+# Setup Connection
+
+If you are only planning on having a single connection, you will only need to configure the connection once. 
 
-// Get the current (gloabl) WPDB instance, or create a custom one 
+```php
+# Basic setup
+
+// Access the global WPDB or a custom instance for additional tables.
 global $wpdb;
 
-// Give this instance its own custom class alias (for calling statically);
-$alias = 'QB';
+// Configure the builder and/or internal WPDB instance
+$connection_config = [Connection::PREFIX => 'gin0115_'];
+
+// Give a *single* Alias
+$builder_alias = 'Gin0115\\DB';
 
-new \Pixie\Connection($wpdb, $config, $alias);
+new Connection( $wpdb, $connection_config, $builder_alias );
 ```
 
-**Simple Query:**
+This would then give access to an instance of the QueryBuilder using this connection, via the alias defined `Gin0115\DB`
 
-The query below returns the row where id = 3, null if no rows.
-```PHP
-$row = QB::table('my_table')->find(3);
+```php
+$foos = Gin0115\DB::table('foo')->where('column', 'red')->get();
 ```
 
-**Full Queries:**
+> Generated & executed query :: "SELECT * FROM gin0115_foo WHERE column = 'red'; "
 
-```PHP
-$query = QB::table('my_table')->where('name', '=', 'Sana');
+## Connection Config
+
+It is possible to configure the connection used by your instance of the query builder.
+
+Values
 
-// Get result
-$query->get();
+| Key      | Constant | Value | Description |  
+| ----------- | ----------- |----------- |----------- |
+| prefix      | Connection:: PREFIX       | STRING | Custom table prefix (will ignore WPDB prefix)|
+| use_wpdb_prefix   | Connection:: USE_WPDB_PREFIX        | BOOL | If true will use WPDB prefix and ignore custom prefix
+| clone_wpdb      | Connection:: CLONE_WPDB       | BOOL | If true, will clone WPDB to not use reference to the instance (usually the $GLOBAL)|
+| show_errors | Connection:: SHOW_ERRORS | BOOL | If set to true will configure WPDB to show/hide errors |
+ 
+
+```php
+$config = [
+    Connection::PREFIX          => 'acme_',
+    Connection::USE_WPDB_PREFIX => true,
+    Connection::CLONE_WPDB      => true,
+    Connection::SHOW_ERRORS     => false,
+];
 ```
 
-**Query Events:**
+> [More details on the config](https://github.com/gin0115/pixie-wpdb/wiki#connection-config)
+
+## Connection Alias
 
-After the code below, every time a select query occurs on `users` table, it will add this where criteria, so banned users don't get access.
+When you create a connection:
 
 ```PHP
-QB::registerEvent('before-select', 'users', function($qb)
-{
-    $qb->where('status', '!=', 'banned');
-});
+new Connection($wpdb, $config, 'MyAlias');
 ```
 
+`MyAlias` is the name for the class alias you want to use (like `MyAlias::table(...)` ), you can use whatever name (with Namespace also, `MyNamespace\\MyClass` ) you like or you may skip it if you don't need an alias. Alias gives you the ability to easily access the QueryBuilder class across your application.
+
+# Usage
+
+Once a connection is created, the builder can be accessed either directly using the Alias Facade or by creating an instance.
+
+## Static Usage
+
+The easiest way to use Pixie is to use the alias facade provided. This allows you to access a builder instance anywhere, much like WPDB. 
 
-There are many advanced options which are documented below. Sold? Let's install.
+```php
+// Create the connection early on.
+$connection = new Connection($wpdb, $config, 'Alias');
 
-## Installation
+// Insert some data to bar.
+Alias::table('bar')->insert(['column'=>'value']);
+```
+
+## None Static Usage
+
+When not using an alias you can instantiate the QueryBuilder handler separately, helpful for Dependency Injection and Testing.
+
+```PHP
+// Create connection and builder instance.
+$connection = new Connection($wpdb, $config);
+$qb = new QueryBuilderHandler($connection);
+
+$query = $qb->table('my_table')->where('name', '=', 'Sana');
+$results = $query->get();
+```
 
-Pixie uses [Composer](http://getcomposer.org/doc/00-intro.md#installation-nix) to make things easy.
+`$connection` here is optional, if not given it will always associate itself to the first connection, but it can be useful when you have multiple database connections.
 
-To install run `composer require gin0115/pixie-wpdb`
+# Credits
 
-Library on [Packagist](https://packagist.org/packages/gin0115/pixie-wpdb).
+This package began as a fork of [Pixie](https://github.com/usmanhalalit/pixie) originally written by [usmanhalalit](https://github.com/usmanhalalit)
+A few features have been inspired by the [Pecee-pixie](https://github.com/skipperbent/pecee-pixie/) fork and continuation, especially the extended aggregate methods.
 
-## Full Usage API
-For the full usage docs, please see the wiki.
 
 ## Changelog
+* 0.0.2 - Improvements to the `updateOrInsert()` method
 * 0.0.1 - Various external and interal changes made to the initial code written by [Muhammad Usman](http://usman.it/)
 ___
 If you find any typo then please edit and send a pull request.

src/QueryBuilder/QueryBuilderHandler.php

@@ -611,9 +611,9 @@ public function replace($data)
     /**
      * @param array<string, mixed> $data
      *
-     * @return int|null
+     * @return int|null Number of row effected, null for none.
      */
-    public function update($data)
+    public function update(array $data): ?int
     {
         $eventResult = $this->fireEvents('before-update');
         if (!is_null($eventResult)) {
@@ -625,23 +625,30 @@ public function update($data)
         $this->dbInstance()->get_results($preparedQuery);
         $this->fireEvents('after-update', $queryObject, $executionTime);
 
-        return 0 !== $this->dbInstance()->rows_affected
-            ? $this->dbInstance()->rows_affected
+        return 0 !== (int) $this->dbInstance()->rows_affected
+            ? (int) $this->dbInstance()->rows_affected
             : null;
     }
 
     /**
-     * @param array<string, mixed> $data
+     * Update or Insert based on the attributes.
+     *
+     * @param array<string, mixed> $attributes Conditions to check
+     * @param array<string, mixed> $values     Values to add/update
      *
-     * @return int|null will return row id for insert and bool for success/fail on update
+     * @return int|int[]|null will return row id(s) for insert and null for success/fail on update
      */
-    public function updateOrInsert($data)
+    public function updateOrInsert(array $attributes, array $values = [])
     {
-        if ($this->first()) {
-            return $this->update($data);
+        // Check if existing post exists.
+        $query = clone $this;
+        foreach ($attributes as $column => $value) {
+            $query->where($column, $value);
         }
 
-        return $this->insert($data);
+        return null !== $query->first()
+            ? $this->update(array_merge($values, $attributes))
+            : $this->insert(array_merge($values, $attributes));
     }
 
     /**

tests/QueryBuilderHandler/TestIntegrationWithWPDB.php

@@ -407,21 +407,38 @@ public function testUpdate()
     /** @testdox [WPDB] It should be possible to use updateOrInsert/upsert to either add a unique dataset or update an existing one. */
     public function testUpsert()
     {
+        $this->wpdb->insert('mock_foo', ['string' => 'first', 'number' => 12], ['%s', '%d']);
+
         $builder = $this->queryBuilderProvider();
 
-        // INSERT
-        $id = $builder->table('mock_foo')->updateOrInsert(['string' => 'first', 'number' => 24]);
+        // UPDATE (was 12, now 24)
+        $updated = $builder->table('mock_foo')->updateOrInsert(['string' => 'first' ], ['string' => 'first', 'number' => 24 ]);
+        $this->assertNotNull($updated);
+        $this->assertEquals(24, $builder->table('mock_foo')->find('first', 'string')->number);
+        $this->assertCount(1, $builder->table('mock_foo')->get());
+        // CREATE
+        $updated = $builder->table('mock_foo')->updateOrInsert(['string' => 'second' ], ['string' => 'second', 'number' => 42 ]);
+        $this->assertNotNull($updated);
+        $this->assertEquals(42, $builder->table('mock_foo')->find('second', 'string')->number);
+
+        // Should now be 2 rows.
+        $this->assertCount(2, $builder->table('mock_foo')->get());
+    }
 
-        // Check we actually inserted the row.
-        $this->assertTrue($id >= 1);
-        $this->assertEquals('first', $builder->table('mock_foo')->find(24, 'number')->string);
+    public function testUpsertWithAttributesMissingFromValues(): void
+    {
+        $this->wpdb->insert('mock_foo', ['string' => 'first', 'number' => 12], ['%s', '%d']);
+        $builder = $this->queryBuilderProvider();
 
-        // UPDATE
-        $updated = $builder->table('mock_foo')->updateOrInsert(['string' => 'second', 'number' => 24]);
+        // UPDATE (was 12, now 24)
+        $builder->table('mock_foo')->updateOrInsert(['string' => 'first' ], ['number' => 24 ]);
+        $this->assertEquals(24, $builder->table('mock_foo')->find('first', 'string')->number);
+        $this->assertCount(1, $builder->table('mock_foo')->get());
 
-        // Check we updated.
-        $this->assertEquals(1, $updated);
-        $this->assertEquals('second', $builder->table('mock_foo')->find(24, 'number')->string);
+        // CREATE
+        $builder->table('mock_foo')->updateOrInsert(['string' => 'second' ], ['number' => 42 ]);
+        $this->assertEquals(42, $builder->table('mock_foo')->find('second', 'string')->number);
+        $this->assertCount(2, $builder->table('mock_foo')->get());
     }
 
     /** @testdox [WPDB] It should be possible to create a query which deletes all rows based on the criteria */
@@ -434,7 +451,7 @@ public function testDeleteWhere(): void
         $builder = $this->queryBuilderProvider();
 
         // Remove all with a NUMBER of 2 or more.
-        $r = $builder->table('mock_foo')->where('number', '>=', 2)->delete();
+        $builder->table('mock_foo')->where('number', '>=', 2)->delete();
 
         // Check we only have the first value.
         $rows = $builder->table('mock_foo')->get();
@@ -774,5 +791,4 @@ public function testOnDuplicateKeyOnPirmaryKey(): void
         $this->assertEquals('me@me.com', $rows[0]->email);
         $this->assertEquals('15', $rows[0]->counter);
     }
-
 }

tests/Unit/TestEvents.php

@@ -224,11 +224,11 @@ public function testEventAfterInsert(): void
     public function testEventBeforeUpdateWillShortCircuitGet(): void
     {
         $events = $this->connection->getEventHandler();
-        $events->registerEvent(Event::BEFORE_UPDATE, 'foo', $this->createClosure('This should skip the query being executed.'));
+        $events->registerEvent(Event::BEFORE_UPDATE, 'foo', $this->createClosure(9999));
         $result = $this->queryBuilderProvider()->table('foo')->where('id', 1)->update(['bar' => 'baz']);
 
         $this->assertEmpty($this->wpdb->usage_log);
-        $this->assertEquals('This should skip the query being executed.', $result);
+        $this->assertEquals(9999, $result);
         $this->assertContains('before-updatefoo', Objects::get_property($events, 'firedEvents'));
     }