From 2e4b6f2619bec0de477c602bd631464af0e0ab8f Mon Sep 17 00:00:00 2001 From: David Buchmann Date: Wed, 9 May 2018 09:58:57 +0200 Subject: [PATCH] adjust phpcr-odm documentation to autowiring --- bundles/phpcr_odm/configuration.rst | 4 +- bundles/phpcr_odm/events.rst | 12 ++-- bundles/phpcr_odm/fixtures_initializers.rst | 26 +++---- bundles/phpcr_odm/forms.rst | 14 ++-- bundles/phpcr_odm/introduction.rst | 14 ++-- bundles/phpcr_odm/models.rst | 80 +++++++++++---------- bundles/phpcr_odm/multilang.rst | 8 +-- bundles/phpcr_odm/multiple_sessions.rst | 23 ++++-- 8 files changed, 98 insertions(+), 83 deletions(-) diff --git a/bundles/phpcr_odm/configuration.rst b/bundles/phpcr_odm/configuration.rst index 0f48ad9b..3c0e9143 100644 --- a/bundles/phpcr_odm/configuration.rst +++ b/bundles/phpcr_odm/configuration.rst @@ -538,8 +538,8 @@ The service to use as base for building the PHPCR-ODM configuration. **type**: ``boolean``, **default**: ``true`` When enabled, you can place your mappings in -``/Resources/config/doctrine/.phpcr.xml`` resp. ``*.phpcr.yml`` -to configure mappings for documents you provide in the ``/Document`` +``/Resources/config/doctrine/.phpcr.xml`` resp. ``*.phpcr.yml`` +to configure mappings for documents you provide in the ``/Document`` folder. Otherwise you need to manually configure the mappings section. ``auto_generate_proxy_classes`` diff --git a/bundles/phpcr_odm/events.rst b/bundles/phpcr_odm/events.rst index e74d1325..c470fc50 100644 --- a/bundles/phpcr_odm/events.rst +++ b/bundles/phpcr_odm/events.rst @@ -33,12 +33,12 @@ use this configuration: # app/config/services.yml services: app.phpcr_search_indexer: - class: AppBundle\EventListener\SearchIndexer + class: App\EventListener\SearchIndexer tags: - { name: doctrine_phpcr.event_listener, event: postPersist } app.phpcr_listener: - class: AppBundle\EventListener\MyListener + class: App\EventListener\MyListener tags: - { name: doctrine_phpcr.event_subscriber } @@ -49,11 +49,11 @@ use this configuration: + class="App\EventListener\SearchIndexer"> + class="App\EventListener\MyListener"> @@ -62,8 +62,8 @@ use this configuration: .. code-block:: php // app/config/config.php - use AppBundle\EventListener\SearchIndexer; - use AppBundle\EventListener\MyListener; + use App\EventListener\SearchIndexer; + use App\EventListener\MyListener; $container ->register( diff --git a/bundles/phpcr_odm/fixtures_initializers.rst b/bundles/phpcr_odm/fixtures_initializers.rst index f9bce59b..e80eabe1 100644 --- a/bundles/phpcr_odm/fixtures_initializers.rst +++ b/bundles/phpcr_odm/fixtures_initializers.rst @@ -16,7 +16,7 @@ Repository Initializers ----------------------- The Initializer is the PHPCR equivalent of the ORM schema tools. It is used to -let bundles register PHPCR node types and to create required base paths in the +let your application PHPCR node types and to create required base paths in the repository. .. note:: @@ -98,10 +98,10 @@ specific documents, you need your own Initializer. The interesting method to overwrite is the ``init`` method. It is passed the ``ManagerRegistry``, from which you can retrieve the PHPCR session but also the document manager:: - // src/AppBundle/Initializer/SiteInitializer.php - namespace AppBundle\Initializer; + // src/App/Initializer/SiteInitializer.php + namespace App\Initializer; - use AppBundle\Documents\Site; + use App\Documents\Site; use Doctrine\Bundle\PHPCRBundle\Initializer\InitializerInterface; use Doctrine\Bundle\PHPCRBundle\ManagerRegistry; use PHPCR\SessionInterface; @@ -153,7 +153,7 @@ Define a service for your Initializer as follows: services: # ... app.phpcr_initializer_site: - class: AppBundle\Initializer\SiteInitializer + class: App\Initializer\SiteInitializer tags: - { name: doctrine_phpcr.initializer } @@ -171,7 +171,7 @@ Define a service for your Initializer as follows: + class="App\Initializer\SiteInitializer"> @@ -186,7 +186,7 @@ Define a service for your Initializer as follows: $container ->register( 'app.phpcr_initializer_site', - 'AppBundle\Initializer\SiteInitializer' + 'App\Initializer\SiteInitializer' ) ->addTag('doctrine_phpcr.initializer', ['name' => 'doctrine_phpcr.initializer'] ; @@ -208,7 +208,7 @@ basis. # app/config/services.yml app.migration: - class: AppBundle\Migration\Migration + class: App\Migration\Migration arguments: - { "%app.content_basepath%", "%app.menu_basepath%" } tags: @@ -220,7 +220,7 @@ basis. + class="App\Migration\Migration"> %app.content_basepath% %app.menu_basepath% @@ -232,7 +232,7 @@ basis. .. code-block:: php - use AppBundle\Migration\Migration; + use App\Migration\Migration; use Symfony\Component\DependencyInjection\Definition; // ... @@ -275,13 +275,13 @@ install the `DoctrineFixturesBundle`_ which brings the Fixtures work the same way they work for Doctrine ORM. You write fixture classes implementing ``Doctrine\Common\DataFixtures\FixtureInterface``. If you -place them in ``\DataFixtures\PHPCR``, they will be auto detected if you +place them in ``\DataFixtures\PHPCR``, they will be auto detected if you don't specify a path in the command. A simple example fixture class looks like this:: - // src/AppBundle/DataFixtures/PHPCR/LoadPageData.php - namespace AppBundle\DataFixtures\PHPCR; + // src/App/DataFixtures/PHPCR/LoadPageData.php + namespace App\DataFixtures\PHPCR; use Doctrine\Common\Persistence\ObjectManager; use Doctrine\Common\DataFixtures\FixtureInterface; diff --git a/bundles/phpcr_odm/forms.rst b/bundles/phpcr_odm/forms.rst index 2c8d6aff..5f975709 100644 --- a/bundles/phpcr_odm/forms.rst +++ b/bundles/phpcr_odm/forms.rst @@ -38,7 +38,7 @@ that the option for the document manager is called ``em``. A simple example of using the ``phpcr_document`` form type looks as follows:: - use AppBundle\Document\TargetClass; + use App\Document\TargetClass; $form ->add( @@ -82,7 +82,7 @@ targets as an array of PHPCR-ODM ids or PHPCR paths. The minimal code required to use this type looks as follows:: - use AppBundle\Document\Article; + use App\Document\Article; $dataArr = [ '/some/phpcr/path/item_1' => 'first item', @@ -126,14 +126,14 @@ correct. .. code-block:: yaml - # src/AppBundle/Resources/config/validation.yml - AppBundle\Entity\Author: + # src/App/Resources/config/validation.yml + App\Document\Author: constraints: - Doctrine\Bundle\PHPCRBundle\Validator\Constraints\ValidPhpcrOdm .. code-block:: php-annotations - // src/AppBundle/Entity/Author.php + // src/App/Document/Author.php // ... use Doctrine\Bundle\PHPCRBundle\Validator\Constraints as OdmAssert; @@ -155,7 +155,7 @@ correct. xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping http://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> - + @@ -163,7 +163,7 @@ correct. .. code-block:: php - // src/AppBundle/Entity/Author.php + // src/App/Document/Author.php // ... use Symfony\Component\Validator\Mapping\ClassMetadata; diff --git a/bundles/phpcr_odm/introduction.rst b/bundles/phpcr_odm/introduction.rst index 0b4aacee..c665ca96 100644 --- a/bundles/phpcr_odm/introduction.rst +++ b/bundles/phpcr_odm/introduction.rst @@ -320,7 +320,7 @@ here, the ODM services will not be loaded. Unless you disable ``auto_mapping``, you can place your documents in the ``Document`` folder inside your bundles and use annotations or name the mapping files following this schema: -``/Resources/config/doctrine/.phpcr.xml`` or ``*.phpcr.yml``. +``/Resources/config/doctrine/.phpcr.xml`` or ``*.phpcr.yml``. If ``auto_generate_proxy_classes`` is false, you need to run the ``cache:warmup`` command in order to have the proxy classes generated after @@ -413,11 +413,13 @@ Services There are 3 main services provided by this bundle: -* ``doctrine_phpcr``- The ``ManagerRegistry`` instance with references to all - sessions and document manager instances; -* ``doctrine_phpcr.default_session`` - The PHPCR session instance; -* ``doctrine_phpcr.odm.default_document_manager`` - The PHPCR-ODM document - manager instance. +* ``Doctrine\Bundle\PHPCRBundle\ManagerRegistry``- The ``ManagerRegistry`` + instance with references to all sessions and document manager instances; +* ``PHPCR\SessionInterface`` - the PHPCR session. If you configured + multiple sessions, this will be the default session; +* ``Doctrine\ODM\PHPCR\DocumentManagerInterface`` - the PHPCR-ODM document + manager. If you configured multiple managers, this will be the default + manager. .. _bundles-phpcr-odm-commands: diff --git a/bundles/phpcr_odm/models.rst b/bundles/phpcr_odm/models.rst index 7d5ddec4..712b279d 100644 --- a/bundles/phpcr_odm/models.rst +++ b/bundles/phpcr_odm/models.rst @@ -39,8 +39,8 @@ Creating a Document Class Without thinking about Doctrine or PHPCR-ODM, you can create a ``Task`` object in PHP:: - // src/Acme/TaskBundle/Document/Task.php - namespace Acme\TaskBundle\Document; + // src/App/Document/Task.php + namespace use App\Document; class Task { @@ -57,8 +57,8 @@ Doctrine PHPCR-ODM yet - it's just a simple PHP class. .. note:: A Document is analogous to the term ``Entity`` employed by the Doctrine - ORM. You must add this object to the ``Document`` sub-namespace of you - bundle, in order register the mapping data automatically. + ORM. To have the mapping happen automatically, place your documents in the + ``Document`` namespace within your application. Add Mapping Information ~~~~~~~~~~~~~~~~~~~~~~~ @@ -78,8 +78,8 @@ class via annotations: .. code-block:: php-annotations - // src/Acme/TaskBundle/Document/Task.php - namespace Acme\TaskBundle\Document; + // src/App/Document/Task.php + namespace App\Document; use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; @@ -111,8 +111,8 @@ class via annotations: .. code-block:: yaml - # src/Acme/TaskBundle/Resources/config/doctrine/Task.phpcr.yml - Acme\TaskBundle\Document\Task: + # src/App/Resources/config/doctrine/Task.phpcr.yml + App\Document\Task: id: id fields: @@ -123,7 +123,7 @@ class via annotations: .. code-block:: xml - + - + @@ -181,21 +181,19 @@ Persisting Documents to PHPCR ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Now that you have a mapped ``Task`` document, complete with getter and setter -methods, you're ready to persist data to PHPCR. From inside a controller, -this is pretty easy, add the following method to the ``DefaultController`` of the -AcmeTaskBundle:: +methods, you are ready to persist data to PHPCR. For a simple example, lets do +this from inside a controller:: - // src/Acme/TaskBundle/Controller/DefaultController.php + // src/App/Controller/DefaultController.php // ... - use Acme\TaskBundle\Document\Task; + use App\Document\Task; + use Doctrine\ODM\PHPCR\DocumentManagerInterface; use Symfony\Component\HttpFoundation\Response; // ... - public function createAction() + public function createAction(DocumentManagerInterface $documentManager) { - $documentManager = $this->get('doctrine_phpcr')->getManager(); - $rootTask = $documentManager->find(null, '/tasks'); $task = new Task(); @@ -211,22 +209,21 @@ AcmeTaskBundle:: Take a look at the previous example in more detail: -* **line 10** This line fetches Doctrine's *document manager* object, which is - responsible for handling the process of persisting and fetching objects to - and from PHPCR. -* **line 12** This line fetches the root document for the tasks, as each - Document needs to have a parent. To create this root document, you can +* **line 8** We use symfony controller injection with autowiring to get the + *document manager*. This service is responsible for storing and fetching + objects to and from PHPCR. +* **line 10** This line loads the root document for the tasks, as each PHPCR + document needs to have a parent. To create this root document, you can configure a :ref:`Repository Initializer `, which will be executed when running ``doctrine:phpcr:repository:init``. -* **lines 14-16** In this section, you instantiate and work with the ``$task`` +* **lines 12-14** In this section, you instantiate and work with the ``$task`` object like any other, normal PHP object. -* **line 18** The ``persist()`` method tells Doctrine to "manage" the - ``$task`` object. This does not actually cause a query to be made to PHPCR - (yet). -* **line 20** When the ``flush()`` method is called, Doctrine looks through - all of the objects that it is managing to see if they need to be persisted to - PHPCR. In this example, the ``$task`` object has not been persisted yet, so - the document manager makes a query to PHPCR, which adds a new document. +* **line 16** The ``persist()`` method tells Doctrine to "manage" the ``$task`` + object. This does not actually cause a query to be made to PHPCR (yet). +* **line 20** When the ``flush()`` method is called, Doctrine looks through all + of the objects that it is managing to see if they need to be stored to PHPCR. + In this example, the ``$task`` object has not been saved yet, so the document + manager makes a query to PHPCR to add it. When creating or updating objects, the workflow is always the same. In the next section, you'll see how Doctrine is smart enough to update documents if @@ -238,9 +235,12 @@ Fetching Objects from PHPCR Fetching an object back out of PHPCR is even easier. For example, suppose you've configured a route to display a specific task by name:: - public function showAction($name) + use App\Document\Task; + use Doctrine\ODM\PHPCR\DocumentManagerInterface; + + public function showAction(DocumentManagerInterface $documentManager, $name) { - $repository = $this->get('doctrine_phpcr')->getRepository('AcmeTaskBundle:Task'); + $repository = $documentManager->getRepository(Task::class); $task = $repository->find('/tasks/'.$name); if (!$task) { @@ -263,12 +263,12 @@ The repository contains all sorts of helpful methods:: $task = $repository->find($id); // query for one task matching be name and done - $task = $repository->findOneBy(array('name' => 'foo', 'done' => false)); + $task = $repository->findOneBy(['name' => 'foo', 'done' => false]); // query for all tasks matching the name, ordered by done $tasks = $repository->findBy( - array('name' => 'foo'), - array('done' => 'ASC') + ['name' => 'foo'], + ['done' => 'ASC'] ); .. tip:: @@ -291,10 +291,12 @@ Updating an Object Once you've fetched an object from Doctrine, updating it is easy. Suppose you have a route that maps a task ID to an update action in a controller:: - public function updateAction($name) + use App\Document\Task; + use Doctrine\ODM\PHPCR\DocumentManagerInterface; + + public function updateAction(DocumentManagerInterface $documentManager, $name) { - $documentManager = $this->get('doctrine_phpcr')->getManager(); - $repository = $documentManager->getRepository('AcmeTaskBundle:Task'); + $repository = $documentManager->getRepository(Task::class); $task = $repository->find('/tasks/'.$name); if (!$task) { diff --git a/bundles/phpcr_odm/multilang.rst b/bundles/phpcr_odm/multilang.rst index b016484c..c4abc393 100644 --- a/bundles/phpcr_odm/multilang.rst +++ b/bundles/phpcr_odm/multilang.rst @@ -123,8 +123,8 @@ depending on the locale. .. code-block:: php - // src/AppBundle/Documents/Article.php - namespace AppBundle\Documents\Article; + // src/App/Documents/Article.php + namespace App\Documents\Article; use Doctrine\ODM\PHPCR\Mapping\Annotations as PHPCR; @@ -161,7 +161,7 @@ depending on the locale. .. code-block:: xml - @@ -172,7 +172,7 @@ depending on the locale. .. code-block:: yaml - AppBundle\Documents\Article: + App\Documents\Article: translator: attribute locale: locale fields: diff --git a/bundles/phpcr_odm/multiple_sessions.rst b/bundles/phpcr_odm/multiple_sessions.rst index 532995ce..f71cf8cb 100644 --- a/bundles/phpcr_odm/multiple_sessions.rst +++ b/bundles/phpcr_odm/multiple_sessions.rst @@ -7,7 +7,16 @@ Configuring multiple sessions for PHPCR-ODM If you need more than one PHPCR backend, you can define ``sessions`` as child of the ``session`` information. Each session has a name and the configuration following the same schema as what is directly in ``session``. You can also -overwrite which session to use as ``default_session``. +overwrite which session to use as ``default_session``. Once you have multiple +sessions, you can also configure multiple document managers with those +sessions. + +.. tip:: + + Autowiring always gives you the default session and the default document + manager. When working with multiple sessions and managers, you need to + explicitly specify the services. For the document managers, you can also + go through the manager registry (see at the end of this page). .. _bundles-phpcr-odm-multiple-phpcr-sessions: @@ -320,18 +329,20 @@ manager looks for models in the MagnoliaBundle. ]); -You can access the managers through the manager registry available in -``doctrine_phpcr``:: +You can access the managers through the manager registry available in the +service ``Doctrine\Bundle\PHPCRBundle\ManagerRegistry``:: + + use Doctrine\Bundle\PHPCRBundle\ManagerRegistry; /** @var $container \Symfony\Component\DependencyInjection\ContainerInterface */ // get the named manager from the registry - $dm = $container->get('doctrine_phpcr')->getManager('website'); + $dm = $container->get(ManagerRegistry::class)->getManager('website'); // get the manager for a specific document class - $dm = $container->get('doctrine_phpcr')->getManagerForClass('CmfContentBundle:StaticContent'); + $dm = $container->get(ManagerRegistry::class)->getManagerForClass('CmfContentBundle:StaticContent'); Additionally, each manager is available as a service in the DI container. -The service name is ``doctrine_phpcr.odm._document_manager`` so for +The service name pattern is ``doctrine_phpcr.odm._document_manager`` so for example the website manager is called ``doctrine_phpcr.odm.website_document_manager``.