doctrine2/manual/en/introduction.txt

++ 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). One of its 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. This provides developers with 
a powerful alternative to SQL that maintains flexibility without requiring 
unnecessary code duplication.

++ 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.

++ 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.phpdoctrine.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.phpdoctrine.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.phpdoctrine.org/DoctrineORM-2.0.0

When you have a package installed via PEAR you can required 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
    Available Tasks:
    core:help
    dbal:run-sql (--file=<path> | --sql=<SQL>) --depth=<DEPTH>
    orm:clear-cache (--query | --metadata | --result [--id=<ID>] [--regex=<REGEX>] [--prefix=<PREFIX>] [--suffix=<SUFFIX>])
    orm:convert-mapping (--from=<SOURCE> | --from-database) --to=<TYPE> --dest=<PATH>
    orm:ensure-production-settings
    orm:generate-proxies --class-dir=<PATH> [--to-dir=<PATH>]
    orm:run-dql --dql=<DQL> --depth=<DEPTH>
    orm:schema-tool (--create | --drop | --update | --complete-update | --re-create) [--dump-sql] [--class-dir=<PATH>]
    orm:version

+++ Package Download

You can also use Doctrine 2 by downloading the latest release package 
from [the download page](http://www.doctrine-project.org/download).

+++ Subversion

Alternatively you can check out the latest version of Doctrine 2 via SVN.

    $ svn co http://svn.doctrine-project.org/trunk doctrine
    
++ Sandbox Quickstart

> **NOTE**
> The sandbox is only available via SVN or soon as a separate download on the downloads
> page.

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 CLI 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 edit it so that it looks as follows:

    [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!".

5) Inspect the SQLite database. Again from within the tools/sandbox folder, 
execute the following command:

    $ php doctrine dbal:run-sql --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.

6) 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`.

7) Explore Doctrine 2!