Permalink
Browse files

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).
  • Loading branch information...
1 parent 067ed7b commit 36d7d60c3b30055dfbab001896c6cb9b1565e915 @weaverryan committed Sep 12, 2013
Showing with 37 additions and 35 deletions.
  1. +37 −35 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 <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,35 +40,33 @@ 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 specifying object-relational
mapping metadata:
- :doc:`Docblock Annotations <annotations-reference>`
- :doc:`XML <xml-mapping>`
- :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::
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.
+ 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:

0 comments on commit 36d7d60

Please sign in to comment.