Readme and docs updates (#6)

Author: mikegioia

CHANGELOG.md

@@ -1,5 +1,9 @@
 ### Changelog
 
+##### v2.1.1
++ Updated `README` and docs contents
+  - Cleaned up the php examples and content
+
 ##### v2.1.0
 + Updated internal tools php-cs-fixer and phpstan
   - Cleared all phpstan errors up to level 8 (max)

README.md

@@ -4,7 +4,7 @@
 [![Latest Stable Version](https://poser.pugx.org/ParticleBits/pdo/v/stable)](https://packagist.org/packages/ParticleBits/pdo)
 [![License](https://poser.pugx.org/ParticleBits/pdo/license)](https://packagist.org/packages/ParticleBits/pdo)
 
-Smallest possible PDO database while being super useful
+Smallest possible PDO database while still being super useful
 
 ### Installation
 
@@ -16,11 +16,16 @@ Use [Composer](https://getcomposer.org/)
 }
 ```
 
-Compatible with PHP 5.6 and higher. Tested on all versions of PHP 5.6 and higher.
+### Features
+
+ * Compatible with PHP 5.6 and higher!
+ * Tested on all versions of PHP 5.6 -> 7.4 _(Not tested yet on PHP 8.x)_
+ * No dependencies other than the PDO extension
+ * Tiny footprint
 
 ### Usage
 
-Examples selecting, inserting, updating and deleting data from or into `users` table.
+Examples selecting, inserting, updating and deleting data from or into the `users` table.
 
 ```php
 require_once 'vendor/autoload.php';
@@ -32,36 +37,42 @@ $pwd = 'your_db_password';
 $pdo = new \Pb\PDO\Database($dsn, $usr, $pwd);
 
 // SELECT * FROM users WHERE id = ?
-$selectStatement = $pdo->select()
-                       ->from('users')
-                       ->where('id', '=', 1234);
+$stmt = $pdo
+    ->select()
+    ->from('users')
+    ->where('id', '=', 1234)
+    ->execute();
 
-$stmt = $selectStatement->execute();
 $data = $stmt->fetch();
 
-// INSERT INTO users ( id , usr , pwd ) VALUES ( ? , ? , ? )
-$insertStatement = $pdo->insert(['id', 'usr', 'pwd'])
-                       ->into('users')
-                       ->values([1234, 'your_username', 'your_password']);
+// INSERT INTO users (id , usr , pwd) VALUES (? , ? , ?)
+$stmt = $pdo
+    ->insert(['id', 'usr', 'pwd'])
+    ->into('users')
+    ->values([1234, 'your_username', 'your_password']);
 
-$insertId = $insertStatement->execute(false);
+$insertId = $stmt->execute(true); // true returns insert ID
 
 // UPDATE users SET pwd = ? WHERE id = ?
-$updateStatement = $pdo->update(['pwd' => 'your_new_password'])
-                       ->table('users')
-                       ->where('id', '=', 1234);
+$stmt = $pdo
+    ->update(['pwd' => 'your_new_password'])
+    ->table('users')
+    ->where('id', '=', 1234);
 
-$affectedRows = $updateStatement->execute();
+$affectedRows = $stmt->execute();
 
 // DELETE FROM users WHERE id = ?
-$deleteStatement = $pdo->delete()
-                       ->from('users')
-                       ->where('id', '=', 1234);
+$stmt = $pdo
+    ->delete()
+    ->from('users')
+    ->where('id', '=', 1234);
 
-$affectedRows = $deleteStatement->execute();
+$affectedRows = $stmt->execute();
 ```
 
-> The `sqlsrv` extension will fail to connect when using error mode `PDO::ERRMODE_EXCEPTION` (default). To connect, you will need to explicitly pass `array(PDO::ATTR_ERRMODE => PDO::ERRMODE_WARNING)` (or `PDO::ERRMODE_SILENT`) into the constructor, or override the `getDefaultOptions()` method when using `sqlsrv`.
+### Notes on the `sqlsrv` extension
+
+The `sqlsrv` extension will fail to connect when using error mode `PDO::ERRMODE_EXCEPTION` (default). To connect, you will need to explicitly pass `array(PDO::ATTR_ERRMODE => PDO::ERRMODE_WARNING)` (or `PDO::ERRMODE_SILENT`) into the constructor, or override the `getDefaultOptions()` method when using `sqlsrv`.
 
 ### Documentation
 

docs/AGGREGATES.md

@@ -1,6 +1,6 @@
 # Aggregates
 
-> Used only in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md) statements.
+Used only in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md) statements.
 
 ### Methods
 
@@ -53,13 +53,13 @@ Parameter | Type | Default | Description
 // ... COUNT( * )
 $selectStatement->count();
 
-// ... COUNT( votes ) AS all_votes
+// ... COUNT(votes) AS all_votes
 $selectStatement->count('votes', 'all_votes');
 
-// ... COUNT( DISTINCT customer_id )
+// ... COUNT(DISTINCT customer_id)
 $selectStatement->distinctCount('customer_id');
 
-// ... MIN|MAX( salary ) , AVG( price ) , SUM( votes )
+// ... MIN|MAX(salary), AVG(price), SUM(votes)
 $selectStatement->min('salary');
 $selectStatement->max('salary');
 $selectStatement->avg('price');

docs/Clause/GROUP_BY.md

@@ -1,6 +1,6 @@
 # GROUP BY clause
 
-> Used only in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md) statements.
+Used only in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md) statements.
 
 ### Methods
 
@@ -21,6 +21,5 @@ $selectStatement->groupBy('f_name');
 // ... GROUP BY f_name, l_name
 $selectStatement->groupBy(['f_name', 'l_name']);
 // or
-$selectStatement->groupBy('f_name')
-                ->groupBy('l_name');
+$selectStatement->groupBy('f_name')->groupBy('l_name');
 ```

docs/Clause/HAVING.md

@@ -1,6 +1,6 @@
 # HAVING clause
 
-> Used only in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md) statements.
+Used only in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md) statements.
 
 ### Methods
 

docs/Clause/JOIN.md

@@ -1,6 +1,6 @@
 # JOIN clause
 
-> Used only in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md) statements.
+Used only in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md) statements.
 
 ### Methods
 

docs/Clause/LIMIT.md

@@ -1,6 +1,6 @@
 # LIMIT clause
 
-> Used in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md), [UPDATE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/UPDATE.md) and [DELETE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/DELETE.md) statements.
+Used in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md), [UPDATE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/UPDATE.md) and [DELETE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/DELETE.md) statements.
 
 ### Methods
 

docs/Clause/OFFSET.md

@@ -1,6 +1,6 @@
 # OFFSET clause
 
-> Used only in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md) statements.
+Used only in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md) statements.
 
 ### Methods
 

docs/Clause/ORDER_BY.md

@@ -1,6 +1,6 @@
 # ORDER BY clause
 
-> Used in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md), [UPDATE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/UPDATE.md) and [DELETE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/DELETE.md) statements.
+Used in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md), [UPDATE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/UPDATE.md) and [DELETE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/DELETE.md) statements.
 
 ### Methods
 

docs/Clause/WHERE.md

@@ -1,6 +1,6 @@
 # WHERE clause
 
-> Used in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md), [UPDATE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/UPDATE.md) and [DELETE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/DELETE.md) statements.
+Used in [SELECT](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/SELECT.md), [UPDATE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/UPDATE.md) and [DELETE](https://github.com/ParticleBits/PDO/blob/master/docs/Statement/DELETE.md) statements.
 
 ### Methods
 
@@ -143,35 +143,35 @@ Parameter | Type | Default | Description
 
 ```php
 // ... WHERE usr = ? OR f_name = ?
-$statement->where('usr', '=', 'FaaPz')
-          ->orWhere('f_name', '=', 'Fabian');
+$stmt->where('usr', '=', 'foobar')
+    ->orWhere('f_name', '=', 'Foo');
 
 // ... WHERE customer_id BETWEEN ? AND ?
-$statement->whereBetween('customer_id', [110, 220]);
+$stmt->whereBetween('customer_id', [110, 220]);
 
 // ... WHERE customer_id NOT BETWEEN ? AND ?
-$statement->whereNotBetween('customer_id', [330, 440]);
+$stmt->whereNotBetween('customer_id', [330, 440]);
 
-// ... WHERE customer_id IN ( ?, ?, ?, ? )
-$statement->whereIn('customer_id', [110, 120, 130, 140 ]);
+// ... WHERE customer_id IN (?, ?, ?, ?)
+$stmt->whereIn('customer_id', [110, 120, 130, 140 ]);
 
-// ... WHERE customer_id NOT IN ( ?, ?, ?, ? )
-$statement->whereNotIn('customer_id', [112, 124, 136, 148 ]);
+// ... WHERE customer_id NOT IN (?, ?, ?, ?)
+$stmt->whereNotIn('customer_id', [112, 124, 136, 148 ]);
 
 // ... WHERE f_name LIKE ?
-$statement->whereLike('f_name', 'Fab___');
+$stmt->whereLike('f_name', 'Foo');
 
 // ... WHERE l_name NOT LIKE ?
-$statement->whereNotLike('l_name', 'Lae%');
+$stmt->whereNotLike('l_name', 'Bar%');
 
 // ... WHERE f_name IS NULL
-$statement->whereNull('f_name');
+$stmt->whereNull('f_name');
 
 // ... WHERE l_name IS NOT NULL
-$statement->whereNotNull('l_name');
+$stmt->whereNotNull('l_name');
 
 // ... WHERE col_1 = ? AND col_2 = ? AND col_3 = ?
-$statement->whereMany(
+$stmt->whereMany(
     [
         'col_1' => 'val_1',
         'col_2' => 'val_2',

docs/README.md

@@ -1,6 +1,6 @@
 # Documentation
 
-> **IMPORTANT!** Before reading through the following commands and methods, please be aware that it is possible to use raw PDO stuff, like `fetch()`, `fetchAll()`, `execute()` and the others whenever you feel you need to.
+**IMPORTANT!** Before reading through the following commands and methods, please be aware that it is possible to use raw PDO stuff, like `fetch()`, `fetchAll()`, `execute()` and the others whenever you feel you need to.
 
 ### Statements
 

docs/Statement/DELETE.md

@@ -20,9 +20,10 @@ Parameter | Type | Default | Description
 
 ```php
 // DELETE FROM users WHERE id = ?
-$deleteStatement = $db->delete()
-                      ->from('users')
-                      ->where('id', '=', 1234);
+$stmt = $db
+    ->delete()
+    ->from('users')
+    ->where('id', '=', 1234);
 
-$affectedRows = $deleteStatement->execute();
+$affectedRows = $stmt->execute();
 ```

docs/Statement/INSERT.md

@@ -29,16 +29,19 @@ Parameter | Type | Default | Description
 ### Examples
 
 ```php
-// INSERT INTO users ( usr , pwd ) VALUES ( ? , ? )
-$insertStatement = $db->insert(['usr', 'pwd'])
-                      ->into('users')
-                      ->values(['usr_1', 'pwd_1']);
-
-// INSERT INTO users ( id , usr , pwd ) VALUES ( ? , ? , ? )
-$insertStatement = $db->insert(['id'])
-                      ->into('users')
-                      ->columns(['usr', 'pwd'])
-                      ->values([1234, 'usr_1234', 'pwd_1234']);
-
-$insertId = $insertStatement->execute(false);
+// INSERT INTO users (usr , pwd) VALUES (? , ?)
+$stmt = $db
+    ->insert(['usr', 'pwd'])
+    ->into('users')
+    ->values(['usr_1', 'pwd_1']);
+
+// INSERT INTO users (id , usr , pwd) VALUES (? , ? , ?)
+$stmt = $db
+    ->insert(['id'])
+    ->into('users')
+    ->columns(['usr', 'pwd'])
+    ->values([1234, 'usr_1234', 'pwd_1234']);
+
+$insertId = $stmt->execute(true); // returns string ID of new row
+$pdoStmt = $stmt->execute(false); // returns \PDOStatement
 ```

docs/Statement/INSERT_MULTI.md

@@ -36,34 +36,20 @@ Parameter | Type | Default | Description
 
 ### Examples
 
-```php
-// INSERT INTO users ( id , usr , pwd ) VALUES ( ? , ? , ? )
-$insertStatement = $db->insert(['id', 'usr', 'pwd'])
-                      ->into('users')
-                      ->values([1234, 'your_username', 'your_password']);
-
-// INSERT INTO users ( id , usr , pwd ) VALUES ( ? , ? , ? )
-$insertStatement = $db->insert(['id'])
-                      ->into('users')
-                      ->columns(['usr', 'pwd'])
-                      ->values([1234, 'your_username', 'your_password']);
-
-$insertId = $insertStatement->execute(false);
-```
-
 #### Inserting multiple rows at once
 
 ```php
-// INSERT INTO users ( usr, pwd ) VALUES ( ? , ? )
-// ON DUPLICATE KEY UPDATE pwd = VALUES( pwd )
-$insertStatement = $db->insertMulti(['usr', 'pwd'])
-                      ->into('users')
-                      ->values(
-                          ['usr_1', 'pwd_1'],
-                          ['usr_2', 'pwd_2'],
-                          ['usr_3', 'pwd_3'])
-                      ->addRow(['usr_4', 'pwd_4'])
-                      ->onDuplicateKeyUpdate(['pwd']);
-
-$affectedRows = $insertStatement->execute();
+// INSERT INTO users (usr, pwd) VALUES (? , ?)
+// ON DUPLICATE KEY UPDATE pwd = VALUES (pwd)
+$stmt = $db
+    ->insertMulti(['usr', 'pwd'])
+    ->into('users')
+    ->values(
+        ['usr_1', 'pwd_1'],
+        ['usr_2', 'pwd_2'],
+        ['usr_3', 'pwd_3']
+    )->addRow(['usr_4', 'pwd_4'])
+    ->onDuplicateKeyUpdate(['pwd']);
+
+$affectedRows = $stmt->execute(); // returns int
 ```

docs/Statement/SELECT.md

@@ -179,10 +179,11 @@ Parameter | Type | Default | Description
 
 ```php
 // SELECT * FROM users WHERE id = ?
-$selectStatement = $db->select()
-                      ->from('users')
-                      ->where('id', '=', 1234);
+$stmt = $db
+    ->select()
+    ->from('users')
+    ->where('id', '=', 1234)
+    ->execute(); // \PDOStatement
 
-$stmt = $selectStatement->execute();
 $data = $stmt->fetch();
 ```

docs/Statement/UPDATE.md

@@ -26,15 +26,17 @@ Parameter | Type | Default | Description
 
 ```php
 // UPDATE users SET pwd = ? WHERE id = ?
-$updateStatement = $db->update(['pwd' => 'your_new_password'])
-                      ->table('users')
-                      ->where('id', '=', 1234);
+$stmt = $db
+    ->update(['pwd' => 'your_new_password'])
+    ->table('users')
+    ->where('id', '=', 1234);
 
 // UPDATE users SET usr = ? , pwd = ? WHERE id = ?
-$updateStatement = $db->update(['usr' => 'your_new_username'])
-                      ->set(['pwd' => 'your_new_password'])
-                      ->table('users')
-                      ->where('id', '=', 1234);
+$stmt = $db
+    ->update(['usr' => 'your_new_username'])
+    ->set(['pwd' => 'your_new_password'])
+    ->table('users')
+    ->where('id', '=', 1234);
 
-$affectedRows = $updateStatement->execute();
+$affectedRows = $stmt->execute();
 ```