From d345d0043258165af11f8843bac0cfc29cbee97a Mon Sep 17 00:00:00 2001 From: Benjamin Eberlei Date: Tue, 5 Oct 2010 22:02:18 +0200 Subject: [PATCH 1/3] Add docs on Doctrine ORM Form integration --- guides/doctrine/orm/form.rst | 75 +++++++++++++++++++++++++++++++++++ guides/doctrine/orm/index.rst | 1 + 2 files changed, 76 insertions(+) create mode 100644 guides/doctrine/orm/form.rst diff --git a/guides/doctrine/orm/form.rst b/guides/doctrine/orm/form.rst new file mode 100644 index 00000000000..dea5deb75bd --- /dev/null +++ b/guides/doctrine/orm/form.rst @@ -0,0 +1,75 @@ +Form Integration +================ + +There is a tight integration between Doctrine ORM and the Symfony Form component. Since Doctrine Entities +are plain old php objects they nicely integrate into the Form component by default, at least for the +primitive data types such as strings, integers and fields. However you can also integrate them nicely +with associations. + +This is done by the help of ValueTransformers, which are form field extension points. There are currently +three transformers that allow you to transform Doctrine ORM Collections and Entities into their identifier +values that can be used with the Form component. Furthermore they translate form values back to the Doctrine +representation in the most efficient way possible, issuing as few queries as possible. + +CollectionToChoiceTransformer +----------------------------- + +This transformer allows you to transform a Collection of Entities into an array of ids. This transformer +should be used with the ChoiceField or any compatible field that handles arrays of values. + + use Symfony\Component\Form\ChoiceField; + use Symfony\Bundle\DoctrineBundle\Form\ValueTransformer\CollectionToChoiceTransformer; + + $field = new ChoiceField('products', array( + 'choices' => $productChoices, + 'multiple' => true, + 'expanded' => true, + )); + $field->setValueTransformer(new CollectionToChoiceTransformer(array( + 'em' => $em, + 'className' => 'Product', + ))); + + // Important: Make sure to attach the value transformer before calling addField(). + $form->addField($field); + +The 'em' property expects the EntityManager, the 'className' property expects the Entity Class name +as an argument. + +CollectionToStringTransformer +----------------------------- + +This transformer allows you to transform a Collection of Entities into a string separated by a separator. +This is useful for lists of tags, usernames or similiar unique fields of your Entities. + +EntityToIDTransformer +--------------------- + +This transformer converts an Entity into its ID and back to allow to select many-to-one +or one-to-one entities in choice fields. See this extended example on how it works. In this +case a list of all users is used in a Choice field to be choosen from: + + use Symfony\Bundle\DoctrineBundle\Form\ValueTransformer\EntityToIDTransformer; + use Symfony\Component\Form\ChoiceField; + + $userChoices = array(); + $users = $em->getRepository('User')->findAll(); + foreach ($users AS $user) { + $userChoices[$user->id] = $user->name; + } + + $userTransformer = new EntityToIDTransformer(array( + 'em' => $em, + 'className' => 'User', + )); + $engineerField = new ChoiceField('engineer', array( + 'choices' => $userChoices, + )); + $engineerField->setValueTransformer($userTransformer); + $reporterField = new ChoiceField('reporter', array( + 'choices' => $userChoices, + )); + $reporterField->setValueTransformer($userTransformer); + + $form->add($engineerField); + $form->add($reporterfield); \ No newline at end of file diff --git a/guides/doctrine/orm/index.rst b/guides/doctrine/orm/index.rst index 3cc24717d76..7627761bbef 100644 --- a/guides/doctrine/orm/index.rst +++ b/guides/doctrine/orm/index.rst @@ -7,3 +7,4 @@ Object Relational Mapper Overview Configuration Console Commands + Form
\ No newline at end of file From c3442a8f33ef72aa53b624be19f44a232a9faa02 Mon Sep 17 00:00:00 2001 From: Benjamin Eberlei Date: Sun, 2 Jan 2011 08:35:04 +0100 Subject: [PATCH 2/3] Add section about Doctrine ORM and MongoDB Event Listener and Subscriber Configuration using the DIC. --- guides/doctrine/mongodb-odm/configuration.rst | 14 +++++ guides/doctrine/orm/configuration.rst | 60 +++++++++++++++---- 2 files changed, 63 insertions(+), 11 deletions(-) diff --git a/guides/doctrine/mongodb-odm/configuration.rst b/guides/doctrine/mongodb-odm/configuration.rst index 3341b2c24eb..755a30c8b2f 100644 --- a/guides/doctrine/mongodb-odm/configuration.rst +++ b/guides/doctrine/mongodb-odm/configuration.rst @@ -92,6 +92,20 @@ The following configuration shows a bunch of mapping examples: prefix: DoctrineExtensions\Documents\ alias: DExt +Registering Event Listeners and Subscribers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Doctrine uses the lightweight ``Doctrine\Common\EventManager`` class to trigger +a number of different events which you can hook into. You can register Event +Listeners or Subscribers by tagging the respective services with +``doctrine.odm.mongodb._event_listener`` or +``doctrine.odm.mongodb._event_subscriber`` using the Dependency Injenction +container. + +You have to use the name of the MongoDB connection to clearly identify which +connection the listeners should be registered with. If you are using multiple +connections you can hook different events into each connection. + Multiple Connections ~~~~~~~~~~~~~~~~~~~~ diff --git a/guides/doctrine/orm/configuration.rst b/guides/doctrine/orm/configuration.rst index 8db9b645810..c04b149db98 100644 --- a/guides/doctrine/orm/configuration.rst +++ b/guides/doctrine/orm/configuration.rst @@ -66,9 +66,9 @@ can control. The following configuration options exist for a mapping: - ``prefix`` A common namespace prefix that all entities of this mapping share. This prefix should never conflict with prefixes of other defined mappings otherwise some of your entities cannot be found by Doctrine. This - option defaults to the bundle namespace + `Entities`, for example for an + option defaults to the bundle namespace + ``Entity``, for example for an application bundle called "Hello" prefix would be - "Application\Hello\Entities". + ``Application\Hello\Entity``. - ``alias`` Doctrine offers a way to alias entity namespaces to simpler, shorter names to be used in DQL queries or for Repository access. - ``is_bundle`` This option is a derived value from ``dir`` and by default is @@ -80,13 +80,13 @@ can control. The following configuration options exist for a mapping: To avoid having to configure lots of information for your mappings you should follow these conventions: -1. Put all your entities in a directory Entities/ inside your bundle. For -example "Application/Hello/Entities/". +1. Put all your entities in a directory ``Entity/`` inside your bundle. For + example ``Application/Hello/Entity/``. 2. If you are using xml, yml or php mapping put all your configuration files -into the "Resources/config/doctrine/metadata/doctrine/orm/" directory sufficed -with dcm.xml, dcm.yml or dcm.php respectively. -3. Annotations is assumed if an "Entities/" but no -"Resources/config/doctrine/metadata/doctrine/orm/" directory is found. + into the "Resources/config/doctrine/metadata/doctrine/orm/" directory sufficed + with dcm.xml, dcm.yml or dcm.php respectively. +3. Annotations is assumed if an ``Entity/`` but no + "Resources/config/doctrine/metadata/doctrine/orm/" directory is found. The following configuration shows a bunch of mapping examples: @@ -96,7 +96,7 @@ The following configuration shows a bunch of mapping examples: mappings: MyBundle1: ~ MyBundle2: yml - MyBundle3: { type: annotation, dir: Entities/ } + MyBundle3: { type: annotation, dir: Entity/ } MyBundle4: { type: xml, dir: Resources/config/doctrine/mapping } MyBundle5: type: yml @@ -104,10 +104,48 @@ The following configuration shows a bunch of mapping examples: alias: BundleAlias doctrine_extensions: type: xml - dir: %kernel.dir%/../src/vendor/DoctrineExtensions/lib/DoctrineExtensions/Entities - prefix: DoctrineExtensions\Entities\ + dir: %kernel.dir%/../src/vendor/DoctrineExtensions/lib/DoctrineExtensions/Entity + prefix: DoctrineExtensions\Entity\ alias: DExt +Registering Event Listeners and Subscribers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Doctrine uses the lightweight ``Doctrine\Common\EventManager`` class to trigger +a number of different events which you can hook into. You can register Event +Listeners or Subscribers by tagging the respective services with +``doctrine.dbal._event_listener`` or +``doctrine.dbal._event_subscriber`` using the Dependency Injenction +container. + +You have to use the name of the DBAL connection to clearly identify which +connection the listeners should be registered with. If you are using multiple +connections you can hook different events into each connection. + +.. code-block:: xml + + + + + + + + + + + + + + + + + +Although the Event Listener and Subscriber tags are prefixed with ``doctrine.dbal`` +these tags also work for the ORM events. Internally Doctrine re-uses the EventManager +that is registered with the connection for the ORM. + Multiple Entity Managers ~~~~~~~~~~~~~~~~~~~~~~~~ From 11e58c6eaff25553f4dfb2c4c0fd1587ae53b113 Mon Sep 17 00:00:00 2001 From: Benjamin Eberlei Date: Sun, 2 Jan 2011 08:37:36 +0100 Subject: [PATCH 3/3] Fix references to Documents instead of Document in MongoDB configuration guide. --- guides/doctrine/mongodb-odm/configuration.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/guides/doctrine/mongodb-odm/configuration.rst b/guides/doctrine/mongodb-odm/configuration.rst index 755a30c8b2f..d4eb98dab53 100644 --- a/guides/doctrine/mongodb-odm/configuration.rst +++ b/guides/doctrine/mongodb-odm/configuration.rst @@ -50,9 +50,9 @@ can control. The following configuration options exist for a mapping: - ``prefix`` A common namespace prefix that all documents of this mapping share. This prefix should never conflict with prefixes of other defined mappings otherwise some of your documents cannot be found by Doctrine. This - option defaults to the bundle namespace + `Documents`, for example for an + option defaults to the bundle namespace + ``Document``, for example for an application bundle called "Hello" prefix would be - "Application\Hello\Documents". + ``Application\Hello\Document``. - ``alias`` Doctrine offers a way to alias document namespaces to simpler, shorter names to be used inqueries or for Repository access. - ``is_bundle`` This option is a derived value from ``dir`` and by default is @@ -64,13 +64,13 @@ can control. The following configuration options exist for a mapping: To avoid having to configure lots of information for your mappings you should follow these conventions: -1. Put all your entities in a directory Documents/ inside your bundle. For -example "Application/Hello/Documents/". +1. Put all your entities in a directory ``Document/`` inside your bundle. For + example ``Application/Hello/Document/``. 2. If you are using xml, yml or php mapping put all your configuration files -into the "Resources/config/doctrine/metadata/doctrine/mongodb/" directory -sufficed with dcm.xml, dcm.yml or dcm.php respectively. -3. Annotations is assumed if an "Documents/" but no -"Resources/config/doctrine/metadata/doctrine/mongodb/" directory is found. + into the ``Resources/config/doctrine/metadata/doctrine/mongodb/`` directory + sufficed with dcm.xml, dcm.yml or dcm.php respectively. +3. Annotations is assumed if an ``Document/`` but no + ``Resources/config/doctrine/metadata/doctrine/mongodb/`` directory is found. The following configuration shows a bunch of mapping examples: