DoctrineBundle
--------------

This document describes some of the functionality provided by the 
**DoctrineBundle**. Doctrine 2 is a first class citizen in Symfony 2 and is 
tightly integrated. Continue reading to learn how to use Doctrine 2 with the
latest Symfony 2!

## Configuration

This section will help you with configuring your Symfony 2 project to enable
the Doctrine DBAL and ORM services.

### Database Abstraction Layer

You can configure your database abstraction layer simply configuration a few 
pieces of information about your database. If you only have one database you can
do the following:

    [yml]
    doctrine.dbal:
      dbname: symfony_guestbook
      user: root
      password: ~

Or if you want to use XML instead of YAMl it would like like this:

    <doctrine:dbal dbname="symfony_guestbook" user="root" password="" />

Or if you have multiple connections and want to customize the configuration of the
connection further you can use the following:

    [yml]
    doctrine.dbal:
      default_connection:       default
      connections:
        default:
          driver:               PDOSqlite     # PDOSqlite, PDOMySql, PDOMsSql, PDOOracle, PDOPgSql, OCI8
          dbname:               symfony_guestbook
          user:                 root
          password:             null
          host:                 localhost
          port:                 ~
          path:                 %kernel.data_dir%/symfony.sqlite
          event_manager_class:  Doctrine\Common\EventManager
          configuration_class:  Doctrine\DBAL\Configuration
          wrapper_class:        ~
          options:              []

You can also specify multiple connections using the XML format:

    <doctrine:dbal default_connection="default">
        <doctrine:connection id="default" dbname="symfony_guestbook" user="root" password="" />
    </doctrine:dbal>

### Object Relational Mapper

If you want to enable the Doctrine 2 ORM you can do so with the following:

    doctrine.orm:
      default_entity_manager:   default
      cache_driver:             apc           # array, apc, memcache, xcache
      entity_managers:
        default:
          connection:           default

It's pretty simple, you can specify which entity managers you want to instantiate
for which connections and also configure some other information about the ORM
like what type of mapping files to use or what cache driver to use.

## Creating a Bundle

To get started we need to create a new bundle:

    $ php console init:bundle "Bundle\\GuestbookBundle"
    Initializing bundle "GuestbookBundle" in "/path/to/symfony-sandbox/src/Bundle"

Now basically the most important thing to know about using Doctrine 2 with Symfony
is where to put your mapping information files, where your entity classes are and 
a few commands to help move things faster!

## Mapping Information

You can place all your mapping information inside a bundle. Below is an example
path for the **GuestbookBundle** we created above:

    /path/to/symfony-sandbox/src/Bundle/GuestbookBundle/Resources/config/doctrine/metadata

Any files found in here that have a suffix of **.dcm.xml** (or whatever
mapping_driver you picked) are used as your entities mapping information.

In the **GuestbookBundle** we have a file named **Bundle.GuestbookBundle.Entities.Entry.dcm.xml**
which contains the following XML:

    <?xml version="1.0" encoding="UTF-8"?>

    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                              http://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">

        <entity name="Bundle\GuestbookBundle\Entities\Entry" table="guestbook_entry">

            <id name="id" type="integer" column="id">
                <generator strategy="AUTO"/>
            </id>

            <field name="createdAt" column="created_at" type="datetime" />
            <field name="name" column="name" type="string" length="255" />
            <field name="emailAddress" column="email_address" type="string" length="255" />
            <field name="body" column="body" type="text" />

        </entity>

    </doctrine-mapping>

## Building Entities

Doctrine can help you a little bit by generating the entity classes for your 
mapping information with the command:

    $ php console doctrine:build-entities

Now if you have a look in the bundles **Entities** directory you will see a new
file named **Entry.php** with some code like the following:

    [php]
    // Bundle/GuestbookBundle/Entities/Entry.php

    namespace Bundle\GuestbookBundle\Entities;

    /**
     * @Entity
     * @Table(name="guestbook_entry")
     */
    class Entry
    {
        /**
         * @Column(name="created_at", type="datetime")
         */
        private $createdAt;

        /**
         * @Column(name="name", type="string", length=255)
         */
        private $name;

    // ...

> **NOTE**
> If you modify your mapping information and re-run the build entities command
> it will modify the classes and update them based on the mapping information.

## Commands

The Doctrine 2 CLI is integrated with the Symfony 2 CLI so we have all the common
commands we need to make working with Doctrine 2 just as easy and fast as before!

### Listing Available Doctrine Commands

    $ php console list doctrine

    Available commands for the "doctrine" namespace:
      :build                       Build task for easily re-building your Doctrine development environment.
      :build-entities              Build all Bundle entity classes from mapping information.
      :clear-cache                 Clear cache from configured query, result and metadata drivers. (doctrine:cc)
      :convert-mapping             Convert mapping information between supported formats.
      :database-tool               Create and drop the configured databases.
      :ensure-production-settings  Verify that Doctrine is properly configured for a production environment.
      :generate-proxies            Generates proxy classes for entity classes.
      :import-mapping              Import the initial mapping information for entities from an existing database.
      :init-entity                 Initialize a new Doctrine entity inside a bundle.
      :load-data-fixtures          Load data fixtures to your database.
      :run-dql                     Executes arbitrary DQL directly from the command line.
      :run-sql                     Executes arbitrary SQL from a file or directly from the command line.
      :schema-tool                 Processes the schema and either apply it directly on EntityManager or generate the SQL output.
      :version                     Displays the current installed Doctrine version.

### Schema Tool

The schema tool in Doctrine 2 allows you to easily drop and your create your 
database schemas for your mapping information.

You can easily create your initial schema from mapping information:

    php console doctrine:schema-tool --create

Or if you want to then drop your schema you can do:

    php console doctrine:schema-tool --drop

If you want to re-create it (drop and create) you can use:

    php console doctrine:schema-tool --re-create

Now the scenario arrises where you want to change your mapping information and
update your database without blowing away everything and losing your existing data.
You can do the following for that:

    php console doctrine:schema-tool --update

> **TIP**
> The above will not drop anything from your database schema. To drop the remaining
> things from your schema you need to use the **--complete-update** option.
>
>     php console doctrine:schema-tool --complete-update

### Doctrine Build Command

The development workflow is very similar to how it is in Symfony 1.4. You can modify 
your mapping information and use **doctrine:build --all** to re-build your 
environment:

    php console doctrine:build --all

The recommend way to work is to re-build your entities and update your database
schema:

    php console doctrine:build --entities --and-update-schema

Now any changes you made in your mapping information will be reflected in the 
according databases! Here are all the available options for the **build** task:

> **NOTE**
> Not the key difference here is that you can modify your schema during development
> and just update your database schema without having to blow everything away and 
> re-build it all.

    $ php console help doctrine:build
    Usage:
     Symfony doctrine:build [--all] [--all-classes] [--entities] [--db] [--and-load[="..."]] [--and-append[="..."]] [--and-update-schema] [--dump-sql] [--connection]

    Options:
     --all   Build everything and reset the database
     --entities Build model classes
     --db    Drop database, create database and create schema.
     --and-load Load data fixtures (multiple values allowed)
     --and-append Load data fixtures and append to existing data (multiple values allowed)
     --and-update-schema Update schema after rebuilding all classes
     --connection The connection to use.

### Doctrine Init Entity Command

You can easily initialize a new Doctrine entity for a bundle by using the 
**doctrine:init-bundle** command:

    $ php console doctrine:init-entity --bundle="Bundle\MySampleBundle" --entity="User\Group"

Now if you have a look inside the bundle you will see that you have a **Group** class
located here **Bundle/MySampleBundle/Entities/User/Group.php**.

Now you can customize the mapping information for the entity by editing the metadata
information inside **Bundle/MySampleBundle/Resources/config/doctrine/metadata** and
just update your database schema:

    $ php console doctrine:schema-tool --update