diff --git a/docs/en/index.rst b/docs/en/index.rst index 58753eb25..383c06930 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -37,7 +37,7 @@ Mapping Objects onto a Database * **Mapping**: :doc:`Objects ` | :doc:`Associations ` | - :doc:`Inheritance ` + :doc:`Inheritance ` | * **Drivers**: :doc:`Docblock Annotations ` | @@ -88,6 +88,7 @@ Tutorials * :doc:`Ordered associations ` * :doc:`Pagination ` * :doc:`Override Field/Association Mappings In Subclasses ` +* :doc:`Embeddables ` Cookbook -------- diff --git a/docs/en/toc.rst b/docs/en/toc.rst index 1a331fa23..75acd2071 100644 --- a/docs/en/toc.rst +++ b/docs/en/toc.rst @@ -16,6 +16,7 @@ Tutorials tutorials/ordered-associations tutorials/override-field-association-mappings-in-subclasses tutorials/pagination.rst + tutorials/embeddables.rst Reference Guide --------------- diff --git a/docs/en/tutorials/embeddables.rst b/docs/en/tutorials/embeddables.rst new file mode 100644 index 000000000..3db2b47b0 --- /dev/null +++ b/docs/en/tutorials/embeddables.rst @@ -0,0 +1,83 @@ +Separating Concerns using Embeddables +------------------------------------- + +Embeddables are classes which are not entities themself, but are embedded +in entities and can also be queried in DQL. You'll mostly want to use them +to reduce duplication or separating concerns. + +For the purposes of this tutorial, we will assume that you have a ``User`` +class in your application and you would like to store an address in +the ``User`` class. We will model the ``Address`` class as an embeddable +instead of simply adding the respective columns to the ``User`` class. + +.. configuration-block:: + + .. code-block:: php + + + + + + + + + + + + + + + .. code-block:: yaml + + User: + type: entity + embedded: + address: + class: Address + + Address: + type: embeddable + columns: + street: { type: string } + postalCode: { type: string } + city: { type: string } + country: { type: string } + +In terms of your database schema, Doctrine will automatically inline all +columns from the ``Address`` class into the table of the ``User`` class, +just as if you had declared them directly there. + +You can also use mapped fields of embedded classes in DQL queries, just +as if they were declared in the ``User`` class: + +.. code-block:: sql + + SELECT u FROM User u WHERE u.address.city = :myCity +