Guilherme Blanco
commit
4b4126dfa6
@ -21,7 +21,7 @@ longitude/latitude pair to represent a geographic location.
|
||||
The entity
|
||||
----------
|
||||
|
||||
We create a simple entity whith a field ``$point`` which holds a value object
|
||||
We create a simple entity with a field ``$point`` which holds a value object
|
||||
``Point`` representing the latitude and longitude of the position.
|
||||
|
||||
The entity class:
|
||||
|
||||
@ -4,7 +4,7 @@ Persisting the Decorator Pattern
|
||||
.. sectionauthor:: Chris Woodford <chris.woodford@gmail.com>
|
||||
|
||||
This recipe will show you a simple example of how you can use
|
||||
Doctrine 2 to persist an implementaton of the
|
||||
Doctrine 2 to persist an implementation of the
|
||||
`Decorator Pattern <http://en.wikipedia.org/wiki/Decorator_pattern>`_
|
||||
|
||||
Component
|
||||
@ -114,7 +114,7 @@ use a ``MappedSuperclass`` for this.
|
||||
protected $decorates;
|
||||
|
||||
/**
|
||||
* intialize the decorator
|
||||
* initialize the decorator
|
||||
* @param Component $c
|
||||
*/
|
||||
public function __construct(Component $c)
|
||||
|
||||
@ -47,7 +47,7 @@ Entities that are serialized into the session normally contain references to
|
||||
other entities as well. Think of the user entity has a reference to his
|
||||
articles, groups, photos or many other different entities. If you serialize
|
||||
this object into the session then you don't want to serialize the related
|
||||
entities aswell. This is why you should call ``EntityManager#detach()`` on this
|
||||
entities as well. This is why you should call ``EntityManager#detach()`` on this
|
||||
object or implement the __sleep() magic method on your entity.
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@ -24,7 +24,7 @@ because they can be used in other systems without each other, but for
|
||||
our application we want to use them together.
|
||||
|
||||
In this case, we have an ``Invoice`` entity with a relationship to a
|
||||
non-existant object, an ``InvoiceSubjectInterface``. The goal is to get
|
||||
non-existent object, an ``InvoiceSubjectInterface``. The goal is to get
|
||||
the ``ResolveTargetEntityListener`` to replace any mention of the interface
|
||||
with a real object that implements that interface.
|
||||
|
||||
|
||||
@ -37,7 +37,7 @@ highly uncomfortable because of the following:
|
||||
block / entity. This would tear down any effort of modular
|
||||
programming.
|
||||
|
||||
Therefore, we need something thats far more flexible.
|
||||
Therefore, we need something that's far more flexible.
|
||||
|
||||
Solution
|
||||
--------
|
||||
|
||||
@ -81,7 +81,7 @@ In XML Mappings:
|
||||
<lifecycle-callback type="preUpdate" method="assertCustomerallowedBuying" />
|
||||
</lifecycle-callbacks>
|
||||
</entity>
|
||||
</doctirne-mapping>
|
||||
</doctrine-mapping>
|
||||
|
||||
YAML needs some little change yet, to allow multiple lifecycle
|
||||
events for one method, this will happen before Beta 1 though.
|
||||
|
||||
@ -66,7 +66,7 @@ The problem is simple. Not a single database vendor saves the timezone, only the
|
||||
However with frequent daylight saving and political timezone changes you can have a UTC offset that moves
|
||||
in different offset directions depending on the real location.
|
||||
|
||||
The solution for this dialemma is simple. Don't use timezones with DateTime and Doctrine 2. However there is a workaround
|
||||
The solution for this dilemma is simple. Don't use timezones with DateTime and Doctrine 2. However there is a workaround
|
||||
that even allows correct date-time handling with timezones:
|
||||
|
||||
1. Always convert any DateTime instance to UTC.
|
||||
@ -75,7 +75,7 @@ that even allows correct date-time handling with timezones:
|
||||
|
||||
Say we have an application for an international postal company and employees insert events regarding postal-package
|
||||
around the world, in their current timezones. To determine the exact time an event occurred means to save both
|
||||
the UTC time at the time of the booking and the timezone the event happend in.
|
||||
the UTC time at the time of the booking and the timezone the event happened in.
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@ -122,7 +122,7 @@ the UTC time at the time of the booking and the timezone the event happend in.
|
||||
|
||||
This database type makes sure that every DateTime instance is always saved in UTC, relative
|
||||
to the current timezone that the passed DateTime instance has. To be able to transform these values
|
||||
back into their real timezone you have to save the timezone in a seperate field of the entity
|
||||
back into their real timezone you have to save the timezone in a separate field of the entity
|
||||
requiring timezoned datetimes:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@ -15,9 +15,9 @@ This chapter is split into three different sections.
|
||||
|
||||
- A list of all the possible association mapping use-cases is given.
|
||||
- :ref:`association_mapping_defaults` are explained that simplify the use-case examples.
|
||||
- :ref:`collections` are introduced that contain entities in assoactions.
|
||||
- :ref:`collections` are introduced that contain entities in associations.
|
||||
|
||||
To master assocations you should also learn about :doc:`owning and inverse sides of associations <unitofwork-associations>`
|
||||
To master associations you should also learn about :doc:`owning and inverse sides of associations <unitofwork-associations>`
|
||||
|
||||
One-To-One, Unidirectional
|
||||
--------------------------
|
||||
|
||||
@ -18,7 +18,7 @@ object-relational mapping metadata:
|
||||
|
||||
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 aswell. There are dedicated
|
||||
alternative YAML and XML examples are given as well. There are dedicated
|
||||
reference chapters for XML and YAML mapping, respectively that explain them
|
||||
in more detail. There is also an Annotation reference chapter.
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@ Frequently Asked Questions
|
||||
.. note::
|
||||
|
||||
This FAQ is a work in progress. We will add lots of questions and not answer them right away just to remember
|
||||
what is often asked. If you stumble accross an unanswerd question please write a mail to the mailing-list or
|
||||
what is often asked. If you stumble across an unanswered question please write a mail to the mailing-list or
|
||||
join the #doctrine channel on Freenode IRC.
|
||||
|
||||
Database Schema
|
||||
@ -74,7 +74,7 @@ What is wrong when I get an InvalidArgumentException "A new entity was found thr
|
||||
|
||||
This exception is thrown during ``EntityManager#flush()`` when there exists an object in the identity map
|
||||
that contains a reference to an object that Doctrine does not know about. Say for example you grab
|
||||
a "User"-entity from the database with a specific id and set a completly new object into one of the associations
|
||||
a "User"-entity from the database with a specific id and set a completely new object into one of the associations
|
||||
of the User object. If you then call ``EntityManager#flush()`` without letting Doctrine know about
|
||||
this new object using ``EntityManager#persist($newObject)`` you will see this exception.
|
||||
|
||||
@ -96,7 +96,7 @@ By definition a One-To-Many association is on the inverse side, that means chang
|
||||
will not be recognized by Doctrine.
|
||||
|
||||
If you want to perform the equivalent of the clear operation you have to iterate the
|
||||
collection and set the owning side many-to-one reference to NULL aswell to detach all entities
|
||||
collection and set the owning side many-to-one reference to NULL as well to detach all entities
|
||||
from the collection. This will trigger the appropriate UPDATE statements on the database.
|
||||
|
||||
How can I add columns to a many-to-many table?
|
||||
@ -126,7 +126,7 @@ Why does pagination not work correctly with fetch joins?
|
||||
|
||||
Pagination in Doctrine uses a LIMIT clause (or vendor equivalent) to restrict the results.
|
||||
However when fetch-joining this is not returning the correct number of results since joining
|
||||
with a one-to-many or many-to-many association muliplies the number of rows by the number
|
||||
with a one-to-many or many-to-many association multiplies the number of rows by the number
|
||||
of associated entities.
|
||||
|
||||
See the previous question for a solution to this task.
|
||||
@ -142,11 +142,11 @@ Yes, you can use Single- or Joined-Table Inheritance in Doctrine 2.
|
||||
See the documentation chapter on :doc:`inheritance mapping <inheritance-mapping>` for
|
||||
the details.
|
||||
|
||||
Why does Doctrine not create proxy objects for my inheritance hierachy?
|
||||
Why does Doctrine not create proxy objects for my inheritance hierarchy?
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If you set a many-to-one or one-to-one association target-entity to any parent class of
|
||||
an inheritance hierachy Doctrine does not know what PHP class the foreign is actually of.
|
||||
an inheritance hierarchy Doctrine does not know what PHP class the foreign is actually of.
|
||||
To find this out it has to execute an SQL query to look this information up in the database.
|
||||
|
||||
EntityGenerator
|
||||
|
||||
@ -19,7 +19,7 @@ appear in the middle of an otherwise mapped inheritance hierarchy
|
||||
A mapped superclass cannot be an entity, it is not query-able and
|
||||
persistent relationships defined by a mapped superclass must be
|
||||
unidirectional (with an owning side only). This means that One-To-Many
|
||||
assocations are not possible on a mapped superclass at all.
|
||||
associations are not possible on a mapped superclass at all.
|
||||
Furthermore Many-To-Many associations are only possible if the
|
||||
mapped superclass is only used in exactly one entity at the moment.
|
||||
For further support of inheritance, the single or
|
||||
|
||||
@ -146,7 +146,7 @@ extensions out there that offer support for Nested Set with
|
||||
Doctrine 2:
|
||||
|
||||
|
||||
- `Doctrine2 Hierachical-Structural Behavior <http://github.com/guilhermeblanco/Doctrine2-Hierarchical-Structural-Behavior>`_
|
||||
- `Doctrine2 Hierarchical-Structural Behavior <http://github.com/guilhermeblanco/Doctrine2-Hierarchical-Structural-Behavior>`_
|
||||
- `Doctrine2 NestedSet <http://github.com/blt04/doctrine2-nestedset>`_
|
||||
|
||||
Known Issues
|
||||
|
||||
@ -170,7 +170,7 @@ Getting ClassMetadata Instances
|
||||
-------------------------------
|
||||
|
||||
If you want to get the ``ClassMetadata`` instance for an entity in
|
||||
your project to programatically use some mapping information to
|
||||
your project to programmatically use some mapping information to
|
||||
generate some HTML or something similar you can retrieve it through
|
||||
the ``ClassMetadataFactory``:
|
||||
|
||||
|
||||
@ -390,7 +390,7 @@ in your sQL statement:
|
||||
$rsm->addRootEntityFromClassMetadata('MyProject\User', 'u');
|
||||
$rsm->addJoinedEntityFromClassMetadata('MyProject\Address', 'a', 'u', 'address', array('id' => 'address_id'));
|
||||
|
||||
For entites with more columns the builder is very convenient to use. It extends the ``ResultSetMapping`` class
|
||||
For entities with more columns the builder is very convenient to use. It extends the ``ResultSetMapping`` class
|
||||
and as such has all the functionality of it as well. Currently the ``ResultSetMappingBuilder`` does not support
|
||||
entities with inheritance.
|
||||
|
||||
|
||||
@ -161,10 +161,10 @@ The API of the ClassMetadataBuilder has the following methods with a fluent inte
|
||||
It also has several methods that create builders (which are necessary for advanced mappings):
|
||||
|
||||
- ``createField($name, $type)`` returns a ``FieldBuilder`` instance
|
||||
- ``createManyToOne($name, $targetEntity)`` returns an ``AssocationBuilder`` instance
|
||||
- ``createOneToOne($name, $targetEntity)`` returns an ``AssocationBuilder`` instance
|
||||
- ``createManyToMany($name, $targetEntity)`` returns an ``ManyToManyAssocationBuilder`` instance
|
||||
- ``createOneToMany($name, $targetEntity)`` returns an ``OneToManyAssocationBuilder`` instance
|
||||
- ``createManyToOne($name, $targetEntity)`` returns an ``AssociationBuilder`` instance
|
||||
- ``createOneToOne($name, $targetEntity)`` returns an ``AssociationBuilder`` instance
|
||||
- ``createManyToMany($name, $targetEntity)`` returns an ``ManyToManyAssociationBuilder`` instance
|
||||
- ``createOneToMany($name, $targetEntity)`` returns an ``OneToManyAssociationBuilder`` instance
|
||||
|
||||
ClassMetadataInfo API
|
||||
---------------------
|
||||
|
||||
@ -28,7 +28,7 @@ Configuration (PEAR)
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Whenever the ``doctrine`` command line tool is invoked, it can
|
||||
access alls Commands that were registered by developer. There is no
|
||||
access all Commands that were registered by developer. There is no
|
||||
auto-detection mechanism at work. The Doctrine binary
|
||||
already registers all the commands that currently ship with
|
||||
Doctrine DBAL and ORM. If you want to use additional commands you
|
||||
@ -300,7 +300,7 @@ to error and we suggest you use code repositories such as GIT or SVN to make
|
||||
backups of your code.
|
||||
|
||||
It makes sense to generate the entity code if you are using entities as Data
|
||||
Access Objects only and dont put much additional logic on them. If you are
|
||||
Access Objects only and don't put much additional logic on them. If you are
|
||||
however putting much more logic on the entities you should refrain from using
|
||||
the entity-generator and code your entities manually.
|
||||
|
||||
@ -319,7 +319,7 @@ Convert Mapping Information
|
||||
Convert mapping information between supported formats.
|
||||
|
||||
This is an **execute one-time** command. It should not be necessary for
|
||||
you to call this method multiple times, escpecially when using the ``--from-database``
|
||||
you to call this method multiple times, especially when using the ``--from-database``
|
||||
flag.
|
||||
|
||||
Converting an existing database schema into mapping files only solves about 70-80%
|
||||
|
||||
@ -8,7 +8,7 @@ following general rules apply:
|
||||
- Relationships may be bidirectional or unidirectional.
|
||||
- A bidirectional relationship has both an owning side and an inverse side
|
||||
- A unidirectional relationship only has an owning side.
|
||||
- Doctrine will **only** check the owning side of an assocation for changes.
|
||||
- Doctrine will **only** check the owning side of an association for changes.
|
||||
|
||||
Bidirectional Associations
|
||||
--------------------------
|
||||
@ -22,16 +22,16 @@ The following rules apply to **bidirectional** associations:
|
||||
OneToOne, ManyToOne, or ManyToMany mapping declaration.
|
||||
The inversedBy attribute contains the name of the association-field
|
||||
on the inverse-side.
|
||||
- ManyToOne is always the owning side of a bidirectional assocation.
|
||||
- OneToMany is always the inverse side of a bidirectional assocation.
|
||||
- The owning side of a OneToOne assocation is the entity with the table
|
||||
- ManyToOne is always the owning side of a bidirectional association.
|
||||
- OneToMany is always the inverse side of a bidirectional association.
|
||||
- The owning side of a OneToOne association is the entity with the table
|
||||
containing the foreign key.
|
||||
- You can pick the owning side of a many-to-many assocation yourself.
|
||||
- You can pick the owning side of a many-to-many association yourself.
|
||||
|
||||
Important concepts
|
||||
------------------
|
||||
|
||||
**Doctrine will only check the owning side of an assocation for changes.**
|
||||
**Doctrine will only check the owning side of an association for changes.**
|
||||
|
||||
To fully understand this, remember how bidirectional associations
|
||||
are maintained in the object world. There are 2 references on each
|
||||
|
||||
@ -12,7 +12,7 @@ its UnitOfWork. The array holding all the entity references is two-levels deep
|
||||
and has the keys "root entity name" and "id". Since Doctrine allows composite
|
||||
keys the id is a sorted, serialized version of all the key columns.
|
||||
|
||||
This allows Doctrine room for optimizations. If you call the EntiyManager and
|
||||
This allows Doctrine room for optimizations. If you call the EntityManager and
|
||||
ask for an entity with a specific ID twice, it will return the same instance:
|
||||
|
||||
.. code-block:: php
|
||||
@ -117,7 +117,7 @@ that consume new memory.
|
||||
Now whenever you call ``EntityManager#flush`` Doctrine will iterate over the
|
||||
Identity Map and for each object compares the original property and association
|
||||
values with the values that are currently set on the object. If changes are
|
||||
detected then the object is qeued for an SQL UPDATE operation. Only the fields
|
||||
detected then the object is queued for an SQL UPDATE operation. Only the fields
|
||||
that actually changed are updated.
|
||||
|
||||
This process has an obvious performance impact. The larger the size of the
|
||||
|
||||
@ -474,9 +474,9 @@ operations.
|
||||
Effects of Database and UnitOfWork being Out-Of-Sync
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
As soon as you begin to change the state ofentities, call persist or remove the
|
||||
As soon as you begin to change the state of entities, call persist or remove the
|
||||
contents of the UnitOfWork and the database will drive out of sync. They can
|
||||
only be sychronized by calling ``EntityManager#flush()``. This section
|
||||
only be synchronized by calling ``EntityManager#flush()``. This section
|
||||
describes the effects of database and UnitOfWork being out of sync.
|
||||
|
||||
- Entities that are scheduled for removal can still be queried from the database.
|
||||
|
||||
@ -112,7 +112,7 @@ and to ``year`` to the related entities.
|
||||
|
||||
.. note::
|
||||
|
||||
This example shows how you can nicely solve the requirement for exisiting
|
||||
This example shows how you can nicely solve the requirement for existing
|
||||
values before ``EntityManager#persist()``: By adding them as mandatory values for the constructor.
|
||||
|
||||
Identity through foreign Entities
|
||||
@ -135,7 +135,7 @@ of one or many parent entities.
|
||||
The semantics of mapping identity through foreign entities are easy:
|
||||
|
||||
- Only allowed on Many-To-One or One-To-One associations.
|
||||
- Plug an ``@Id`` annotation onto every assocation.
|
||||
- Plug an ``@Id`` annotation onto every association.
|
||||
- Set an attribute ``association-key`` with the field name of the association in XML.
|
||||
- Set a key ``associationKey:`` with the field name of the association in YAML.
|
||||
|
||||
|
||||
@ -3,8 +3,8 @@ Extra Lazy Associations
|
||||
|
||||
In many cases associations between entities can get pretty large. Even in a simple scenario like a blog.
|
||||
where posts can be commented, you always have to assume that a post draws hundreds of comments.
|
||||
In Doctrine 2.0 if you accessed an association it would always get loaded completly into memory. This
|
||||
can lead to pretty serious performance problems, if your associations contain several hundrets or thousands
|
||||
In Doctrine 2.0 if you accessed an association it would always get loaded completely into memory. This
|
||||
can lead to pretty serious performance problems, if your associations contain several hundreds or thousands
|
||||
of entities.
|
||||
|
||||
With Doctrine 2.1 a feature called **Extra Lazy** is introduced for associations. Associations
|
||||
|
||||
@ -8,7 +8,7 @@ Getting Started: Model First
|
||||
you :doc:`Model First <getting-started-models>`, you are modelling your application using tools (for
|
||||
example UML) and generate database schema and PHP code from this model.
|
||||
When you have a :doc:`Database First <getting-started-database>`, then you already have a database schema
|
||||
and generate the correspdongin PHP code from it.
|
||||
and generate the corresponding PHP code from it.
|
||||
|
||||
.. note::
|
||||
|
||||
|
||||
@ -1348,7 +1348,7 @@ Entity Repositories
|
||||
|
||||
For now we have not discussed how to separate the Doctrine query logic from your model.
|
||||
In Doctrine 1 there was the concept of ``Doctrine_Table`` instances for this
|
||||
seperation. The similar concept in Doctrine2 is called Entity Repositories, integrating
|
||||
separation. The similar concept in Doctrine2 is called Entity Repositories, integrating
|
||||
the `repository pattern <http://martinfowler.com/eaaCatalog/repository.html>`_ at the heart of Doctrine.
|
||||
|
||||
Every Entity uses a default repository by default and offers a bunch of convenience
|
||||
@ -1380,7 +1380,7 @@ Compared to DQL these query methods are falling short of functionality very fast
|
||||
Doctrine offers you a convenient way to extend the functionalities of the default ``EntityRepository``
|
||||
and put all the specialized DQL query logic on it. For this you have to create a subclass
|
||||
of ``Doctrine\ORM\EntityRepository``, in our case a ``BugRepository`` and group all
|
||||
the previoiusly discussed query functionality in it:
|
||||
the previously discussed query functionality in it:
|
||||
|
||||
.. code-block:: php
|
||||
|
||||
@ -1428,7 +1428,7 @@ the previoiusly discussed query functionality in it:
|
||||
}
|
||||
}
|
||||
|
||||
Dont forget to add a `require_once` call for this class to the bootstrap.php
|
||||
Don't forget to add a `require_once` call for this class to the bootstrap.php
|
||||
|
||||
To be able to use this query logic through ``$this->getEntityManager()->getRepository('Bug')``
|
||||
we have to adjust the metadata slightly.
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
Ordering To-Many Assocations
|
||||
----------------------------
|
||||
Ordering To-Many Associations
|
||||
-----------------------------
|
||||
|
||||
There are use-cases when you'll want to sort collections when they are
|
||||
retrieved from the database. In userland you do this as long as you
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
Working with Indexed Assocations
|
||||
================================
|
||||
Working with Indexed Associations
|
||||
=================================
|
||||
|
||||
.. note::
|
||||
|
||||
@ -22,10 +22,10 @@ As an example we will design a simple stock exchange list view. The domain consi
|
||||
and ``Market`` where each Stock has a symbol and is traded on a single market. Instead of having a numerical
|
||||
list of stocks traded on a market they will be indexed by their symbol, which is unique across all markets.
|
||||
|
||||
Mapping Indexed Assocations
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Mapping Indexed Associations
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can map indexed assocations by adding:
|
||||
You can map indexed associations by adding:
|
||||
|
||||
* ``indexBy`` attribute to any ``@OneToMany`` or ``@ManyToMany`` annotation.
|
||||
* ``index-by`` attribute to any ``<one-to-many />`` or ``<many-to-many />`` xml element.
|
||||
@ -139,7 +139,7 @@ The code and mappings for the Market entity looks like this:
|
||||
indexBy: symbol
|
||||
|
||||
Inside the ``addStock()`` method you can see how we directly set the key of the association to the symbol,
|
||||
so that we can work with the indexed assocation directly after invoking ``addStock()``. Inside ``getStock($symbol)``
|
||||
so that we can work with the indexed association directly after invoking ``addStock()``. Inside ``getStock($symbol)``
|
||||
we pick a stock traded on the particular market by symbol. If this stock doesn't exist an exception is thrown.
|
||||
|
||||
The ``Stock`` entity doesn't contain any special instructions that are new, but for completeness
|
||||
@ -294,5 +294,5 @@ Outlook into the Future
|
||||
|
||||
For the inverse side of a many-to-many associations there will be a way to persist the keys and the order
|
||||
as a third and fourth parameter into the join table. This feature is discussed in `DDC-213 <http://www.doctrine-project.org/jira/browse/DDC-213>`_
|
||||
This feature cannot be implemeted for One-To-Many associations, because they are never the owning side.
|
||||
This feature cannot be implemented for One-To-Many associations, because they are never the owning side.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user