li3_doctrine / branches / master / readme.wiki
history ## li3_doctrine: The Lithium + Doctrine Integration Project
This plugin enables Lithium application developers to seamlessly implement all or part of their model layer using the [Doctrine Object-Relational Mapper](http://www.doctrine-project.org/).
To install, simply do the following (change the direction of slashes as necessary):
{{{
cd /path/to/your/app/libraries
git clone code@dev.lithify.me:li3_doctrine.git
}}}
Then, edit `app/config/bootstrap/libraries.php` and add the following:
{{{ Libraries::add('li3_doctrine'); }}}
Now you're almost ready to go. The only thing remaining is to install doctrine itself. Assuming the `li3` command is in your system path, you can do the following:
{{{
cd .. && li3 doctrine install
}}}
Finally, you must create a database connection with Doctrine. Edit `app/config/bootstrap/connections.php` and add the following:
{{{
Connections::add('default', array(
'type' => 'doctrine',
'driver' => 'pdo_mysql',
'host' => 'localhost',
'user' => 'root',
'password' => 'password',
'dbname' => 'blog_li3'
));
}}}
You can now use Doctrine models in your app, add standard
doctrine entities to the model directory, example:
{{{<?php
// app/models/User.php
namespace app\models;
/**
* @Entity
*/
class User
{
/**
* @Id
* @Column(type="integer")
* @GeneratedValue(strategy="IDENTITY")
*/
protected $id;
/**
* @Column(type="string", length="255")
*/
protected $name;
public function setName($name)
{
$this->name = $name;
}
public function getName()
{
return $this->name;
}
}
?>}}}
Then this can be model can be used and accessed from your controller in the following fashion:
First be sure to include the relevant namespace and use statements
{{{namespace app\controllers;
use \app\models\User;
use \lithium\data\Connections;}}}
Then inside your action methods you can use the following
{{{$em = Connections::get('default')->getEntityManager();
$user = new User();
$user->setName('Lithium Guy');
$em->persist($user);
$em->flush();}}}
## Using Repositories
Doctrine recommends the use a data presentation layer called a 'repository', these have been referred to as a 'Data Access Object' or 'DAO' in other languages. This is where you place much the business logic specific to getting data into your app. You can read more about repositories on the Doctrine website [here](http://www.doctrine-project.org/docs/orm/2.0/en/reference/working-with-objects.html?highlight=repositories#custom-repositories)
You can choose where you would like to store these repositories, but I recommend ```app/repositories``` or ```app/resources/repositories```. In your model/entity you must now specify where the repository is located.
#For Example
{{{namespace app\models;
/**
* @Entity(repositoryClass="app\resources\repositories\UserRepository")
*/
class User{
}}}
Because of the built in name-spacing in Lithium, Doctrine knows that the repository for the User can be found in the specified class location.
We can now create the file ```app/resources/repositories/UserRepository.php``` as in the trivial example below
{{{namespace app\resources\repositories;
use Doctrine\ORM\EntityRepository;
use app\models;
class UserRepository extends EntityRepository
{
public function getLithiumGuy()
{
return self::findOneBy(
array('name' => 'Lithium Guy')
);
}
}}}}
## Using the Doctrine Console
Doctrine has an excellent CLI(Command Line Interface) here you can control many of the doctrine features. We have made the plugin so that you can call this console right from within your app.
Providing the `li3` command is in your system path from the root of your app you can call ```li3 doctrine``` and it will alias to the Doctrine command. You can list the options by calling ```li3 doctrine```. So for example to create your proxy objects for your models/entities please call ```li3 doctrine orm:generate-proxies```.
One thing to be careful is that this defaults to your ```default``` connection. If you need to use a different connection use the connection flag in your command. Example ```li3 doctrine orm:generate-proxies --connection=other```
## Using Doctrine Migrations
We have now added the ability to use Doctrine Migrations. Once you have added your connection to a working database, from your commmand line go to the root of your application and type:
{{{li3 doctrine migrationinstall}}}
This will install all necessary configuration files, directories and latest version of the Doctrine Migrations project.
You can then type ```li3 doctrine list migrations``` for a full list of options. Type ```li3 doctrine migrations:generate``` to create your first migration. The migration files will be created in yourapp/migrations.
All migration commands are avaible as in [the Doctrine Migrations project documentation](http://www.doctrine-project.org/projects/migrations/2.0/docs/en) but with the ```./doctrine``` command being replaced by ```li3 doctrine```.