From 485b52957f453c6eb2672bfa285c0c4d9433250f Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 18 Jan 2014 11:12:54 +0100 Subject: [PATCH 01/19] Removed duplicated DQL documentation The doctrine docs already has a big great documentation on this. There is no reason to duplicate it in the sf docs. This commit removes everything except a simple example. It also moves the sentence about the return result above, since that makes more sense now the getSingleResult example is removed. --- book/doctrine.rst | 55 ++++------------------------------------------- 1 file changed, 4 insertions(+), 51 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index 026a3b4f977..d2b9387611e 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -728,65 +728,18 @@ a controller, do the following:: $products = $query->getResult(); +The ``getResult()`` method returns an array of results. + If you're comfortable with SQL, then DQL should feel very natural. The biggest difference is that you need to think in terms of "objects" instead of rows -in a database. For this reason, you select *from* ``AcmeStoreBundle:Product`` -and then alias it as ``p``. - -The ``getResult()`` method returns an array of results. If you're querying -for just one object, you can use the ``getSingleResult()`` method instead:: - - $product = $query->getSingleResult(); - -.. caution:: - - The ``getSingleResult()`` method throws a ``Doctrine\ORM\NoResultException`` - exception if no results are returned and a ``Doctrine\ORM\NonUniqueResultException`` - if *more* than one result is returned. If you use this method, you may - need to wrap it in a try-catch block and ensure that only one result is - returned (if you're querying on something that could feasibly return - more than one result):: - - $query = $em->createQuery('SELECT ...') - ->setMaxResults(1); - - try { - $product = $query->getSingleResult(); - } catch (\Doctrine\Orm\NoResultException $e) { - $product = null; - } - // ... +in a database. For this reason, you select *from* the ``AcmeStoreBundle:Product`` +*object* and then alias it as ``p``. The DQL syntax is incredibly powerful, allowing you to easily join between entities (the topic of :ref:`relations ` will be covered later), group, etc. For more information, see the official Doctrine `Doctrine Query Language`_ documentation. -.. sidebar:: Setting Parameters - - Take note of the ``setParameter()`` method. When working with Doctrine, - it's always a good idea to set any external values as "placeholders", - which was done in the above query: - - .. code-block:: text - - ... WHERE p.price > :price ... - - You can then set the value of the ``price`` placeholder by calling the - ``setParameter()`` method:: - - ->setParameter('price', '19.99') - - Using parameters instead of placing values directly in the query string - is done to prevent SQL injection attacks and should *always* be done. - If you're using multiple parameters, you can set their values at once - using the ``setParameters()`` method:: - - ->setParameters(array( - 'price' => '19.99', - 'name' => 'Foo', - )) - Using Doctrine's Query Builder ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 1ec68feb0e2da8742c5b4547ebf4f0af955bf988 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 18 Jan 2014 11:17:17 +0100 Subject: [PATCH 02/19] Minor tweaks to Repository section --- book/doctrine.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index d2b9387611e..f78be755922 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -772,10 +772,10 @@ Custom Repository Classes In the previous sections, you began constructing and using more complex queries from inside a controller. In order to isolate, test and reuse these queries, -it's a good idea to create a custom repository class for your entity and +it's a good practise to create a custom repository class for your entity and add methods with your query logic there. -To do this, add the name of the repository class to your mapping definition. +To do this, add the name of the repository class to your mapping definition: .. configuration-block:: From 22bb029c0556ee3392b71b0778e83e944d501f5f Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 18 Jan 2014 12:08:53 +0100 Subject: [PATCH 03/19] Minor tweak to configuration section --- book/doctrine.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index f78be755922..bbce8ad9ff6 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -1253,7 +1253,7 @@ Configuration Doctrine is highly configurable, though you probably won't ever need to worry about most of its options. To find out more about configuring Doctrine, see -the Doctrine section of the :doc:`reference manual `. +the Doctrine section of the :doc:`config reference `. Lifecycle Callbacks ------------------- From 13edbcc403cb0de694a8ea4f9b14f417bde54ca2 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 18 Jan 2014 12:11:41 +0100 Subject: [PATCH 04/19] Removed some duplicated Livecycle docs The list is also included in the doctrine docs. There is no need to duplicate that in the sf docs. And if it's usefull, it certainly isn't when there is no more documentation about their meaning. --- book/doctrine.rst | 18 +++--------------- 1 file changed, 3 insertions(+), 15 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index bbce8ad9ff6..c30cc8e05bd 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -1265,7 +1265,7 @@ stages of the lifecycle of an entity (e.g. the entity is inserted, updated, deleted, etc). If you're using annotations for your metadata, start by enabling the lifecycle -callbacks. This is not necessary if you're using YAML or XML for your mapping: +callbacks. This is not necessary if you're using YAML or XML for your mapping. .. code-block:: php-annotations @@ -1328,20 +1328,8 @@ the current date, only when the entity is first persisted (i.e. inserted): Now, right before the entity is first persisted, Doctrine will automatically call this method and the ``createdAt`` field will be set to the current date. - -This can be repeated for any of the other lifecycle events, which include: - -* ``preRemove`` -* ``postRemove`` -* ``prePersist`` -* ``postPersist`` -* ``preUpdate`` -* ``postUpdate`` -* ``postLoad`` -* ``loadClassMetadata`` - -For more information on what these lifecycle events mean and lifecycle callbacks -in general, see Doctrine's `Lifecycle Events documentation`_ +For more information on other lifecycle events and lifecycle callbacks in +general, see Doctrine's `Lifecycle Events documentation`_. .. sidebar:: Lifecycle Callbacks and Event Listeners From c95a68d41cae07b7dc5bc7022b4b3134f8d69946 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 18 Jan 2014 12:15:13 +0100 Subject: [PATCH 05/19] Removed "Doctrine Extensions" section It's enough to add it to the "Read more" list, there is no need to introduce each cookbook article in a seperate section. --- book/doctrine.rst | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index c30cc8e05bd..a68a2186b3b 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -1344,17 +1344,6 @@ general, see Doctrine's `Lifecycle Events documentation`_. or subscriber and give it access to whatever resources you need. For more information, see :doc:`/cookbook/doctrine/event_listeners_subscribers`. -Doctrine Extensions: Timestampable, Sluggable, etc. ---------------------------------------------------- - -Doctrine is quite flexible, and a number of third-party extensions are available -that allow you to easily perform repeated and common tasks on your entities. -These include thing such as *Sluggable*, *Timestampable*, *Loggable*, *Translatable*, -and *Tree*. - -For more information on how to find and use these extensions, see the cookbook -article about :doc:`using common Doctrine extensions `. - .. _book-doctrine-field-types: Doctrine Field Types Reference From 88aa347e80c76f9c4cabe03340ddeb7b68f87e75 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 18 Jan 2014 12:16:39 +0100 Subject: [PATCH 06/19] Removed types list This is really doctrine specific, the sf docs should not document this, kind of SoC for docs :wink:. --- book/doctrine.rst | 102 +--------------------------------------------- 1 file changed, 2 insertions(+), 100 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index a68a2186b3b..7e78b106307 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -1351,106 +1351,8 @@ Doctrine Field Types Reference Doctrine comes with a large number of field types available. Each of these maps a PHP data type to a specific column type in whatever database you're -using. The following types are supported in Doctrine: - -* **Strings** - - * ``string`` (used for shorter strings) - * ``text`` (used for larger strings) - -* **Numbers** - - * ``integer`` - * ``smallint`` - * ``bigint`` - * ``decimal`` - * ``float`` - -* **Dates and Times** (use a `DateTime`_ object for these fields in PHP) - - * ``date`` - * ``time`` - * ``datetime`` - * ``datetimetz`` - -* **Other Types** - - * ``boolean`` - * ``object`` (serialized and stored in a ``CLOB`` field) - * ``array`` (serialized and stored in a ``CLOB`` field) - * ``blob`` (mapped to a resource stream) - * ``simple_array`` (serialized using :phpfunction:`implode()` and :phpfunction:`explode()`, - with a comma as delimiter, and stored in a ``CLOB`` field) - * ``json_array`` (serialized using :phpfunction:`json_encode()` and :phpfunction:`json_decode()`, - and stored in a ``CLOB`` field) - * ``guid`` - -For more information, see Doctrine's `Mapping Types documentation`_. - -Field Options -~~~~~~~~~~~~~ - -Each field can have a set of options applied to it. The available options -include ``type`` (defaults to ``string``), ``name``, ``length``, ``unique`` -and ``nullable``. Take a few examples: - -.. configuration-block:: - - .. code-block:: php-annotations - - /** - * A string field with length 255 that cannot be null - * (reflecting the default values for the "type", "length" - * and *nullable* options) - * - * @ORM\Column() - */ - protected $name; - - /** - * A string field of length 150 that persists to an "email_address" column - * and has a unique index. - * - * @ORM\Column(name="email_address", unique=true, length=150) - */ - protected $email; - - .. code-block:: yaml - - fields: - # A string field length 255 that cannot be null - # (reflecting the default values for the "length" and *nullable* options) - # type attribute is necessary in YAML definitions - name: - type: string - - # A string field of length 150 that persists to an "email_address" column - # and has a unique index. - email: - type: string - column: email_address - length: 150 - unique: true - - .. code-block:: xml - - - - - -.. note:: - - There are a few more options not listed here. For more details, see - Doctrine's `Property Mapping documentation`_ +using. To see a list of all available types and more information, see +Doctrine's `Mapping Types documentation`_. .. index:: single: Doctrine; ORM console commands From 2c68f04583585b26e6e36e340b29161bc4dbbf2b Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 18 Jan 2014 12:22:31 +0100 Subject: [PATCH 07/19] Moved commands to cookbook It's not really basic information. All important commands are already discussed in the rest of the chapter. The rest are just usefull commands, which is a perfect topic for a cookbook. --- book/doctrine.rst | 62 +---------------------------------- cookbook/doctrine/console.rst | 60 +++++++++++++++++++++++++++++++++ cookbook/doctrine/index.rst | 1 + cookbook/map.rst.inc | 1 + 4 files changed, 63 insertions(+), 61 deletions(-) create mode 100644 cookbook/doctrine/console.rst diff --git a/book/doctrine.rst b/book/doctrine.rst index 7e78b106307..8abdaaf4958 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -1354,67 +1354,6 @@ maps a PHP data type to a specific column type in whatever database you're using. To see a list of all available types and more information, see Doctrine's `Mapping Types documentation`_. -.. index:: - single: Doctrine; ORM console commands - single: CLI; Doctrine ORM - -Console Commands ----------------- - -The Doctrine2 ORM integration offers several console commands under the -``doctrine`` namespace. To view the command list you can run the console -without any arguments: - -.. code-block:: bash - - $ php app/console - -A list of available commands will print out, many of which start with the -``doctrine:`` prefix. You can find out more information about any of these -commands (or any Symfony command) by running the ``help`` command. For example, -to get details about the ``doctrine:database:create`` task, run: - -.. code-block:: bash - - $ php app/console help doctrine:database:create - -Some notable or interesting tasks include: - -* ``doctrine:ensure-production-settings`` - checks to see if the current - environment is configured efficiently for production. This should always - be run in the ``prod`` environment: - - .. code-block:: bash - - $ php app/console doctrine:ensure-production-settings --env=prod - -* ``doctrine:mapping:import`` - allows Doctrine to introspect an existing - database and create mapping information. For more information, see - :doc:`/cookbook/doctrine/reverse_engineering`. - -* ``doctrine:mapping:info`` - tells you all of the entities that Doctrine - is aware of and whether or not there are any basic errors with the mapping. - -* ``doctrine:query:dql`` and ``doctrine:query:sql`` - allow you to execute - DQL or SQL queries directly from the command line. - -.. note:: - - To be able to load data fixtures to your database, you will need to have - the DoctrineFixturesBundle bundle installed. To learn how to do it, - read the ":doc:`/bundles/DoctrineFixturesBundle/index`" entry of the - documentation. - -.. tip:: - - This page shows working with Doctrine within a controller. You may also - want to work with Doctrine elsewhere in your application. The - :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getDoctrine` - method of the controller returns the ``doctrine`` service, you can work with - this in the same way elsewhere by injecting this into your own - services. See :doc:`/book/service_container` for more on creating - your own services. - Summary ------- @@ -1434,6 +1373,7 @@ For more information about Doctrine, see the *Doctrine* section of the * :doc:`/bundles/DoctrineFixturesBundle/index` * :doc:`/cookbook/doctrine/common_extensions` +* :doc:`/cookbook/doctrine/console` .. _`Doctrine`: http://www.doctrine-project.org/ .. _`MongoDB`: http://www.mongodb.org/ diff --git a/cookbook/doctrine/console.rst b/cookbook/doctrine/console.rst new file mode 100644 index 00000000000..b48cd3e3f3c --- /dev/null +++ b/cookbook/doctrine/console.rst @@ -0,0 +1,60 @@ +.. index:: + single: Doctrine; ORM console commands + single: CLI; Doctrine ORM + +Console Commands +---------------- + +The Doctrine2 ORM integration offers several console commands under the +``doctrine`` namespace. To view the command list you can run the console +without any arguments: + +.. code-block:: bash + + $ php app/console + +A list of available commands will print out, many of which start with the +``doctrine:`` prefix. You can find out more information about any of these +commands (or any Symfony command) by running the ``help`` command. For example, +to get details about the ``doctrine:database:create`` task, run: + +.. code-block:: bash + + $ php app/console help doctrine:database:create + +Some notable or interesting tasks include: + +* ``doctrine:ensure-production-settings`` - checks to see if the current + environment is configured efficiently for production. This should always + be run in the ``prod`` environment: + + .. code-block:: bash + + $ php app/console doctrine:ensure-production-settings --env=prod + +* ``doctrine:mapping:import`` - allows Doctrine to introspect an existing + database and create mapping information. For more information, see + :doc:`/cookbook/doctrine/reverse_engineering`. + +* ``doctrine:mapping:info`` - tells you all of the entities that Doctrine + is aware of and whether or not there are any basic errors with the mapping. + +* ``doctrine:query:dql`` and ``doctrine:query:sql`` - allow you to execute + DQL or SQL queries directly from the command line. + +.. note:: + + To be able to load data fixtures to your database, you will need to have + the DoctrineFixturesBundle bundle installed. To learn how to do it, + read the ":doc:`/bundles/DoctrineFixturesBundle/index`" entry of the + documentation. + +.. tip:: + + This page shows working with Doctrine within a controller. You may also + want to work with Doctrine elsewhere in your application. The + :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getDoctrine` + method of the controller returns the ``doctrine`` service, you can work with + this in the same way elsewhere by injecting this into your own + services. See :doc:`/book/service_container` for more on creating + your own services. diff --git a/cookbook/doctrine/index.rst b/cookbook/doctrine/index.rst index 7f19ef7d4fe..a62c736db11 100644 --- a/cookbook/doctrine/index.rst +++ b/cookbook/doctrine/index.rst @@ -14,3 +14,4 @@ Doctrine resolve_target_entity mapping_model_classes registration_form + console diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index b2777f42f5e..60ec9546e85 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -62,6 +62,7 @@ * :doc:`/cookbook/doctrine/resolve_target_entity` * :doc:`/cookbook/doctrine/mapping_model_classes` * :doc:`/cookbook/doctrine/registration_form` + * :doc:`/cookbook/doctrine/console` * :doc:`/cookbook/email/index` From 2af5c607553551ca8c62cfc22d8337cedff4cdcd Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 18 Jan 2014 12:25:14 +0100 Subject: [PATCH 08/19] Small tweaks to summary --- book/doctrine.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index 8abdaaf4958..ab09847d3e7 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -1369,11 +1369,12 @@ that allow you to take different actions as objects go through their persistence lifecycle. For more information about Doctrine, see the *Doctrine* section of the -:doc:`cookbook `, which includes the following articles: +:doc:`cookbook `. Some usefull articles might be: -* :doc:`/bundles/DoctrineFixturesBundle/index` * :doc:`/cookbook/doctrine/common_extensions` * :doc:`/cookbook/doctrine/console` +* :doc:`/bundles/DoctrineFixturesBundle/index` +* :doc:`/bundles/DoctrineMongoDBBundle/index` .. _`Doctrine`: http://www.doctrine-project.org/ .. _`MongoDB`: http://www.mongodb.org/ From 18cbacd46de88ec0c297e86e975bd8cf79354151 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 18 Jan 2014 12:27:37 +0100 Subject: [PATCH 09/19] Clean up reference pointers list --- book/doctrine.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index ab09847d3e7..8fc6e72dc6e 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -1382,10 +1382,8 @@ For more information about Doctrine, see the *Doctrine* section of the .. _`Query Builder`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/query-builder.html .. _`Doctrine Query Language`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html .. _`Association Mapping Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/association-mapping.html -.. _`DateTime`: http://php.net/manual/en/class.datetime.php .. _`Mapping Types Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#doctrine-mapping-types -.. _`Property Mapping documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping +.. _`Property Mapping`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping .. _`Lifecycle Events documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html#lifecycle-events .. _`Reserved SQL keywords documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#quoting-reserved-words .. _`Persistent classes`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#persistent-classes -.. _`Property Mapping`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping From 034d69abd89f6274a543f3cc8a2d2f72a12c619b Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 18 Jan 2014 12:47:05 +0100 Subject: [PATCH 10/19] Tweaked new cookbook article --- cookbook/doctrine/console.rst | 31 +++++++------------------------ 1 file changed, 7 insertions(+), 24 deletions(-) diff --git a/cookbook/doctrine/console.rst b/cookbook/doctrine/console.rst index b48cd3e3f3c..0cfb7befca0 100644 --- a/cookbook/doctrine/console.rst +++ b/cookbook/doctrine/console.rst @@ -6,17 +6,17 @@ Console Commands ---------------- The Doctrine2 ORM integration offers several console commands under the -``doctrine`` namespace. To view the command list you can run the console -without any arguments: +``doctrine`` namespace. To view the command list you can use the ``list`` +command: .. code-block:: bash - $ php app/console + $ php app/console list doctrine -A list of available commands will print out, many of which start with the -``doctrine:`` prefix. You can find out more information about any of these -commands (or any Symfony command) by running the ``help`` command. For example, -to get details about the ``doctrine:database:create`` task, run: +A list of available commands will print out. You can find out more information +about any of these commands (or any Symfony command) by running the ``help`` +command. For example, to get details about the ``doctrine:database:create`` +task, run: .. code-block:: bash @@ -41,20 +41,3 @@ Some notable or interesting tasks include: * ``doctrine:query:dql`` and ``doctrine:query:sql`` - allow you to execute DQL or SQL queries directly from the command line. - -.. note:: - - To be able to load data fixtures to your database, you will need to have - the DoctrineFixturesBundle bundle installed. To learn how to do it, - read the ":doc:`/bundles/DoctrineFixturesBundle/index`" entry of the - documentation. - -.. tip:: - - This page shows working with Doctrine within a controller. You may also - want to work with Doctrine elsewhere in your application. The - :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getDoctrine` - method of the controller returns the ``doctrine`` service, you can work with - this in the same way elsewhere by injecting this into your own - services. See :doc:`/book/service_container` for more on creating - your own services. From f7ec98ca904a92a24180bb695605739b32a45a1f Mon Sep 17 00:00:00 2001 From: WouterJ Date: Sat, 18 Jan 2014 12:47:55 +0100 Subject: [PATCH 11/19] Added tip at a more logical place --- book/doctrine.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/book/doctrine.rst b/book/doctrine.rst index 8fc6e72dc6e..bc44ef39de9 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -517,6 +517,16 @@ of the bundle: If you're following along with this example, you'll need to create a route that points to this action to see it work. +.. tip:: + + This page shows working with Doctrine within a controller. You may also + want to work with Doctrine elsewhere in your application. The + :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getDoctrine` + method of the controller returns the ``doctrine`` service, you can work with + this in the same way elsewhere by injecting this into your own + services. See :doc:`/book/service_container` for more on creating + your own services. + Take a look at the previous example in more detail: * **lines 9-12** In this section, you instantiate and work with the ``$product`` From c98a3da05f03dd6e382b3cc148e4f618415bc094 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 3 Feb 2014 16:19:41 +0100 Subject: [PATCH 12/19] Adjusted doctrine service tip --- book/doctrine.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index bc44ef39de9..3eba317a2a4 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -519,13 +519,12 @@ of the bundle: .. tip:: - This page shows working with Doctrine within a controller. You may also - want to work with Doctrine elsewhere in your application. The - :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getDoctrine` - method of the controller returns the ``doctrine`` service, you can work with - this in the same way elsewhere by injecting this into your own - services. See :doc:`/book/service_container` for more on creating - your own services. + This article shows working with Doctrine from within a controller by using + the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::getDoctrine` + method of the controller. This method is a shortcut to get the + ``doctrine`` service. You can work with Doctrine anywhere else + by injecting that service in the service. See + :doc:`/book/service_container` for more on creating your own services. Take a look at the previous example in more detail: From 7acc0d24d5cbd9e40e5b37936ddf2b4d8cc7a928 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 3 Feb 2014 16:20:51 +0100 Subject: [PATCH 13/19] Reverted removal of getSingleResult() It's now smaller (25 to 3 lines) and uses getOneOrNullResult(). --- book/doctrine.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index 3eba317a2a4..d5b17870010 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -737,7 +737,11 @@ a controller, do the following:: $products = $query->getResult(); -The ``getResult()`` method returns an array of results. +The ``getResult()`` method returns an array of results. To get only one +result, you can use ``getSingleResult()`` (which throws exception there is no +result) or ``getOneOrNullResult()``:: + + $product = $query->getOneOrNullResult(); If you're comfortable with SQL, then DQL should feel very natural. The biggest difference is that you need to think in terms of "objects" instead of rows From 91a18cdfa858f6a5e1e6e8e49ccc2cf0fd4828f1 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 3 Feb 2014 16:26:46 +0100 Subject: [PATCH 14/19] Changed order to QueryBuilder -> DQL The QueryBuilder seems to be easier and more recommend to use. This meant the QueryBuilder section now contains the primary information and the DQL section is now reduced to somewhat a "side topic". --- book/doctrine.rst | 72 +++++++++++++++++++++++------------------------ 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index d5b17870010..64e793c2c51 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -720,12 +720,42 @@ instead of querying for rows on a table (e.g. ``product``). When querying in Doctrine, you have two options: writing pure Doctrine queries or using Doctrine's Query Builder. +Querying for Objects Using Doctrine's Query Builder +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Imagine that you want to query for products, but only return products that +cost more than ``19.99``, ordered from cheapest to most expensive. You can use +Doctrine's ``QueryBuilder`` for this:: + + $repository = $this->getDoctrine() + ->getRepository('AcmeStoreBundle:Product'); + + $query = $repository->createQueryBuilder('p') + ->where('p.price > :price') + ->setParameter('price', '19.99') + ->orderBy('p.price', 'ASC') + ->getQuery(); + + $products = $query->getResult(); + +The ``QueryBuilder`` object contains every method necessary to build your +query. By calling the ``getQuery()`` method, the query builder returns a +normal ``Query`` object, which can be used to get the result of the query. + +The ``getResult()`` method returns an array of results. To get only one +result, you can use ``getSingleResult()`` (which throws exception there is no +result) or ``getOneOrNullResult()``:: + + $product = $query->getOneOrNullResult(); + +For more information on Doctrine's Query Builder, consult Doctrine's +`Query Builder`_ documentation. + Querying for Objects with DQL ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Imagine that you want to query for products, but only return products that -cost more than ``19.99``, ordered from cheapest to most expensive. From inside -a controller, do the following:: +Instead of using the ``QueryBuilder``, you can alternatively write the queries +directly using DQL:: $em = $this->getDoctrine()->getManager(); $query = $em->createQuery( @@ -737,49 +767,17 @@ a controller, do the following:: $products = $query->getResult(); -The ``getResult()`` method returns an array of results. To get only one -result, you can use ``getSingleResult()`` (which throws exception there is no -result) or ``getOneOrNullResult()``:: - - $product = $query->getOneOrNullResult(); - If you're comfortable with SQL, then DQL should feel very natural. The biggest difference is that you need to think in terms of "objects" instead of rows in a database. For this reason, you select *from* the ``AcmeStoreBundle:Product`` -*object* and then alias it as ``p``. +*object* and then alias it as ``p`` (as you see, this is equal to what you +already did in the previous section). The DQL syntax is incredibly powerful, allowing you to easily join between entities (the topic of :ref:`relations ` will be covered later), group, etc. For more information, see the official Doctrine `Doctrine Query Language`_ documentation. -Using Doctrine's Query Builder -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Instead of writing the queries directly, you can alternatively use Doctrine's -``QueryBuilder`` to do the same job using a nice, object-oriented interface. -If you use an IDE, you can also take advantage of auto-completion as you -type the method names. From inside a controller:: - - $repository = $this->getDoctrine() - ->getRepository('AcmeStoreBundle:Product'); - - $query = $repository->createQueryBuilder('p') - ->where('p.price > :price') - ->setParameter('price', '19.99') - ->orderBy('p.price', 'ASC') - ->getQuery(); - - $products = $query->getResult(); - -The ``QueryBuilder`` object contains every method necessary to build your -query. By calling the ``getQuery()`` method, the query builder returns a -normal ``Query`` object, which is the same object you built directly in the -previous section. - -For more information on Doctrine's Query Builder, consult Doctrine's -`Query Builder`_ documentation. - Custom Repository Classes ~~~~~~~~~~~~~~~~~~~~~~~~~ From 8bb3195ead06f4fb8112200f8bb259612d9e47ef Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 3 Feb 2014 16:31:51 +0100 Subject: [PATCH 15/19] Fixed spelling --- book/doctrine.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index 64e793c2c51..420f45d6f6a 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -783,7 +783,7 @@ Custom Repository Classes In the previous sections, you began constructing and using more complex queries from inside a controller. In order to isolate, test and reuse these queries, -it's a good practise to create a custom repository class for your entity and +it's a good practice to create a custom repository class for your entity and add methods with your query logic there. To do this, add the name of the repository class to your mapping definition: From 20ba9e0d39190773d2c7d1b75b1bd738ca46b7b5 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 3 Feb 2014 16:35:31 +0100 Subject: [PATCH 16/19] Readded small note about parameters --- book/doctrine.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/book/doctrine.rst b/book/doctrine.rst index 420f45d6f6a..1967b2f5d62 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -742,6 +742,12 @@ The ``QueryBuilder`` object contains every method necessary to build your query. By calling the ``getQuery()`` method, the query builder returns a normal ``Query`` object, which can be used to get the result of the query. +.. tip:: + + Take note of the ``setParameter()`` method. When working with Doctrine, + it's always a good idea to set any external values as "placeholders" + (``:price`` in the example above) as it prevents SQL injection attacks. + The ``getResult()`` method returns an array of results. To get only one result, you can use ``getSingleResult()`` (which throws exception there is no result) or ``getOneOrNullResult()``:: From 79e2216b4005e85b9c53925312f07471c1dce621 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 3 Feb 2014 16:37:33 +0100 Subject: [PATCH 17/19] Rephrased linking paragraph for Lifecycle events --- book/doctrine.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index 1967b2f5d62..aac54db9963 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -1345,8 +1345,10 @@ the current date, only when the entity is first persisted (i.e. inserted): Now, right before the entity is first persisted, Doctrine will automatically call this method and the ``createdAt`` field will be set to the current date. -For more information on other lifecycle events and lifecycle callbacks in -general, see Doctrine's `Lifecycle Events documentation`_. + +There are several other lifecycle events that you can hook into. For more +information on other lifecycle events and lifecycle callbacks in general, see +Doctrine's `Lifecycle Events documentation`_. .. sidebar:: Lifecycle Callbacks and Event Listeners From 7af962c14bb940561ed73b2cb555c53410547cde Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 3 Feb 2014 16:42:32 +0100 Subject: [PATCH 18/19] Rephrased Field Type section --- book/doctrine.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index aac54db9963..910df4e21de 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -1370,8 +1370,10 @@ Doctrine Field Types Reference Doctrine comes with a large number of field types available. Each of these maps a PHP data type to a specific column type in whatever database you're -using. To see a list of all available types and more information, see -Doctrine's `Mapping Types documentation`_. +using. For each field type, the ``Column`` can be configured further, setting +the ``length``, ``nullable`` behavior, ``name`` and other options. To see a +list of all available types and more information, see Doctrine's +`Mapping Types documentation`_. Summary ------- @@ -1401,7 +1403,7 @@ For more information about Doctrine, see the *Doctrine* section of the .. _`Query Builder`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/query-builder.html .. _`Doctrine Query Language`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html .. _`Association Mapping Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/association-mapping.html -.. _`Mapping Types Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#doctrine-mapping-types +.. _`Mapping Types Documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mappings .. _`Property Mapping`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#property-mapping .. _`Lifecycle Events documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/events.html#lifecycle-events .. _`Reserved SQL keywords documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#quoting-reserved-words From b4dd1a107811bb65f2f16d5b1837bf33db5454b0 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Mon, 3 Feb 2014 16:43:23 +0100 Subject: [PATCH 19/19] Fixed typo + added remore section --- book/doctrine.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index 910df4e21de..6cfd8d6dcd6 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -1389,8 +1389,11 @@ powerful, allowing you to create complex queries and subscribe to events that allow you to take different actions as objects go through their persistence lifecycle. +Learn More +~~~~~~~~~~ + For more information about Doctrine, see the *Doctrine* section of the -:doc:`cookbook `. Some usefull articles might be: +:doc:`cookbook `. Some useful articles might be: * :doc:`/cookbook/doctrine/common_extensions` * :doc:`/cookbook/doctrine/console`