Playing editor with the docs

docs/EXTRAS_ORM.rst

@@ -1,15 +1,16 @@
 Miscellaneous 
 =============
 
-The items listed below are entirely optional and are intended to enhance
+The items listed below are optional and intended to enhance 
 integration between Zend Framework and Doctrine 2.
 
-ObjectExists and NoObjectExists Validators
-------------------------------------------
+ObjectExists Validator and  NoObjectExists Validator
+----------------------------------------------------
 
-The ObjectExists and NoObjectExists are validators similar to
-Zendvalidators. You can pass a variety of options to determine validity.
-The most basic use case requires an entity manager (em), an entity, and
+ObjectExists and NoObjectExists are validators similar to
+`Zend Validators <https://framework.zend.com/manual/2.4/en/modules/zend.validator.html>`_. 
+You can pass a variety of options to determine validity.
+The most basic use case requires an entity manager, an entity, and
 a field. You also have the option of specifying a query\_builder Closure
 to use if you want to fine tune the results.
 
@@ -18,18 +19,20 @@ to use if you want to fine tune the results.
     <?php
     $validator = new \DoctrineModule\Validator\NoObjectExists([
         // object repository to lookup
-        'object_repository' => $serviceLocator->get('Doctrine\ORM\EntityManager')->getRepository('My\Entity\User'),
+        'object_repository' => $serviceLocator->get('doctrine.entitymanager.orm_default')   
+            ->getRepository('Db\Entity\User'),
 
         // fields to match
         'fields' => ['username'],
     ]);
 
     // following works also with simple values if the number of fields to be matched is 1
-    echo $validator->isValid(['username' => 'test']) ? 'Valid' : 'Invalid! Duplicate found!';
+    echo $validator->isValid(['username' => 'test']) ? 'Valid' : 'Invalid. A duplicate was found.';
 
-Authentication adapter for ZendThe authentication adapter is intended to provide an adapter for ``Zend\Authentication``. It works much
---------------------------------------------------------------------------------------------------------------------------------------
+Authentication Adapter
+----------------------
 
+The authentication adapter is intended to provide an adapter for ``Zend\Authentication``. It works much
 like the ``DbTable`` adapter in the core framework. You must provide the
 entity manager instance, entity name, identity field, and credential
 field. You can optionally provide a callable method to perform hashing
@@ -38,13 +41,16 @@ on the password prior to checking for validation.
 .. code:: php
 
     <?php
-    $adapter = new \DoctrineModule\Authentication\Adapter\DoctrineObject(
-        $this->getLocator()->get('Doctrine\ORM\EntityManager'),
+    
+    use DoctrineModule\Authentication\Adapter\DoctrineObject as DoctrineObjectAdapter;
+    
+    $adapter = DoctrineObjectAdapter(
+        $entityManager,
         'Application\Test\Entity',
         'username', // optional, default shown
         'password',  // optional, default shown,
         function($identity, $credential) { // optional callable
-            return \My\Service\User::hashCredential(
+            return \Application\Service\User::hashCredential(
                 $credential,
                 $identity->getSalt(),
                 $identity->getAlgorithm()
@@ -53,16 +59,17 @@ on the password prior to checking for validation.
     );
 
     $adapter->setIdentityValue('admin');
-    $adapter->setCredentialValue('pa55w0rd');
+    $adapter->setCredentialValue('password');
     $result = $adapter->authenticate();
 
-    echo $result->isValid() ? 'Authenticated!' : 'Could not authenticate';
+    echo $result->isValid() ? 'Authenticated' : 'Could not authenticate';
+
 
 Custom DBAL Types
 -----------------
 
-To register custom Doctrine DBAL types, simply add them to the
-``doctrine.configuration.my_dbal_default.types`` key in you
+To register custom Doctrine DBAL types add them to the
+``doctrine.configuration.orm_default.types`` key in you
 configuration file:
 
 .. code:: php
@@ -84,7 +91,8 @@ configuration file:
         ],
     ];
 
-You are now able to use them, for example, in your ORM entities:
+With this configuration you may use them in your ORM entities
+to define field datatypes:
 
 .. code:: php
 
@@ -122,8 +130,8 @@ additionally register this mapping with your database platform.
         ],
     ];
 
-Now using Schema-Tool, whenever it detects a column having the "tinyint"
+Now using Schema-Tool, whenever it finds a column of type "tinyint"
 it will convert it into a "tinyint" Doctrine Type instance for Schema
 representation. Keep in mind that you can easily produce clashes this
-way, each database type can only map to exactly one Doctrine mapping
+way because each database type can only map to exactly one Doctrine mapping
 type.

docs/cache.rst

@@ -1,5 +1,11 @@
-Caching queries, results and metadata
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Caching
+=======
+
+Caching is very important in Doctrine.
+
+In this example for Metadata, Queries, and Results we set an array 
+cache for the result\_cache.  Please note the array cache is for 
+development only and shown here along side other cache types.
 
 If you want to set a cache for query, result and metadata, you can
 specify this inside your ``config/autoload/local.php``
@@ -19,11 +25,12 @@ specify this inside your ``config/autoload/local.php``
         ],
     ];
 
-The previous configuration take in consideration different cache
+The previous configuration takes into consideration different cache
 adapters. You can specify any other adapter that implements the
 ``Doctrine\Common\Cache\Cache`` interface. Find more
 `here <https://www.doctrine-project.org/projects/doctrine-orm/en/2.6/reference/caching.html>`__.
 
+
 Example with Redis
 ------------------
 
@@ -86,6 +93,7 @@ In this case you have to specify a custom factory in your
 Read more about
 `Caching <https://www.doctrine-project.org/projects/doctrine-orm/en/2.6/reference/caching.html>`__.
 
+
 How to enable and configure Second Level Cache
 ----------------------------------------------
 

docs/configuration.rst

@@ -1,8 +1,8 @@
 Configuration
 =============
 
-How to Register Custom DQL Functions
-------------------------------------
+Register a Custom DQL Function
+------------------------------
 
 .. code:: php
 
@@ -11,15 +11,16 @@ How to Register Custom DQL Functions
             'configuration' => [
                 'orm_default' => [
                     'numeric_functions' => [
-                        'ROUND' => 'path\to\my\query\round',
+                        'ROUND' => 'Db\DoctrineExtensions\Query\Mysql\Round',
                     ],
                 ],
             ],
         ],
     ];
 
-How to register type mapping
-----------------------------
+
+Register a Type mapping
+-----------------------
 
 .. code:: php
 
@@ -35,6 +36,7 @@ How to register type mapping
         ],
     ];
 
+
 How to add new type
 -------------------
 
@@ -45,7 +47,7 @@ How to add new type
             'configuration' => [
                 'orm_default' => [
                     'types' => [
-                        'mytype' => 'Application\Types\MyType',
+                        'newtype' => 'Db\DBAL\Types\NewType',
                     ],
                 ],
             ],
@@ -66,8 +68,11 @@ How to add new type
         ],
     ];
 
+
+Doctrine Type Comment
+---------------------
+
 Option to set the doctrine type comment (DC2Type:myType) for custom types
--------------------------------------------------------------------------
 
 .. code:: php
 
@@ -83,8 +88,11 @@ Option to set the doctrine type comment (DC2Type:myType) for custom types
         ],
     ];
 
+
+Built-in Resolver
+-----------------
+
 How to Define Relationships with Abstract Classes and Interfaces (ResolveTargetEntityListener)
------
 
 .. code:: php
 
@@ -101,7 +109,8 @@ How to Define Relationships with Abstract Classes and Interfaces (ResolveTargetE
         ],
     ];
 
-Set a custom default repository
+
+Set a Custom Default Repository
 -------------------------------
 
 .. code:: php
@@ -116,9 +125,12 @@ Set a custom default repository
         ],
     ];
 
+
 How to Use Two Connections
 --------------------------
 
+See also `this blog article<https://blog.tomhanderson.com/2016/03/zf2-doctrine-configure-second-object.html>`_.
+
 .. code:: php
 
     return [
@@ -203,6 +215,7 @@ will create the following objects as needed: \*
 
 You can retrieve them from the service manager via their keys.
 
+
 How to Use Naming Strategy
 --------------------------
 

docs/index.rst

@@ -1,6 +1,8 @@
 Doctrine ORM Module for Zend Framework
 ======================================
 
+This module works with Zend Framework 2 and 3.
+
 .. toctree::
     :caption: Table of Contents
 

docs/migrations.rst

@@ -1,5 +1,11 @@
-Configuring Doctrine Migrations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Doctrine Migrations
+===================
+
+Support for the migrations library is included.  Only one
+migration configuration is possible.
+
+Configure
+---------
 
 .. code:: php
 
@@ -18,3 +24,10 @@ Configuring Doctrine Migrations
         ],
     ];
 
+
+Multiple Migration Configurations
+---------------------------------
+
+At this time if you want to have migrations for multiple entity manager database configurations
+you must use the `.phar archive <https://github.com/doctrine/migrations/releases>`_ and
+external configuration files.