adds docs

docs/en/index.rst

@@ -37,7 +37,7 @@ Mapping Objects onto a Database
 * **Mapping**:
   :doc:`Objects <reference/basic-mapping>` |
   :doc:`Associations <reference/association-mapping>` |
-  :doc:`Inheritance <reference/inheritance-mapping>`
+  :doc:`Inheritance <reference/inheritance-mapping>` |
 
 * **Drivers**:
   :doc:`Docblock Annotations <reference/annotations-reference>` |
@@ -88,6 +88,7 @@ Tutorials
 * :doc:`Ordered associations <tutorials/ordered-associations>`
 * :doc:`Pagination <tutorials/pagination>`
 * :doc:`Override Field/Association Mappings In Subclasses <tutorials/override-field-association-mappings-in-subclasses>`
+* :doc:`Embeddables <tutorials/embeddables>`
 
 Cookbook
 --------

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
 ---------------

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
+
+        <?php
+
+        /** @Entity */
+        class User
+        {
+            /** @Embedded(class = "Address") */
+            private $address;
+        }
+
+        /** @Embeddable */
+        class Address
+        {
+            /** @Column(type = "string") */
+            private $street;
+
+            /** @Column(type = "string") */
+            private $postalCode;
+
+            /** @Column(type = "string") */
+            private $city;
+
+            /** @Column(type = "string") */
+            private $country;
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="User">
+                <embedded class="Address" />
+            </entity>
+
+            <embeddable name="Address">
+                <column name="street" type="string" />
+                <column name="postalCode" type="string" />
+                <column name="city" type="string" />
+                <column name="country" type="string" />
+            </embeddable>
+        </doctrine-mapping>
+
+    .. 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
+