297 lines
11 KiB
Plaintext
297 lines
11 KiB
Plaintext
++ Welcome
|
|
|
|
Doctrine 2 is an object-relational mapper (ORM) for PHP 5.3.0+ that provides
|
|
transparent persistence for PHP objects. It sits on top of a powerful database
|
|
abstraction layer (DBAL). Object-Relational Mappers primary task is the transparent
|
|
translation between (PHP) objects and relational database rows.
|
|
|
|
One of Doctrines key features is the option to write database queries in a
|
|
proprietary object oriented SQL dialect called Doctrine
|
|
Query Language (DQL), inspired by Hibernates HQL. Besides DQLs slight
|
|
differences to SQL it abstracts the mapping between database rows and
|
|
objects considerably, allowing developers to write powerful queries
|
|
in a simple and flexible fashion.
|
|
|
|
++ Disclaimer
|
|
|
|
This is the Doctrine 2 reference documentation. Introductory guides and tutorials
|
|
that you can follow along from start to finish, like the "Guide to Doctrine" book
|
|
known from the Doctrine 1.x series, will be available at a later date.
|
|
|
|
++ Using an Object-Relational Mapper
|
|
|
|
As the term ORM already hints at, Doctrine 2 aims to simplify the translation
|
|
between database rows and the PHP object model. The primary use case for Doctrine
|
|
are therefore applications that utilize the Object-Oriented Programming Paradigm.
|
|
For applications that not primarily work with objects Doctrine 2 is not suited very well.
|
|
|
|
++ Requirements
|
|
|
|
Doctrine 2 requires a minimum of PHP 5.3.0. For greatly improved performance it
|
|
is also recommended that you use APC with PHP.
|
|
|
|
++ Doctrine 2 Packages
|
|
|
|
Doctrine 2 is divided into three main packages.
|
|
|
|
* Common
|
|
* DBAL (includes Common)
|
|
* ORM (includes DBAL+Common)
|
|
|
|
This manual mainly covers the ORM package, sometimes touching parts of the
|
|
underlying DBAL and Common packages. The Doctrine code base is split in to these
|
|
packages for a few reasons and they are to...
|
|
|
|
* ...make things more maintainable and decoupled
|
|
* ...allow you to use the code in Doctrine Common without the ORM or DBAL
|
|
* ...allow you to use the DBAL without the ORM
|
|
|
|
+++ The Common Package
|
|
|
|
The Common package contains highly reusable components that have no dependencies
|
|
beyond the package itself (and PHP, of course). The root namespace of the
|
|
Common package is `Doctrine\Common`.
|
|
|
|
+++ The DBAL Package
|
|
|
|
The DBAL package contains an enhanced database abstraction layer on top of
|
|
PDO but is not strongly bound to PDO. The purpose of this layer is to provide a
|
|
single API that bridges most of the differences between the different RDBMS vendors.
|
|
The root namespace of the DBAL package is `Doctrine\DBAL`.
|
|
|
|
+++ The ORM Package
|
|
|
|
The ORM package contains the object-relational mapping toolkit that provides
|
|
transparent relational persistence for plain PHP objects. The root namespace of
|
|
the ORM package is `Doctrine\ORM`.
|
|
|
|
++ Installing
|
|
|
|
Doctrine can be installed many different ways. We will describe all the different
|
|
ways and you can choose which one suits you best.
|
|
|
|
+++ PEAR
|
|
|
|
You can easily install any of the three Doctrine packages from the PEAR command
|
|
line installation utility.
|
|
|
|
To install just the `Common` package you can run the following command:
|
|
|
|
$ sudo pear install pear.doctrine-project.org/DoctrineCommon-2.0.0
|
|
|
|
If you want to use the Doctrine Database Abstraction Layer you can install it
|
|
with the following command.
|
|
|
|
$ sudo pear install pear.doctrine-project.org/DoctrineDBAL-2.0.0
|
|
|
|
Or, if you want to get the works and go for the ORM you can install it with the
|
|
following command.
|
|
|
|
$ sudo pear install pear.doctrine-project.org/DoctrineORM-2.0.0
|
|
|
|
When you have a package installed via PEAR you can require and load the
|
|
`ClassLoader` with the following code.
|
|
|
|
[php]
|
|
require 'Doctrine/Common/ClassLoader.php';
|
|
$classLoader = new \Doctrine\Common\ClassLoader();
|
|
|
|
The packages are installed in to your shared PEAR PHP code folder in a folder
|
|
named `Doctrine`. You also get a nice command line utility installed and made
|
|
available on your system. Now when you run the `doctrine` command you will
|
|
see what you can do with it.
|
|
|
|
$ doctrine
|
|
Doctrine Command Line Interface version 2.0.0BETA3-DEV
|
|
|
|
Usage:
|
|
[options] command [arguments]
|
|
|
|
Options:
|
|
--help -h Display this help message.
|
|
--quiet -q Do not output any message.
|
|
--verbose -v Increase verbosity of messages.
|
|
--version -V Display this program version.
|
|
--color -c Force ANSI color output.
|
|
--no-interaction -n Do not ask any interactive question.
|
|
|
|
Available commands:
|
|
help Displays help for a command (?)
|
|
list Lists commands
|
|
dbal
|
|
:import Import SQL file(s) directly to Database.
|
|
:run-sql Executes arbitrary SQL directly from the command line.
|
|
orm
|
|
:convert-d1-schema Converts Doctrine 1.X schema into a Doctrine 2.X schema.
|
|
:convert-mapping Convert mapping information between supported formats.
|
|
:ensure-production-settings Verify that Doctrine is properly configured for a production environment.
|
|
:generate-entities Generate entity classes and method stubs from your mapping information.
|
|
:generate-proxies Generates proxy classes for entity classes.
|
|
:generate-repositories Generate repository classes from your mapping information.
|
|
:run-dql Executes arbitrary DQL directly from the command line.
|
|
:validate-schema Validate that the mapping files.
|
|
orm:clear-cache
|
|
:metadata Clear all metadata cache of the various cache drivers.
|
|
:query Clear all query cache of the various cache drivers.
|
|
:result Clear result cache of the various cache drivers.
|
|
orm:schema-tool
|
|
:create Processes the schema and either create it directly on EntityManager Storage Connection or generate the SQL output.
|
|
:drop Processes the schema and either drop the database schema of EntityManager Storage Connection or generate the SQL output.
|
|
:update Processes the schema and either update the database schema of EntityManager Storage Connection or generate the SQL output.
|
|
|
|
+++ Package Download
|
|
|
|
You can also use Doctrine 2 by downloading the latest release package
|
|
from [the download page](http://www.doctrine-project.org/download).
|
|
|
|
+++ GitHub
|
|
|
|
Alternatively you can clone the latest version of Doctrine 2 via GitHub.com:
|
|
|
|
$ git clone git://github.com/doctrine/doctrine2.git doctrine
|
|
|
|
This downloads all the sources of the ORM package. You need to initialize the Github
|
|
submodules for the Common and DBAL package dependencies:
|
|
|
|
$ git submodule init
|
|
$ git submodule update
|
|
|
|
This updates your Git checkout to use the Doctrine\Common and Doctrine\DBAL package
|
|
versions that are recommended for the cloned Master version of Doctrine 2.
|
|
|
|
> **NOTE**
|
|
>
|
|
> You should not combine the Doctrine-Common, Doctrine-DBAL and Doctrine-ORM master commits
|
|
> with each other in combination. The ORM may not work with the current Common or DBAL master versions.
|
|
> Instead the ORM ships with the Git Submodules that are required.
|
|
|
|
+++ Subversion
|
|
|
|
> **NOTE**
|
|
>
|
|
> Using the SVN Mirror is not recommended. It only allows access to the latest master commit
|
|
> and does not automatically fetch the submodules.
|
|
|
|
If you prefer subversion you can also checkout the code from GitHub.com through
|
|
the subversion protocol:
|
|
|
|
$ svn co http://svn.github.com/doctrine/doctrine2.git doctrine2
|
|
|
|
However this only allows you to check out the current master of Doctrine 2, without
|
|
the Common and DBAL dependencies. You have to grab them yourself, but might run
|
|
into version incompatibilities between the different master branches of Common, DBAL
|
|
and ORM.
|
|
|
|
++ Sandbox Quickstart
|
|
|
|
> **NOTE**
|
|
> The sandbox is only available via the Doctrine2 Github Repository or soon as a separate download on the downloads
|
|
> page. You will find it in the $root/tools/sandbox folder.
|
|
|
|
The sandbox is a pre-configured environment for evaluating and playing
|
|
with Doctrine 2.
|
|
|
|
+++ Overview
|
|
|
|
After navigating to the sandbox directory, you should see the following structure:
|
|
|
|
sandbox/
|
|
Entities/
|
|
Address.php
|
|
User.php
|
|
xml/
|
|
Entities.Address.dcm.xml
|
|
Entities.User.dcm.xml
|
|
yaml/
|
|
Entities.Address.dcm.yml
|
|
Entities.User.dcm.yml
|
|
cli-config.php
|
|
doctrine
|
|
doctrine.php
|
|
index.php
|
|
|
|
Here is a short overview of the purpose of these folders and files:
|
|
|
|
* The `Entities` folder is where any model classes are created. Two example entities are already there.
|
|
* The `xml` folder is where any XML mapping files are created (if you want to use XML mapping). Two example mapping documents for the 2 example entities are already there.
|
|
* The `yaml` folder is where any YAML mapping files are created (if you want to use YAML mapping). Two example mapping documents for the 2 example entities are already there.
|
|
* The `cli-config.php` contains bootstrap code for a configuration that is used by the Console tool `doctrine` whenever you execute a task.
|
|
* `doctrine`/`doctrine.php` is a command-line tool.
|
|
* `index.php` is a basic classical bootstrap file of a php application that uses Doctrine 2.
|
|
|
|
+++ Mini-tutorial
|
|
|
|
1) From within the tools/sandbox folder, run the following command and you should
|
|
see the same output.
|
|
|
|
$ php doctrine orm:schema-tool:create
|
|
Creating database schema...
|
|
Database schema created successfully!
|
|
|
|
2) Take another look into the tools/sandbox folder. A SQLite database should
|
|
have been created with the name `database.sqlite`.
|
|
|
|
3) Open `index.php` and at the bottom edit it so it looks like the following:
|
|
|
|
[php]
|
|
//... bootstrap stuff
|
|
|
|
## PUT YOUR TEST CODE BELOW
|
|
|
|
$user = new \Entities\User;
|
|
$user->setName('Garfield');
|
|
$em->persist($user);
|
|
$em->flush();
|
|
|
|
echo "User saved!";
|
|
|
|
Open index.php in your browser or execute it on the command line. You should see
|
|
the output "User saved!".
|
|
|
|
4) Inspect the SQLite database. Again from within the tools/sandbox folder,
|
|
execute the following command:
|
|
|
|
$ php doctrine dbal:run-sql "select * from users"
|
|
|
|
You should get the following output:
|
|
|
|
array(1) {
|
|
[0]=>
|
|
array(2) {
|
|
["id"]=>
|
|
string(1) "1"
|
|
["name"]=>
|
|
string(8) "Garfield"
|
|
}
|
|
}
|
|
|
|
You just saved your first entity with a generated ID in an SQLite database.
|
|
|
|
5) Replace the contents of index.php with the following:
|
|
|
|
[php]
|
|
//... bootstrap stuff
|
|
|
|
## PUT YOUR TEST CODE BELOW
|
|
|
|
$q = $em->createQuery('select u from Entities\User u where u.name = ?1');
|
|
$q->setParameter(1, 'Garfield');
|
|
$garfield = $q->getSingleResult();
|
|
|
|
echo "Hello " . $garfield->getName() . "!";
|
|
|
|
You just created your first DQL query to retrieve the user with the name
|
|
'Garfield' from an SQLite database (Yes, there is an easier way to do it,
|
|
but we wanted to introduce you to DQL at this point. Can you **find** the easier way?).
|
|
|
|
> **TIP**
|
|
> When you create new model classes or alter existing ones you can recreate the database
|
|
> schema with the command `doctrine orm:schema-tool --drop` followed by
|
|
> `doctrine orm:schema-tool --create`.
|
|
|
|
6) Explore Doctrine 2!
|
|
|
|
See the following links if you want to start with more complex tutorials rather than reading the manual:
|
|
|
|
* Doctrine2 Cookbook: [Getting Started XML Edition](http://www.doctrine-project.org/projects/orm/2.0/docs/cookbook/getting-started-xml-edition/en)
|