Rearrange docs

docs/auth.rst

@@ -177,4 +177,4 @@ Authentication usage is covered by
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst

docs/caching.rst

@@ -33,4 +33,4 @@ implement ``Doctrine\Common\Cache\Cache`` or extend ``Doctrine\Common\Cache\Cach
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst

docs/configuration.rst

@@ -2,7 +2,7 @@
 Config File
 ===========
 
-This is an overview of all of the options provided in `~/config/doctrine.php`
+This is an overview of the options provided in `~/config/doctrine.php`
 
 
 Entity Manager
@@ -37,7 +37,7 @@ Within the entity manager name array are configuration settings.  These are
 * ``meta`` - The type of metadata configuration.  Valid values are
   ``attributes``, ``xml``, ``simplified_xml``, ``static_php``, ``php``.
   The majority of configurations use ``attributes`` or ``xml`` and these
-  metadata configurtions are recommended.
+  metadata configurations are recommended.
 * ``namespaces`` - If your entities are not located in the configured app
   namespace, you can specify a different one here.
 * ``naming_strategy`` - Default is the included Laravel naming strategy.
@@ -79,32 +79,29 @@ array.
 Example configuration
 
 .. code-block:: php
-  'managers'                  => [
+  'managers' => [
       'default' => [
-          'dev'        => env('APP_DEBUG'),
-          'meta'       => env('DOCTRINE_METADATA', 'attributes'),
+          'dev' => env('APP_DEBUG', false),
           'connection' => env('DB_CONNECTION', 'mysql'),
-          'namespaces' => [
-              'App'
-          ],
-          'paths'      => [
-              base_path('app')
-          ],
+          'meta' => env('DOCTRINE_METADATA', 'xml'),
+          'paths' => [__DIR__ . '/doctrine-orm-metadata'],
           'repository' => Doctrine\ORM\EntityRepository::class,
-          'proxies'    => [
-              'namespace'     => false,
-              'path'          => storage_path('proxies'),
+          'logger' => env('DOCTRINE_LOGGER', false),
+          'proxies' => [
+              'namespace' => false,
+              'path' => storage_path('proxies'),
               'auto_generate' => env('DOCTRINE_PROXY_AUTOGENERATE', false)
           ],
           'events' => ...
           'filters' => ...
-      ]
-  ]
+      ],
+  ],
+
 
 Namespace Alias
 ===============
 
-To use namespace alias, you just have to specify then as key of each namespace.
+To use namespace alias, specify the alias as key of each namespace.
 
 Example:
 
@@ -144,7 +141,7 @@ Extensions
 ==========
 
 Extensions can be enabled by adding them to this array. They provide additional
-functionality Entities (Timestamps, Loggable, etc.)
+functionality to entities (Timestamps, Loggable, etc.)
 
 To use the extensions in this sample you must install the extensions package.
 
@@ -157,17 +154,17 @@ and follow the
 
 .. code-block:: php
 
-  'extensions'                => [
-      //LaravelDoctrine\ORM\Extensions\TablePrefix\TablePrefixExtension::class,
-      //LaravelDoctrine\Extensions\Timestamps\TimestampableExtension::class,
-      //LaravelDoctrine\Extensions\SoftDeletes\SoftDeleteableExtension::class,
-      //LaravelDoctrine\Extensions\Sluggable\SluggableExtension::class,
-      //LaravelDoctrine\Extensions\Sortable\SortableExtension::class,
-      //LaravelDoctrine\Extensions\Tree\TreeExtension::class,
-      //LaravelDoctrine\Extensions\Loggable\LoggableExtension::class,
-      //LaravelDoctrine\Extensions\Blameable\BlameableExtension::class,
-      //LaravelDoctrine\Extensions\IpTraceable\IpTraceableExtension::class,
-      //LaravelDoctrine\Extensions\Translatable\TranslatableExtension::class
+  'extensions' => [
+      LaravelDoctrine\ORM\Extensions\TablePrefix\TablePrefixExtension::class,
+      LaravelDoctrine\Extensions\Timestamps\TimestampableExtension::class,
+      LaravelDoctrine\Extensions\SoftDeletes\SoftDeleteableExtension::class,
+      LaravelDoctrine\Extensions\Sluggable\SluggableExtension::class,
+      LaravelDoctrine\Extensions\Sortable\SortableExtension::class,
+      LaravelDoctrine\Extensions\Tree\TreeExtension::class,
+      LaravelDoctrine\Extensions\Loggable\LoggableExtension::class,
+      LaravelDoctrine\Extensions\Blameable\BlameableExtension::class,
+      LaravelDoctrine\Extensions\IpTraceable\IpTraceableExtension::class,
+      LaravelDoctrine\Extensions\Translatable\TranslatableExtension::class
   ],
 
 
@@ -270,7 +267,7 @@ Cache
 
 Caches will be used to cache metadata, results, and queries.
 
-Available cache providers
+Available cache providers:
 
 * apc
 * array
@@ -318,4 +315,4 @@ and follow the
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst

docs/connections.rst

@@ -48,4 +48,4 @@ You can find the available connection parameters inside the
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst

docs/console.rst

@@ -23,4 +23,4 @@ Many artisan commands are included in this repository.
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst

docs/default-table-options.rst

@@ -42,4 +42,4 @@ Modify your ``database.php`` configuration file to include the
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst

docs/doctrine-manager.rst

@@ -69,4 +69,4 @@ Additionally, you can write your own custom manager by implementing
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst

docs/entities.rst

@@ -115,7 +115,71 @@ The related `Theory` entity looks like this:
   }
 
 
+Metadata
+========
+
+Because Doctrine entities do not extend any smart ancestor class, we have to tell
+Doctrine how to map the data from the database into the entity. There are
+multiple ways of doing this.
+
+
+Attributes
+----------
+
+Attributes mean that you will use attributes
+to indicate the column mappings.
+
+.. code-block:: php
+
+ namespace App\Doctrine\ORM\Entity;
+
+  use Doctrine\ORM\Mapping as ORM;
+
+  #[ORM\Entity]
+  #[ORM\Table(name: "articles")]
+  class Article
+  {
+      #[ORM\Id]
+      #[ORM\Column(type: "integer")]
+      #[ORM\GeneratedValue(strategy: "AUTO")]
+      private $id;
+
+      #[ORM\Column(type: "string", nullable: false)]
+      private $title;
+  }
+
+
+More about the attributes driver:
+https://www.doctrine-project.org/projects/doctrine-orm/en/2.11/reference/attributes-reference.html
+
+
+XML
+---
+
+Another option are XML mappings. It's better to change the
+metadata paths to something like ``config_path('doctrine_orm_metadata')``
+for your xml files.
+
+App.Doctrine.ORM.Entity.Article.dcm.xml
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+    <entity name="App\Doctrine\ORM\Entity\Article" table="articles">
+      <id name="id" type="integer">
+        <generator strategy="AUTO"/>
+      </id>
+      <field name="title" type="string" nullable="false"/>
+    </entity>
+  </doctrine-mapping>
+
+
+More information about XML mappings:
+https://www.doctrine-project.org/projects/doctrine-orm/en/2.6/reference/xml-mapping.html
+
+
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst

docs/entity-manager.rst

@@ -11,7 +11,7 @@ Using the EntityManager
 Facade
 ------
 
-You can use the ``EntityManager`` facade to access the `EntityManager` methods
+You can use the ``EntityManager`` facade to access the `EntityManager` methods.
 
 .. code_block:: php
 
@@ -33,11 +33,11 @@ Dependency Injection
 
 .. code-block:: php
 
-  use Doctrine\ORM\EntityManagerInterface;
+  use Doctrine\ORM\EntityManager;
 
   class ExampleController extends Controller
   {
-      public function __construct(protected EntityManagerInterface $em)
+      public function __construct(protected EntityManager $entityManager)
       {
       }
   }
@@ -46,21 +46,24 @@ Dependency Injection
 Multiple connections
 --------------------
 
-If you are using multiple managers, ``EntityManagerInterface`` will only return
-the default connection.  If you want to have control over which EnityManager
-you want, you'll have to inject ``Doctrine\Common\Persistence\ManagerRegistry``
+If you are using multiple entity managers, dependency injection will only return
+the default entity manager.  For control over which
+entity manager you want, you'll have to inject
+``Doctrine\Common\Persistence\ManagerRegistry``
 
 
 .. code-block:: php
+
   use Doctrine\Common\Persistence\ManagerRegistry;
+  use Doctrine\ORM\EntityManager;
 
   class ExampleController extends Controller
   {
-      protected $em;
+      protected EntityManager $entityManager;
 
-      public function __construct(ManagerRegistry $em)
+      public function __construct(protected ManagerRegistry $managerRegistry)
       {
-          $this->em = $em->getManager('otherConnection');
+          $this->em = $managerRegistry->getManager('second');
       }
   }
 
@@ -70,8 +73,8 @@ Finding entities
 
 .. note::
 
-    For making the examples more expressive, we will use the facade.
-    However I do recommend to leverage dependency injection as much as possible.
+    For making the examples more expressive, facades are used.
+    However it is recommend to leverage dependency injection as much as possible.
     This makes mocking the EntityManager in your tests a lot easier.
 
 Entities are objects with identity. Their identity has a conceptual meaning
@@ -84,18 +87,18 @@ those changes. This pattern is the `Identity Map Pattern <https://martinfowler.c
 which means that Doctrine keeps a map of each entity and ids that have been
 retrieved per request and keeps return the same instances on every find.
 
-``$article`` and ``$article1`` will be identical, eventhough we haven't
+``$entity`` and ``$entityCopy`` will be identical, eventhough we haven't
 persisted the changes to ``$article`` to the database yet.
 
 .. code-block:: php
 
-  $article = EntityManager::find('App\Entities\Article', 1);
-  $article->setTitle('Different title');
+  $entity = EntityManager::find('App\Entities\Article', 1);
+  $entity->setTitle('Different title');
 
-  $article2 = EntityManager::find('App\Entities\Article', 1);
+  $entityCopy = EntityManager::find('App\Entities\Article', 1);
 
   if ($article === $article2) {
-      echo "Yes we are the same!";
+      echo 'Yes, we are the same!';
   }
 
 
@@ -104,7 +107,7 @@ Persisting
 
 By passing the entity through the ``$entityManager->persist()`` method of the EntityManager,
 that entity becomes managed, which means that its persistence is from now
-on managed by an EntityManager. As a result the persistent state of such
+on managed by an EntityManager. As a result, the persistent state of such
 an entity will subsequently be properly synchronised with the database
 when ``$entityManager->flush()`` is invoked.
 
@@ -160,4 +163,4 @@ https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/worki
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst

docs/index.rst

@@ -35,14 +35,14 @@ object-oriented programming if persistence and entities are seperate.
   upgrade
 
   install
+  configuration
   entities
   metadata
   entity-manager
   multiple-connections
   repositories
   console
 
-  configuration
   doctrine-manager
   connections
   caching
@@ -59,4 +59,4 @@ object-oriented programming if persistence and entities are seperate.
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst

docs/install.rst

@@ -34,6 +34,7 @@ Environment variables used inside the config
   Default is ``DOCTRINE_CACHE``.
 * ``DOCTRINE_RESULT_CACHE`` - The cache handler for the results.
   Default is ``DOCTRINE_CACHE``.
+* ``DOCTRINE_LOGGER`` - The logger to use to log DQL queries.
 
 
 Application Folder Structure

docs/metadata.rst

@@ -66,4 +66,4 @@ https://www.doctrine-project.org/projects/doctrine-orm/en/2.6/reference/xml-mapp
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst

docs/notifications.rst

@@ -130,3 +130,9 @@ entity (most likely your User entity). Usage of the
   {
       return 'custom';
   }
+
+
+.. role:: raw-html(raw)
+   :format: html
+
+.. include:: footer.rst

docs/pagination.rst

@@ -70,4 +70,4 @@ with the ``LaravelDoctrine\ORM\Pagination\PaginatesFromParams`` trait:
 .. role:: raw-html(raw)
    :format: html
 
-.. include:: footer.rst
+.. include:: footer.rst