update docs

docs/_bookdown.json

@@ -1,10 +1,7 @@
 {
     "title": "Atlas.Pdo",
     "content": [
-        "getting-started.md",
-        "fetch.md",
-        "yield.md",
+        "connection.md",
         "connection-locator.md",
-        "upgrade.md"
     ]
 }

docs/connection-locator.md

@@ -2,39 +2,41 @@
 
 Some applications may multiple database servers; for example, one for writes, and one or more for reads. The _ConnectionLocator_ allows you to define multiple _Connection_ objects for lazy-loaded read and write connections. It will create the connections only when they are when called. The _Connection_ creation logic should be wrapped in factory callable.
 
-## Runtime Configuration
+## Instantiation
 
-First, create the _ConnectionLocator_:
+The easiest way to create a _ConnectionLoctor_ is to use its static  `new()` method, either with _PDO_ connection arguments, or with an actual _PDO_ instance:
 
 ```php
-use Atlas\Pdo\Connection;
 use Atlas\Pdo\ConnectionLocator;
 
-$connections = new ConnectionLocator();
-```
-
-Now add a default connection factory; this will be used when a read or write connection is not defined. (This is also useful for setting up connection location in advance of actually having multiple database servers.)
-
-```php
-$connections->setDefaultFactory(Connection::factory(
-    'mysql:host=default.db.localhost;dbname=database',
+// pass PDO constructor arguments ...
+$connectionLocator = ConnectionLocator::new(
+    'mysql:host=localhost;dbname=testdb',
     'username',
     'password'
-));
+);
+
+// ... or a PDO instance.
+$connectionLocator = ConnectionLocator::new($pdo);
 ```
 
-Next, add as many named read and write connection factories as you like:
+Doing so will define the default connection factory for the _ConnectionLocator_.
+
+
+## Runtime Configuration
+
+Once you have a _ConnectionLocator_, you can add as many named read and write connection factories as you like:
 
 ```php
 // the write (master) server
-$connections->setWriteFactory('master', Connection::factory(
+$connectionLocator->setWriteFactory('master', Connection::factory(
     'mysql:host=master.db.localhost;dbname=database',
     'username',
     'password'
 ));
 
 // read (slave) #1
-$connections->setReadFactory('slave1', Connection::factory(
+$connectionLocator->setReadFactory('slave1', Connection::factory(
     return new Connection(
         'mysql:host=slave1.db.localhost;dbname=database',
         'username',
@@ -43,36 +45,63 @@ $connections->setReadFactory('slave1', Connection::factory(
 });
 
 // read (slave) #2
-$connections->setReadFactory('slave2', Connection::factory(
+$connectionLocator->setReadFactory('slave2', Connection::factory(
     'mysql:host=slave2.db.localhost;dbname=database',
     'username',
     'password'
 ));
 
 // read (slave) #3
-$connections->setReadFactory('slave3', Connection::factory(
+$connectionLocator->setReadFactory('slave3', Connection::factory(
     'mysql:host=slave3.db.localhost;dbname=database',
     'username',
     'password'
 ));
 ```
 
-Finally, retrieve a connection from the locator when you need it. This will create the connection (if needed) and then return it.
+## Getting Connections
 
-- `getDefault()` will return the default _Connection_ instance.
+Retrieve a _Connection_ from the locator when you need it. This will create the _Connection_ (if needed) and then return it.
 
-- `getRead()` will return a named read _Connection_ instance. If no name is specified, it will return a random read _Connection_. If no read connections are defined, it will return the default _Connection_.
+- `getDefault()` will return the default _Connection_.
 
-- `getWrite()` will return a named write _Connection_. If no name is specified, it will return a random write _Connection_. If no write connections are defined, it will return the default _Connection_.
+- `getRead()` will return a random read _Connection_; after the first call, `getRead()` will always return the same _Connection_. (If no read _Connections_ are defined, it will return the default connection.)
+
+- `getWrite()` will return a random write _Connection_; after the first call, `getWrite()` will always return the same _Connection_. (If no read _Connections_ are defined, it will return the default connection.)
 
 ```php
-$read = $connections->getRead();
+$read = $connectionLocator->getRead();
 $results = $read->fetchAll('SELECT * FROM table_name LIMIT 10');
+
+$readAgain = $connectionLocator->getRead();
+assert($read === $readAgain); // true
 ```
 
+You can get any read or write connection directly by name using the `get()` method:
+
+```php
+$foo = $connectionLocator->get(ConnectionLocator::READ, 'foo');
+$bar = $connectionLocator->get(ConnectionLocator::WRITE, 'bar');
+```
+
+## Locking To The Write Connection
+
+If you call the `lockToWrite()` method, calls to `getRead()` will return the write connection instead of the read connection.
+
+```php
+$read = $connectionLocator->getRead();
+$write = $connectionLocator->getWrite();
+
+$connectionLocator->lockToWrite();
+$readAgain = $connectionLocator->getRead();
+assert($readAgain === $write); // true
+```
+
+You can disable the lock-to-write behavior by calling `lockToWrite(false)`.
+
 ## Construction-Time Configuration
 
-The _ConnectionLocator_ can be configured with all its connections at construction time; this is useful with dependency injection mechanisms.
+The _ConnectionLocator_ can be configured with all its connections at construction time; this can be useful with dependency injection mechanisms. (Note that this requires using the constructor proper, not the static `new()` method.)
 
 ```php
 use Atlas\Pdo\Connection;
@@ -114,5 +143,5 @@ $write = [
 ];
 
 // configure locator at construction time
-$connections = new ConnectionLocator($default, $read, $write);
+$connectionLocator = new ConnectionLocator($default, $read, $write);
 ```

docs/connection.md

@@ -1,22 +1,21 @@
-# Getting Started
+# Connection
 
 ## Instantiation
 
-Instantiate a _Connection_ with an existing PDO instance:
+The easiest way to create a _Connection_ is to use its static  `new()` method, either with _PDO_ connection arguments, or with an actual _PDO_ instance:
 
 ```php
 use Atlas\Pdo\Connection;
 
-$pdo = new PDO('sqlite::memory:');
-$connection = new Connection($pdo);
-```
-
-Alternatively, use the `Connection::new()` method to create the _Connection_ PDO instance for you:
-
-```php
-use Atlas\Pdo\Connection;
+// pass PDO constructor arguments ...
+$connection = Connection::new(
+    'mysql:host=localhost;dbname=testdb',
+    'username',
+    'password'
+);
 
-$connection = Connection::new('sqlite::memory:');
+// ... or a PDO instance.
+$connection = Connection::new($pdo);
 ```
 
 If you need a callable factory to create a _Connection_ and its PDO instance at a later time, such as in a service container, you can use the `Connection::factory()` method:
@@ -102,6 +101,14 @@ $result = $connection->fetchGroup($stm, $bind, $style = PDO::FETCH_COLUMN)
 
 Set `$style` to `PDO::FETCH_NAMED` when values are an array (i.e. there are more than two columns in the select).
 
+### fetchKeyPair()
+
+The `fetchKeyPair()` method returns an associative array where each key is the first column and each value is the second column
+
+```php
+$result = $connection->fetchKeyPair($stm, $bind);
+```
+
 ### fetchObject()
 
 The `fetchObject()` method returns the first row as an object of your choosing; the columns are mapped to object properties. an optional 4th parameter array provides constructor arguments when instantiating the object.
@@ -126,14 +133,6 @@ The `fetchOne()` method returns the first row as an associative array where the
 $result = $connection->fetchOne($stm, $bind);
 ```
 
-### fetchKeyPair()
-
-The `fetchKeyPair()` method returns an associative array where each key is the first column and each value is the second column
-
-```php
-$result = $connection->fetchKeyPair($stm, $bind);
-```
-
 ### fetchUnique()
 
 The `fetchUnique()` method returns an associative array of all rows where the key is the value of the first column, and the row arrays are keyed on the remaining column names.
@@ -175,24 +174,24 @@ foreach ($connection->yieldColumn($stm, $bind) as $val) {
 }
 ```
 
-### yieldObjects()
+### yieldKeyPair()
 
-This is the yielding equivalent of `fetchObjects()`.
+This is the yielding equivalent of `fetchKeyPair()`.
 
 ```php
-$class = 'ClassName';
-$args = ['arg0', 'arg1', 'arg2'];
-foreach ($connection->yieldObjects($stm, $bind, $class, $args) as $object) {
+foreach ($connection->yieldPairs($stm, $bind) as $key => $val) {
     // ...
 }
 ```
 
-### yieldPairs()
+### yieldObjects()
 
-This is the yielding equivalent of `fetchKeyPair()`.
+This is the yielding equivalent of `fetchObjects()`.
 
 ```php
-foreach ($connection->yieldPairs($stm, $bind) as $key => $val) {
+$class = 'ClassName';
+$args = ['arg0', 'arg1', 'arg2'];
+foreach ($connection->yieldObjects($stm, $bind, $class, $args) as $object) {
     // ...
 }
 ```