RetailCRM-Mirror/doctrine2
1
0
Fork 0
mirror of synced 2025-04-03 13:23:37 +03:00
Code Issues Projects Releases Wiki Activity

Reworked parts of the tutorial

Browse source
This commit is contained in:
Benjamin Eberlei 2013-03-16 23:36:36 +01:00
parent e0d706219b
commit bdfe6098a4
1 changed files with 115 additions and 115 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

230
docs/en/tutorials/getting-started.rst
View file

@ -1,47 +1,48 @@
Getting Started: Code First Getting Started with Doctrine
=========================== =============================
.. note:: *Development Workflows* This guide covers getting started with the Doctrine ORM. After working
through the guide you should know:
When you :doc:`Code First <getting-started>`, you - How to install and configure Doctrine by connecting it to a database
start with developing Objects and then map them onto your database. When - Mapping PHP objects to database tables
you :doc:`Model First <getting-started-models>`, you are modelling your application using tools (for - Generating a database schema from PHP objects
example UML) and generate database schema and PHP code from this model. - Using the ``EntityManager`` to insert, update, delete and find
When you have a :doc:`Database First <getting-started-database>`, then you already have a database schema objects in the database.
and generate the corresponding PHP code from it.
Doctrine 2 is an object-relational mapper (ORM) for PHP 5.3.0+ that provides Guide Assumptions
transparent persistence for PHP objects. It uses the Data Mapper pattern at -----------------
the heart of this project, aiming for a complete separation of the
domain/business logic from the persistence in a relational database management
system. The benefit of Doctrine for the programmer is the ability to focus
solely on the object-oriented business logic and worry about persistence only
as a secondary task. This doesn't mean persistence is not important to Doctrine
2, however it is our belief that there are considerable benefits for
object-oriented programming if persistence and entities are kept perfectly
separated.
Starting with the object-oriented model is called the *Code First* approach to This guide is designed for beginners that haven't worked with Doctrine ORM
Doctrine. before. There are some prerequesites for the tutorial that have to be
installed:
- PHP 5.3.3 or above
- Composer Package Manager (`Install Composer
<http://getcomposer.org/doc/00-intro.md>`_)
The code of this tutorial is `available on Github <https://github.com/doctrine/doctrine2-orm-tutorial>`_.
.. note:: .. note::
The code of this tutorial is `available on Github <https://github.com/doctrine/doctrine2-orm-tutorial>`_. This tutorial assumes you work with Doctrine 2.3 and above.
Some of the code will not work with lower versions.
What are Entities? What is Doctrine?
------------------ -----------------
Entities are lightweight PHP Objects that don't need to extend any Doctrine 2 is an `object-relational mapper (ORM)
abstract base class or interface. An entity class must not be final <http://en.wikipedia.org/wiki/Object-relational_mapping>`_ for PHP 5.3.3+ that
or contain final methods. Additionally it must not implement provides transparent persistence for PHP objects. It uses the Data Mapper
**clone** nor **wakeup** or :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`. pattern at the heart, aiming for a complete separation of your domain/business
logic from the persistence in a relational database management system.
See the :doc:`architecture chapter <../reference/architecture>` for a full list of the restrictions The benefit of Doctrine for the programmer is the ability to focus
that your entities need to comply with. on the object-oriented business logic and worry about persistence only
as a secondary problem. This doesn't mean persistence is downplayed by Doctrine
An entity contains persistable properties. A persistable property 2, however it is our belief that there are considerable benefits for
is an instance variable of the entity that is saved into and retrieved from the database object-oriented programming if persistence and entities are kept
by Doctrine's data mapping capabilities. separated.
An Example Model: Bug Tracker An Example Model: Bug Tracker
----------------------------- -----------------------------
@ -50,8 +51,7 @@ For this Getting Started Guide for Doctrine we will implement the
Bug Tracker domain model from the Bug Tracker domain model from the
`Zend\_Db\_Table <http://framework.zend.com/manual/en/zend.db.table.html>`_ `Zend\_Db\_Table <http://framework.zend.com/manual/en/zend.db.table.html>`_
documentation. Reading their documentation we can extract the documentation. Reading their documentation we can extract the
requirements to be: requirements:
- A Bugs has a description, creation date, status, reporter and - A Bugs has a description, creation date, status, reporter and
engineer engineer
@ -118,27 +118,47 @@ A first prototype
We start with a simplified design for the bug tracker domain, by creating three We start with a simplified design for the bug tracker domain, by creating three
classes ``Bug``, ``Product`` and ``User`` and putting them into classes ``Bug``, ``Product`` and ``User`` and putting them into
`entities/Bug.php`, `entities/Product.php` and `entities/User.php` `entities/Bug.php`, `entities/Product.php` and `entities/User.php`
respectively. respectively. We want instances of this three classes to be saved
in the database. A class saved into a database with Doctrine is called
entity. Entity classes are part of the domain model of your application.
.. code-block:: php .. code-block:: php
<?php <?php
// Bug.php // entities/Bug.php
class Bug class Bug
{ {
/**
* @var int
*/
protected $id; protected $id;
/**
* @var string
*/
protected $description; protected $description;
/**
* @var DateTime
*/
protected $created; protected $created;
/**
* @var string
*/
protected $status; protected $status;
} }
.. code-block:: php .. code-block:: php
<?php <?php
// Product.php // entities/Product.php
class Product class Product
{ {
/**
* @var int
*/
protected $id; protected $id;
/**
* @var string
*/
protected $name; protected $name;
public function getId() public function getId()
@ -160,11 +180,17 @@ respectively.
.. code-block:: php .. code-block:: php
<?php <?php
// User.php // entities/User.php
class User class User
{ {
/**
* @var int
*/
protected $id; protected $id;
public $name; // public for educational purpose, see below /**
* @var string
*/
protected $name;
public function getId() public function getId()
{ {
@ -182,47 +208,46 @@ respectively.
} }
} }
.. warning:: .. note::
Properties should never be public when using Doctrine. **What are Entities?**
This will lead to bugs with the way lazy loading works in Doctrine.
You see that all properties have getters and setters except `$id`. Entities are PHP Objects that can be identified over many requests
Doctrine 2 uses Reflection to access the values in all your entities properties, so it by a unique identifier or primary key. These classes don't need to extend any
is possible to set the `$id` value for Doctrine, however not from abstract base class or interface. An entity class must not be final
your application code. The use of reflection by Doctrine allows you or contain final methods. Additionally it must not implement
to completely encapsulate state and state changes in your entities. **clone** nor **wakeup** or :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
Many of the fields are single scalar values, for example the 3 ID An entity contains persistable properties. A persistable property
fields of the entities, their names, description, status and change is an instance variable of the entity that is saved into and retrieved from the database
dates. Doctrine 2 can easily handle these single values as can any by Doctrine's data mapping capabilities.
other ORM. From a point of our domain model they are ready to be
used right now and we will see at a later stage how they are mapped
to the database.
We will soon add references between objects in this domain Note how all properties have getter and setter methods defined except
model. The semantics are discussed case by case to `$id`. To access data from entities Doctrine 2 uses the Reflection API, so it
explain how Doctrine handles them. In general each OneToOne or is possible for Doctrine to access the value of `$id`. You don't have to
ManyToOne Relation in the Database is replaced by an instance of take Doctrine into account when designing access to the state of your objects.
the related object in the domain model. Each OneToMany or
ManyToMany Relation is replaced by a collection of instances in the
domain model. You never have to work with the foreign keys, only
with objects that represent the foreign key through their own identity.
If you think this through carefully you realize Doctrine 2 will All of the properties so far are scalar values, for example the 3 ID
load up the complete database in memory if you access one object. fields of the entities, their names, description, status and change dates.
However by default Doctrine generates Lazy Load proxies of entities
or collections of all the relations that haven't been explicitly With just the scalar values this model is useless. We need to add references
between entities in this domain model. The semantics of each type of reference
are now introduced and discussed on a case by case basis
to explain how Doctrine handles them.
In general each OneToOne or ManyToOne Relation in the Database is replaced by
an instance of the related object in the domain model. Each OneToMany or
ManyToMany Relation is replaced by a collection of instances in the domain
model. You never have to work with the foreign keys, only with objects that
represent the foreign key through their own identity.
To prevent Doctrine 2 from loading up the complete database in memory if you
access one object, the Lazy Load pattern is implemented. Proxies of entities or
collections are created of all the relations that haven't been explicitly
retrieved from the database yet. retrieved from the database yet.
To be able to use lazyload with collections, simple PHP arrays have Now that you know the basics about references in Doctrine, we can extend the
to be replaced by a generic collection interface for Doctrine which domain model to match the requirements:
tries to act as as much like an array as possible by using ArrayAccess,
IteratorAggregate and Countable interfaces. The class is the most
simple implementation of this interface.
Now that we know this, we have to clear up our domain model to cope
with the assumptions about related collections:
.. code-block:: php .. code-block:: php
@ -234,7 +259,7 @@ with the assumptions about related collections:
{ {
// ... (previous code) // ... (previous code)
protected $products = null; protected $products;
public function __construct() public function __construct()
{ {
@ -251,8 +276,8 @@ with the assumptions about related collections:
{ {
// ... (previous code) // ... (previous code)
protected $reportedBugs = null; protected $reportedBugs;
protected $assignedBugs = null; protected $assignedBugs;
public function __construct() public function __construct()
{ {
@ -1161,13 +1186,10 @@ Find by Primary Key
The next Use-Case is displaying a Bug by primary key. This could be The next Use-Case is displaying a Bug by primary key. This could be
done using DQL as in the previous example with a where clause, done using DQL as in the previous example with a where clause,
however there is a convenience method on the Entity Manager that however there is a convenience method on the ``EntityManager`` that
handles loading by primary key, which we have already seen in the handles loading by primary key, which we have already seen in the
write scenarios: write scenarios:
However we will soon see another problem with our entities using
this approach. Try displaying the engineer's name:
.. code-block:: php .. code-block:: php
<?php <?php
@ -1179,18 +1201,17 @@ this approach. Try displaying the engineer's name:
$bug = $entityManager->find("Bug", (int)$theBugId); $bug = $entityManager->find("Bug", (int)$theBugId);
echo "Bug: ".$bug->getDescription()."\n"; echo "Bug: ".$bug->getDescription()."\n";
// Accessing our special public $name property here on purpose: echo "Engineer: ".$bug->getEngineer()->getName()."\n";
echo "Engineer: ".$bug->getEngineer()->name."\n";
The output of the engineers name is null! What is happening? The output of the engineers name is fetched from the database! What is happening?
It worked in the previous example, so it can't be a problem with the persistence code of
Doctrine. What is it then? You walked in the public property trap.
Since we only retrieved the bug by primary key both the engineer Since we only retrieved the bug by primary key both the engineer and reporter
and reporter are not immediately loaded from the database but are are not immediately loaded from the database but are replaced by LazyLoading
replaced by LazyLoading proxies. Sample code of this proxy proxies. These proxies will load behind the scenes, when the first method
generated code can be found in the specified Proxy Directory, it is called on them.
looks like:
Sample code of this proxy generated code can be found in the specified Proxy
Directory, it looks like:
.. code-block:: php .. code-block:: php
@ -1218,26 +1239,9 @@ looks like:
} }
See how upon each method call the proxy is lazily loaded from the See how upon each method call the proxy is lazily loaded from the
database? Using public properties however we never call a method database?
and Doctrine has no way to hook into the PHP Engine to detect a
direct access to a public property and trigger the lazy load. We
need to rewrite our entities, make all the properties private or
protected and add getters and setters to get a working example:
.. code-block:: php The call prints:
<?php
// show_bug.php
require_once "bootstrap.php";
$theBugId = $argv[1];
$bug = $entityManager->find("Bug", (int)$theBugId);
echo "Bug: ".$bug->getDescription()."\n";
echo "Engineer: ".$bug->getEngineer()->getName()."\n";
Now prints:
:: ::
@ -1245,10 +1249,6 @@ Now prints:
Bug: Something does not work! Bug: Something does not work!
Engineer: beberlei Engineer: beberlei
Being required to use private or protected properties Doctrine 2
actually enforces you to encapsulate your objects according to
object-oriented best-practices.
Dashboard of the User Dashboard of the User
--------------------- ---------------------