Merge pull request #101 from php-db/documentation-improvements

Documentation improvements

Author: simon-mundy

.markdownlint.json

@@ -0,0 +1,6 @@
+{
+  "MD007": { "indent": 4 },
+  "MD013": false,
+  "MD033": false,
+  "MD060": false
+}

docs/book/adapter.md

@@ -1,21 +1,14 @@
 # AdapterAwareTrait
 
-The trait `PhpDb\Adapter\AdapterAwareTrait`, which provides implementation
-for `PhpDb\Adapter\AdapterAwareInterface`, and allowed removal of
-duplicated implementations in several components of Laminas or in custom
-applications.
-
-The interface defines only the method `setDbAdapter()` with one parameter for an
-instance of `PhpDb\Adapter\Adapter`:
+`PhpDb\Adapter\AdapterAwareTrait` provides a standard implementation of
+`AdapterAwareInterface` for injecting database adapters into your classes.
 
 ```php
 public function setDbAdapter(\PhpDb\Adapter\Adapter $adapter) : self;
 ```
 
 ## Basic Usage
 
-### Create Class and Add Trait
-
 ```php
 use PhpDb\Adapter\AdapterAwareTrait;
 use PhpDb\Adapter\AdapterAwareInterface;
@@ -24,28 +17,17 @@ class Example implements AdapterAwareInterface
 {
     use AdapterAwareTrait;
 }
-```
-
-### Create and Set Adapter
-
-[Create a database adapter](../adapter.md#creating-an-adapter-using-configuration) and set the adapter to the instance of the `Example`
-class:
-
-```php
-$adapter = new PhpDb\Adapter\Adapter([
-    'driver'   => 'Pdo_Sqlite',
-    'database' => 'path/to/sqlite.db',
-]);
 
+// Set adapter (see adapter.md for creation)
 $example = new Example();
-$example->setAdapter($adapter);
+$example->setDbAdapter($adapter);
 ```
 
 ## AdapterServiceDelegator
 
 The [delegator](https://docs.laminas.dev/laminas-servicemanager/delegators/)
-`PhpDb\Adapter\AdapterServiceDelegator` can be used to set a database
-adapter via the [service manager of laminas-servicemanager](https://docs.laminas.dev/laminas-servicemanager/quick-start/).
+`PhpDb\Adapter\AdapterServiceDelegator` can be used to set a database adapter
+via the [service manager of laminas-servicemanager](https://docs.laminas.dev/laminas-servicemanager/quick-start/).
 
 The delegator tries to fetch a database adapter via the name
 `PhpDb\Adapter\AdapterInterface` from the service container and sets the
@@ -54,8 +36,9 @@ adapter to the requested service. The adapter itself must be an instance of
 
 > ### Integration for Mezzio and laminas-mvc based Applications
 >
-> In a Mezzio or laminas-mvc based application the database adapter is already
-> registered during the installation with the laminas-component-installer.
+> In a Mezzio or laminas-mvc based application the database adapter is
+> already registered during the installation with the
+> laminas-component-installer.
 
 ### Create Class and Use Trait
 
@@ -80,23 +63,29 @@ class Example implements AdapterAwareInterface
 
 ### Create and Configure Service Manager
 
-Create and [configured the service manager](https://docs.laminas.dev/laminas-servicemanager/configuring-the-service-manager/):
+Create and [configure the service manager](
+https://docs.laminas.dev/laminas-servicemanager/configuring-the-service-manager/):
 
 ```php
-use Interop\Container\ContainerInterface;
+use Psr\Container\ContainerInterface;
+use PhpDb\Adapter\Adapter;
 use PhpDb\Adapter\AdapterInterface;
 use PhpDb\Adapter\AdapterServiceDelegator;
 use PhpDb\Adapter\AdapterAwareTrait;
 use PhpDb\Adapter\AdapterAwareInterface;
+use PhpDb\Sqlite\Driver\Sqlite;
+use PhpDb\Sqlite\Platform\Sqlite as SqlitePlatform;
 
 $serviceManager = new Laminas\ServiceManager\ServiceManager([
     'factories' => [
         // Database adapter
-        AdapterInterface::class => static function(ContainerInterface $container) {
-            return new PhpDb\Adapter\Adapter([
-                'driver'   => 'Pdo_Sqlite',
+        AdapterInterface::class => static function(
+            ContainerInterface $container
+        ) {
+            $driver = new Sqlite([
                 'database' => 'path/to/sqlite.db',
             ]);
+            return new Adapter($driver, new SqlitePlatform());
         }
     ],
     'invokables' => [
@@ -114,18 +103,19 @@ $serviceManager = new Laminas\ServiceManager\ServiceManager([
 
 ### Get Instance of Class
 
-[Retrieving an instance](https://docs.laminas.dev/laminas-servicemanager/quick-start/#3-retrieving-objects)
+[Retrieving an instance](
+https://docs.laminas.dev/laminas-servicemanager/quick-start/#3-retrieving-objects)
 of the `Example` class with a database adapter:
 
 ```php
 /** @var Example $example */
 $example = $serviceManager->get(Example::class);
 
-var_dump($example->getAdapter() instanceof PhpDb\Adapter\Adapter); // true
+var_dump(
+    $example->getAdapter() instanceof PhpDb\Adapter\AdapterInterface
+); // true
 ```
 
-## Concrete Implementations
-
-The validators [`Db\RecordExists` and `Db\NoRecordExists`](https://docs.laminas.dev/laminas-validator/validators/db/)
-implements the trait and the plugin manager of [laminas-validator](https://docs.laminas.dev/laminas-validator/)
-includes the delegator to set the database adapter for both validators.
+The [laminas-validator](
+https://docs.laminas.dev/laminas-validator/validators/db/)
+`Db\RecordExists` and `Db\NoRecordExists` validators use this pattern.