From caf6ba65e8223a9e72514bc609bcbac0f2623185 Mon Sep 17 00:00:00 2001 From: Benjamin Eberlei Date: Tue, 10 Sep 2013 21:39:40 +0200 Subject: [PATCH] Refactor Basic Mapping chapter to focus on the actual topic more. Rearrange apperance of topics. Introduce a sane example entity as example. --- docs/en/reference/basic-mapping.rst | 256 ++++++++++++++-------------- 1 file changed, 125 insertions(+), 131 deletions(-) diff --git a/docs/en/reference/basic-mapping.rst b/docs/en/reference/basic-mapping.rst index d21a4d007..22ecc4d72 100644 --- a/docs/en/reference/basic-mapping.rst +++ b/docs/en/reference/basic-mapping.rst @@ -19,39 +19,52 @@ Guide Assumptions You should have already :doc:`installed and configure ` Doctrine. -Mapping Drivers ---------------- +Creating Classes for the Database +--------------------------------- -Doctrine provides several different ways for specifying -object-relational mapping metadata: +Every PHP Class that you want to save in the database using Doctrine +need to be marked as "Entity". The term "Entity" describes objects +that have identity over many independent requests. This identity is +usually achieved by assigning a unique identifier to an entity. +In this tutorial the following ``Message`` PHP class will serve as +example Entity: -- Docblock Annotations -- XML -- YAML +.. code-block:: php + + ` +- :doc:`XML ` +- :doc:`YAML ` - PHP code This manual usually mentions docblock annotations in all the examples that are spread throughout all chapters, however for many examples alternative YAML and -XML examples are given as well. There are dedicated reference chapters for -:doc:`XML ` and :doc:`YAML ` mapping, respectively -that explain them in more detail. There is also a reference chapter for -:doc:`Annotations `. +XML examples are given as well. .. note:: - All metadata drivers give exactly the same performance. Once the metadata - of a class has been read from the source (annotations, xml or yaml) it is - stored in an instance of the ``Doctrine\ORM\Mapping\ClassMetadata`` class - and these instances are stored in the metadata cache. Therefore at the end - of the day all drivers perform equally well. If you're not using a metadata - cache (not recommended!) then the XML driver is the fastest by using PHP's - native XML support. + All metadata drivers perform equally. Once the metadata of a class has been + read from the source (annotations, xml or yaml) it is stored in an instance + of the ``Doctrine\ORM\Mapping\ClassMetadata`` class and these instances are + stored in the metadata cache. If you're not using a metadata cache (not + recommended!) then the XML driver is the fastest by using PHP's native XML + support. -Persistent classes ------------------- - -Every PHP Class that you want to save in the database using Doctrine -need to be configured as "Entity". +Marking our ``Message`` entity for Doctrine is straightforward: .. configuration-block:: @@ -59,7 +72,7 @@ need to be configured as "Entity". - + .. code-block:: yaml - MyPersistentClass: + Message: type: entity # ... With no additional information given Doctrine expects the entity to be saved -into a table with the same name as the class. You can change this assumption -by adding more information about the used table: +into a table with the same name as the class in our case ``Message``. +You can change this by configuring information about the table: .. configuration-block:: @@ -89,9 +102,9 @@ by adding more information about the used table: - + .. code-block:: yaml - MyPersistentClass: + Message: type: entity - table: my_persistent_class + table: message # ... -In this example the class ``MyPersistentClass`` will be saved and fetched from -the table ``my_persistent_class``. +Now the class ``Message`` will be saved and fetched from the table ``message``. + +Property Mapping +---------------- + +The next step after defining a PHP class as entity is mapping of properties +to columns in a table. + +To configure a property use the ``@Column`` docblock annotation. The ``type`` +attribute specifies the Doctrine Mapping Type to use for the field. If the type +is not specified, ``string`` is used as the default mapping type. + +.. configuration-block:: + + .. code-block:: php + + + + + + + + + + .. code-block:: yaml + + Message: + type: entity + fields: + id: + type: integer + text: + length: 140 + postedAt: + type: datetime + name: posted_at + +Because we don't explicitly specify a column name, Doctrine assumes the field +name is also the column name. In the example we configured the property ``id`` to map to the column ``id`` +using the mapping type ``integer``. The field ``text`` is mapped to the column +``text`` with the default mapping type ``string`` and ``postedAt`` is of the +datetime type, but mapped to a column called ``posted_at``. + +The Column annotation has some more attributes. Here is a complete +list: + +- ``type``: (optional, defaults to 'string') The mapping type to + use for the column. +- ``name``: (optional, defaults to field name) The name of the + column in the database. +- ``length``: (optional, default 255) The length of the column in + the database. (Applies only if a string-valued column is used). +- ``unique``: (optional, default FALSE) Whether the column is a + unique key. +- ``nullable``: (optional, default FALSE) Whether the database + column is nullable. +- ``precision``: (optional, default 0) The precision for a decimal + (exact numeric) column. (Applies only if a decimal column is used.) +- ``scale``: (optional, default 0) The scale for a decimal (exact + numeric) column. (Applies only if a decimal column is used.) +- ``columnDefinition``: (optional) Allows to define a custom + DDL snippet that is used to create the column. Warning: This normally + confuses the SchemaTool to always detect the column as changed. +- ``options``: (optional) Key-value pairs of options that get passed + to the underlying database platform when generating DDL statements. Doctrine Mapping Types ---------------------- @@ -176,102 +266,6 @@ built-in mapping types: on working with datetimes that gives hints for implementing multi timezone applications. -Property Mapping ----------------- - -Properties of an entity class can be mapped to columns of the -SQL table of that entity. - -To configure a property use the ``@Column`` docblock annotation. This -annotation usually requires at least 1 attribute to be set, the ``type``. The -``type`` attribute specifies the Doctrine Mapping Type to use for the field. If -the type is not specified, ``string`` is used as the default mapping type. - - -Example: - -.. configuration-block:: - - .. code-block:: php - - - - - - - - - .. code-block:: yaml - - MyPersistentClass: - type: entity - fields: - id: - type: integer - name: - length: 50 - -In that example we configured the property ``id`` to map to the column ``id`` -using the mapping type ``integer``. The field ``name`` is mapped to the column -``name`` with the default mapping type ``string``. Column names are assumed to -be the same as the field names unless you specify a different name for the -column using the ``name`` attribute of the Column annotation: - -.. configuration-block:: - - .. code-block:: php - - - - - - - - .. code-block:: yaml - - MyPersistentClass: - type: entity - fields: - name: - length: 50 - column: db_name - -The Column annotation has some more attributes. Here is a complete -list: - -- ``type``: (optional, defaults to 'string') The mapping type to - use for the column. -- ``name``: (optional, defaults to field name) The name of the - column in the database. -- ``length``: (optional, default 255) The length of the column in - the database. (Applies only if a string-valued column is used). -- ``unique``: (optional, default FALSE) Whether the column is a - unique key. -- ``nullable``: (optional, default FALSE) Whether the database - column is nullable. -- ``precision``: (optional, default 0) The precision for a decimal - (exact numeric) column. (Applies only if a decimal column is used.) -- ``scale``: (optional, default 0) The scale for a decimal (exact - numeric) column. (Applies only if a decimal column is used.) Identifiers / Primary Keys --------------------------