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 look 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>
## Generating Entities
Doctrine can help you a little bit by generating the entity classes for your
mapping information with the command:
$ php console doctrine:generate: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:
:cache:clear-metadata Clear all metadata cache for a entity manager.
:cache:clear-query Clear all query cache for a entity manager.
:cache:clear-result Clear result cache for a entity manager.
:data:load Load data fixtures to your database.
:database:create Create the configured databases.
:database:drop Drop the configured databases.
: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:entity Generate a new Doctrine entity inside a bundle.
:generate:proxies Generates proxy classes for entity classes.
:generate:repositories Generate repository classes from your mapping information.
:mapping:convert Convert mapping information between supported formats.
:mapping:convert-d1-schema Convert a Doctrine 1 schema to Doctrine 2 mapping files.
:mapping:import Import mapping information from an existing database.
:query:dql Executes arbitrary DQL directly from the command line.
:query:sql Executes arbitrary SQL directly from the command line.
:schema:create Processes the schema and either create it directly on EntityManager Storage Connection or generate the SQL output.
:schema:drop Processes the schema and either drop the database schema of EntityManager Storage Connection or generate the SQL output.
:schema:update Processes the schema and either update the database schema of EntityManager Storage Connection or generate the SQL output.
### Schema Tool
The schema tool in Doctrine 2 allows you to easily drop and create your
database schemas for your mapping information.
You can easily create your initial schema from mapping information:
php console doctrine:schema:create
Or if you want to then drop your schema you can do:
php console doctrine:schema:drop
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: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** option.
>
> php console doctrine:schema:update --complete
### Doctrine Generate Entity Command
You can easily generate a new Doctrine entity for a bundle by using the
**doctrine:generate-entity** command:
$ php console doctrine:generate:entity "Bundle\MySampleBundle" "User\Group" --fields="name:string(255) description:text"
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:update
