From f3b5a4382106dd52051f41adda791a765ffedd42 Mon Sep 17 00:00:00 2001 From: Tom H Anderson Date: Fri, 25 Oct 2024 23:42:57 -0600 Subject: [PATCH] Rearrange docs --- docs/auth.rst | 2 +- docs/caching.rst | 2 +- docs/configuration.rst | 59 +++++++++++++++--------------- docs/connections.rst | 2 +- docs/console.rst | 2 +- docs/default-table-options.rst | 2 +- docs/doctrine-manager.rst | 2 +- docs/entities.rst | 66 +++++++++++++++++++++++++++++++++- docs/entity-manager.rst | 39 ++++++++++---------- docs/index.rst | 4 +-- docs/install.rst | 1 + docs/metadata.rst | 2 +- docs/notifications.rst | 6 ++++ docs/pagination.rst | 2 +- docs/repositories.rst | 6 ++-- docs/testing.rst | 2 +- docs/troubleshooting.rst | 2 +- docs/validation.rst | 2 +- 18 files changed, 136 insertions(+), 67 deletions(-) diff --git a/docs/auth.rst b/docs/auth.rst index 91781b09..ffc5081d 100644 --- a/docs/auth.rst +++ b/docs/auth.rst @@ -177,4 +177,4 @@ Authentication usage is covered by .. role:: raw-html(raw) :format: html -.. include:: footer.rst \ No newline at end of file +.. include:: footer.rst diff --git a/docs/caching.rst b/docs/caching.rst index f77c149a..29987285 100644 --- a/docs/caching.rst +++ b/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 \ No newline at end of file +.. include:: footer.rst diff --git a/docs/configuration.rst b/docs/configuration.rst index 33f44bde..b9e9df67 100644 --- a/docs/configuration.rst +++ b/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 \ No newline at end of file +.. include:: footer.rst diff --git a/docs/connections.rst b/docs/connections.rst index 3da63c3e..98dc788a 100644 --- a/docs/connections.rst +++ b/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 \ No newline at end of file +.. include:: footer.rst diff --git a/docs/console.rst b/docs/console.rst index 02d6e7c0..3f11affa 100644 --- a/docs/console.rst +++ b/docs/console.rst @@ -23,4 +23,4 @@ Many artisan commands are included in this repository. .. role:: raw-html(raw) :format: html -.. include:: footer.rst \ No newline at end of file +.. include:: footer.rst diff --git a/docs/default-table-options.rst b/docs/default-table-options.rst index 7ca366e5..dd0f6b12 100644 --- a/docs/default-table-options.rst +++ b/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 \ No newline at end of file +.. include:: footer.rst diff --git a/docs/doctrine-manager.rst b/docs/doctrine-manager.rst index c1f0b5e3..89ecd366 100644 --- a/docs/doctrine-manager.rst +++ b/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 \ No newline at end of file +.. include:: footer.rst diff --git a/docs/entities.rst b/docs/entities.rst index 0fee1606..87c42598 100644 --- a/docs/entities.rst +++ b/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 + + + + + + + + + + + + +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 \ No newline at end of file +.. include:: footer.rst diff --git a/docs/entity-manager.rst b/docs/entity-manager.rst index 049bca9f..ba9c9b8a 100644 --- a/docs/entity-manager.rst +++ b/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 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 \ No newline at end of file +.. include:: footer.rst diff --git a/docs/index.rst b/docs/index.rst index 5e220492..c0225391 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -35,6 +35,7 @@ object-oriented programming if persistence and entities are seperate. upgrade install + configuration entities metadata entity-manager @@ -42,7 +43,6 @@ object-oriented programming if persistence and entities are seperate. 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 \ No newline at end of file +.. include:: footer.rst diff --git a/docs/install.rst b/docs/install.rst index 8ad049db..6fb26a9d 100644 --- a/docs/install.rst +++ b/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 diff --git a/docs/metadata.rst b/docs/metadata.rst index 2b8562c3..868f6066 100644 --- a/docs/metadata.rst +++ b/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 \ No newline at end of file +.. include:: footer.rst diff --git a/docs/notifications.rst b/docs/notifications.rst index 20d2737d..ce1efe28 100644 --- a/docs/notifications.rst +++ b/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 diff --git a/docs/pagination.rst b/docs/pagination.rst index 63e97dea..85481e09 100644 --- a/docs/pagination.rst +++ b/docs/pagination.rst @@ -70,4 +70,4 @@ with the ``LaravelDoctrine\ORM\Pagination\PaginatesFromParams`` trait: .. role:: raw-html(raw) :format: html -.. include:: footer.rst \ No newline at end of file +.. include:: footer.rst diff --git a/docs/repositories.rst b/docs/repositories.rst index dc0a2a9e..4c914f19 100644 --- a/docs/repositories.rst +++ b/docs/repositories.rst @@ -20,9 +20,7 @@ Getting a repository instance ============================= The easiest way to get a repository is to let the EntityManager provide one -for the Entity you want: - -.. code-block:: php +for the Entity you want. .. code-block:: php @@ -242,4 +240,4 @@ http://shawnmc.cool/the-repository-pattern .. role:: raw-html(raw) :format: html -.. include:: footer.rst \ No newline at end of file +.. include:: footer.rst diff --git a/docs/testing.rst b/docs/testing.rst index 63d8c91d..960f7ebd 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -126,4 +126,4 @@ Factory definition callbacks may receive an optional second argument of attribut .. role:: raw-html(raw) :format: html -.. include:: footer.rst \ No newline at end of file +.. include:: footer.rst diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 4a9a1afe..800056c8 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -60,4 +60,4 @@ performance reasons. .. role:: raw-html(raw) :format: html -.. include:: footer.rst \ No newline at end of file +.. include:: footer.rst diff --git a/docs/validation.rst b/docs/validation.rst index 909c60be..6e8bb967 100644 --- a/docs/validation.rst +++ b/docs/validation.rst @@ -100,4 +100,4 @@ The field under validation must exist on a given database table. .. role:: raw-html(raw) :format: html -.. include:: footer.rst \ No newline at end of file +.. include:: footer.rst