diff --git a/docs/en/reference/basic-mapping.rst b/docs/en/reference/basic-mapping.rst index c2b3aaa61..699df1d09 100644 --- a/docs/en/reference/basic-mapping.rst +++ b/docs/en/reference/basic-mapping.rst @@ -4,12 +4,12 @@ Basic Mapping This guide explains the basic mapping of entities and properties. After working through this guide you should know: -- How to create PHP classes that can be saved in the database with Doctrine +- How to create PHP objects that can be saved to the database with Doctrine; - How to configure the mapping between columns on tables and properties on - entities. -- What Doctrine Mapping types are -- Defining primary keys and how identifiers are generated by Doctrine -- How quoting of reserved symbols works in Doctrine + entities; +- What Doctrine mapping types are; +- Defining primary keys and how identifiers are generated by Doctrine; +- How quoting of reserved symbols works in Doctrine. Mapping of associations will be covered in the next chapter on :doc:`Association Mapping <association-mapping>`. @@ -23,11 +23,11 @@ Doctrine. Creating Classes for the Database --------------------------------- -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 +Every PHP object that you want to save in the database using Doctrine +is called an "Entity". The term "Entity" describes objects +that have an 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 +In this tutorial the following ``Message`` PHP class will serve as the example Entity: .. code-block:: php @@ -40,14 +40,14 @@ example Entity: private $postedAt; } -Because Doctrine is a generic library, it can only know about your -entities when you are describing their existance and structure using -Metadata Mapping, a pattern `described by Martin Fowler in PoEAA -<http://martinfowler.com/eaaCatalog/metadataMapping.html>`_. Because -of this pattern the documentation will often speak of "mapping something", -which means that we use the metadata mapping pattern to use this feature. +Because Doctrine is a generic library, it only knows about your +entities because you will describe their existence and structure using +mapping metadata, which is configuration that tells Doctrine how your +entity should be stored in the database. The documentation will often +speak of "mapping something", which means writing the mapping metadata +that describes your entity. -Doctrine provides several different ways for specifying object-relational +Doctrine provides several different ways to specify object-relational mapping metadata: - :doc:`Docblock Annotations <annotations-reference>` @@ -55,9 +55,8 @@ mapping metadata: - :doc:`YAML <yaml-mapping>` - :doc:`PHP code <php-mapping>` -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. +This manual will usually show mapping metadata via docblock annotations, though +many examples also show the equivalent configuration in YAML and XML. .. note:: @@ -65,10 +64,9 @@ XML examples are given as well. 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. + recommended!) then the XML driver is the fastest. -Marking our ``Message`` entity for Doctrine is straightforward: +Marking our ``Message`` class as an entity for Doctrine is straightforward: .. configuration-block:: @@ -95,7 +93,7 @@ Marking our ``Message`` entity for Doctrine is straightforward: type: entity # ... -With no additional information given Doctrine expects the entity to be saved +With no additional information, Doctrine expects the entity to be saved into a table with the same name as the class in our case ``Message``. You can change this by configuring information about the table: @@ -133,12 +131,13 @@ 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 +The next step after marking a PHP class as an entity is mapping its 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. +attribute specifies the :ref:`Doctrine Mapping Type <reference-mapping-types>` +to use for the field. If the type is not specified, ``string`` is used as the +default. .. configuration-block:: @@ -179,11 +178,12 @@ is not specified, ``string`` is used as the default mapping type. 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``. +When we don't explicitly specify a column name via the ``name`` option, Doctrine +assumes the field name is also the column name. This means that: + +* the ``id`` property will map to the column ``id`` using the type ``integer``; +* the ``text`` property will map to the column ``text`` with the default mapping type ``string``; +* the ``postedAt`` property will map to the ``posted_at`` column with the ``datetime`` type. The Column annotation has some more attributes. Here is a complete list: @@ -208,16 +208,18 @@ list: - ``options``: (optional) Key-value pairs of options that get passed to the underlying database platform when generating DDL statements. +.. _reference-mapping-types: + Doctrine Mapping Types ---------------------- The ``type`` option used in the ``@Column`` accepts any of the existing Doctrine types or even your own custom types. A Doctrine type defines -the conversion between PHP and SQL types, indepedant from the database vendor +the conversion between PHP and SQL types, independent from the database vendor you are using. All Mapping Types that ship with Doctrine are fully portable between the supported database systems. -As an example the Doctrine Mapping Type ``string`` defines the +As an example, the Doctrine Mapping Type ``string`` defines the mapping from a PHP string to a SQL VARCHAR (or VARCHAR2 etc. depending on the RDBMS brand). Here is a quick overview of the built-in mapping types: @@ -278,7 +280,7 @@ A cookbook article shows how to define :doc:`your own custom mapping types Identifiers / Primary Keys -------------------------- -Every entity class requires an identifier/primary key. You can select +Every entity class must have an identifier/primary key. You can select the field that serves as the identifier with the ``@Id`` annotation. @@ -331,7 +333,7 @@ Identifier Generation Strategies The previous example showed how to use the default identifier generation strategy without knowing the underlying database with the AUTO-detection strategy. It is also possible to specify the -identifier generation strategy more explicitly, which allows to +identifier generation strategy more explicitly, which allows you to make use of some additional features. Here is the list of possible generation strategies: