From 36d7d60c3b30055dfbab001896c6cb9b1565e915 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Thu, 12 Sep 2013 17:08:48 -0500 Subject: [PATCH 1/2] Minor updates while reading the basic-mapping page The only arguable changes involve a few spots where I either removed something I thought was too technical and not valuable (e.g. talking about the metadata mapping pattern). --- docs/en/reference/basic-mapping.rst | 72 +++++++++++++++-------------- 1 file changed, 37 insertions(+), 35 deletions(-) diff --git a/docs/en/reference/basic-mapping.rst b/docs/en/reference/basic-mapping.rst index c2b3aaa61..622af453b 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 classes 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 `. @@ -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 class 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 -`_. 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 specifying object-relational mapping metadata: - :doc:`Docblock Annotations ` @@ -55,9 +55,8 @@ mapping metadata: - :doc:`YAML ` - :doc:`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. +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 ` +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: From 1fcef3321e4bbe266a01481a10fc334a8d5d98c6 Mon Sep 17 00:00:00 2001 From: Ryan Weaver Date: Thu, 12 Sep 2013 20:52:12 -0500 Subject: [PATCH 2/2] Changes thanks to @Ocramius --- docs/en/reference/basic-mapping.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/en/reference/basic-mapping.rst b/docs/en/reference/basic-mapping.rst index 622af453b..699df1d09 100644 --- a/docs/en/reference/basic-mapping.rst +++ b/docs/en/reference/basic-mapping.rst @@ -4,7 +4,7 @@ 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 to 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; @@ -23,7 +23,7 @@ Doctrine. Creating Classes for the Database --------------------------------- -Every PHP class that you want to save in the database using Doctrine +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. @@ -47,7 +47,7 @@ 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 to specifying object-relational +Doctrine provides several different ways to specify object-relational mapping metadata: - :doc:`Docblock Annotations `