Doctrine是一个基于PHP的对象关系映射(ORM),它构建在强大的数据库抽象层(DBAL)之上,透明地为PHP对象提供持久化。
你可以从官方文档中读到更多关于Doctrine ORM 的内容。
首先,先激活和配置Doctrine DBAL,然后激活ORM。如果你遵循本章的说明和约定,你只需要告诉Doctrine自动映射你的实体:
- # app/config/config.yml
- doctrine:
- orm:
- auto_mapping: true
因为Doctrine透明地提供PHP对象的持久化,所以它可以与任何PHP类一起工作:
- // src/Acme/HelloBundle/Entity/User.php
- namespace Acme\HelloBundle\Entity;
- class User
- {
- protected $id;
- protected $name;
- public function getId()
- {
- return $this->id;
- }
- public function setName($name)
- {
- $this->name = $name;
- }
- public function getName()
- {
- return $this->name;
- }
- }
当你的实体被定义之后,当你使用doctrine:generate:entities命令时,你可以忽略getter/setter方法而让Doctrine为你创建它们。这只在你创建了映射信息之后才能正常工作(参见下面)
为了让Doctrine管理你的类(Doctrine2中叫实体),你需要使用注释、XML或YAML来编写映射信息:
- // src/Acme/HelloBundle/Entity/User.php
- namespace Acme\HelloBundle\Entity;
- use Doctrine\ORM\Mapping as ORM;
- /**
- * @ORM\Entity
- */
- class User
- {
- /**
- * @ORM\Id
- * @ORM\Column(type="integer")
- * @ORM\GeneratedValue(strategy="AUTO")
- */
- protected $id;
- /**
- * @ORM\Column(type="string", length="255")
- */
- protected $name;
- }
当你在Symfony2项目中使用注释时,你不得不将所有Doctrine ORM的名字空间注释都使用rom:前缀。
如果你使用YAML或XML去描述你的实体时,你可以忽略实体类的创建,并让doctrine:generate:entities命令来为你自动生成。
为了不用为每个实体创建一个文件,你也可以在doctrine.orm.yml文件中定义你的映射信息。
用下列命令创建与你元数据信息相关的数据库和模式
- $ php app/console doctrine:database:create
- $ php app/console doctrine:schema:create
最后,使用你的实体,并且用Doctrine来管理它的持久化状态:
- // src/Acme/HelloBundle/Controller/UserController.php
- namespace Acme\HelloBundle\Controller;
- use Acme\HelloBundle\Entity\User;
- class UserController extends Controller
- {
- public function createAction()
- {
- $user = new User();
- $user->setName('Jonathan H. Wage');
- $em = $this->get('doctrine')->getEntityManager();
- $em->persist($user);
- $em->flush();
- // ...
- }
- public function editAction($id)
- {
- $em = $this->get('doctrine')->getEntityManager();
- $user = $em->find('AcmeHelloBundle:User', $id);
- $user->setBody('new body');
- $em->persist($user);
- $em->flush();
- // ...
- }
- public function deleteAction($id)
- {
- $em = $this->get('doctrine')->getEntityManager();
- $user = $em->find('AcmeHelloBundle:User', $id);
- $em->remove($user);
- $em->flush();
- // ...
- }
- }
现在问题出现了,如果你想改变你的映射信息并更新你的开发数据库模式,而不想丢掉设置并失去已有数据的话,那么首先我们应该在我们的User实体中添加一个new属性:
- // src/Acme/HelloBundle/Entity/User.php
- namespace Acme\HelloBundle\Entity;
- use Doctrine\ORM\Mapping as ORM;
- /** @ORM\Entity */
- class User
- {
- /** @ORM\Column(type="string") */
- protected $new;
- // ...
- }
当你需要那样做,将你的数据库模式更新到new字段时,你只需要去运行下列命令:
- $ php app/console doctrine:schema:update
现在你的数据库被更新且new字段被添加到数据库的数据表中。
查询
如你所见,使用实体管理器操作一个对象是简单容易的。但你如何查询对象集呢?如同所有Doctrine操作一样,这也是可以通过实体管理器做到的。在上个例子中可以使用查询语句来改变删除先引导对象再将其删除的删除方法:
- public function deleteAction($id)
- {
- $query = $this->get('doctrine')->getEntityManager()
- ->createQuery('DELETE FROM Acme\HelloBundle\Entity\User u
- WHERE u.id = :id');
- $query->setParameters(array(
- 'id' => $id
- ));
- $query->execute();
- // ...
- }
当然,你也可以使用SELECT和UPDATE查询。Doctrine带来了它自己的查询语言DQL(Doctrine Query Language)。DQL跟SQL有些相似,但查询语言有它自己的语法。
你可以在官方网站查看更多关于Doctrine查询语言 。DQL的优点在于它是数据库未知的,也就是说使用DQL所写的同一查询可以在任何支持的数据库引擎上工作。
使用DQL的DELETE或UPDATE语句是有缺陷的。具体来说,因为是直接对数据库操作,Doctrine并不知道内部细节。举个例子,如果你对一个对象查询,然后通过UPDATE语句直接在数据库中对该对象进行更新,该对象本身不会反映这个更新。因此,小心使用这些语句,在单个请求里,你的对象可能会和你数据库不同步。
Repositories
在Symfony2的控制器中使用查询是很不好的做法,查询应该在你Bundle的模型层中使用,以便能够测试它们并在你的应用程序中重用。幸运地是,Doctrine允许你使用名为Repositories的特殊类来封装查询。
Doctrine为你的repository类提供了一个缺省实现,因此你可以使用它们的通用方法去查询你的实体数据。其中之一就是findAll方法。
- $em = $this->get('doctrine')->getEntityManager();
- $users = $em->getRepository('AcmeHelloBundle:User')->findAll();
如果你想创建你自己的函数去查询和维护你的数据,你需要为一个实体创建一个自定义的Repository类。要做到这一点,你需要在你的映射定义中添加repository类的名称。
- // src/Acme/HelloBundle/Entity/User.php
- namespace Acme\HelloBundle\Entity;
- use Doctrine\ORM\Mapping as ORM;
- /**
- * @ORM\Entity(repositoryClass="Acme\HelloBundle\Repository\UserRepository")
- */
- class User
- {
- //...
- }
如果你运行以下命令生成你的实体,那么repository类会自动创建。
- $ php app/console doctrine:generate:entities
如果你在添加repositoryClass映射之前就已经生成了你的实体,那么你就不得不自行创建这个类了。幸运地是,它非常容易,简单地在你Bundle目录下的Repository/目录创建一个类,并确保它继承Doctrine\ORM\EntityRepository类。一旦你创建了这个类,你就可以为你的实体添加任意方法了。
下列代码示范了一个repository类的示例。
- // src/Acme/HelloBundle/Repository/UserRepository.php
- namespace Acme\HelloBundle\Repository;
- use Doctrine\ORM\EntityRepository;
- class UserRepository extends EntityRepository
- {
- public function findAllOrderedByName()
- {
- return $this->getEntityManager()
- ->createQuery('SELECT u FROM Acme\HelloBundle\Entity\User u
- ORDER BY u.name ASC')
- ->getResult();
- }
- }
实体管理器在repositories函数中可能通过$this->getEntityManager()来访问。
新方法的用法和缺省查找函数一样。
- $em = $this->get('doctrine')->getEntityManager();
- $users = $em->getRepository('AcmeHelloBundle:User')
- ->findAllOrderedByName();
配置
我们在Symfony2中只是知道了让Doctrine ORM运行的必要配置选项,其它的配置选项都使用缺省值。
下面的配置示例显示了ORM的所有缺省配置:
- doctrine:
- orm:
- auto_mapping: true
- auto_generate_proxy_classes: true
- proxy_namespace: Proxies
- proxy_dir: %kernel.cache_dir%/doctrine/orm/Proxies
- default_entity_manager: default
- metadata_cache_driver: array
- query_cache_driver: array
- result_cache_driver: array
这有许多其它的配置选项,你可以用来覆写某些类,但那些仅用于非常高级的用例。你可以看看配置指南 ,以便对所有支持的选项有个了解。
你可以指定缓存驱动的值,象"array"、"apc"、"memcache"或"xcache"。
下面的例子展示了缓存配置的概况:
- doctrine:
- orm:
- auto_mapping: true
- metadata_cache_driver: apc
- query_cache_driver: xcache
- result_cache_driver:
- type: memcache
- host: localhost
- port: 11211
- instance_class: Memcache
映射配置
显式定义所有被映射的实体是ORM唯一必要的配置,你可以控制一些配置选项,下面是一些映射配置选项:
为了避免为你的映射配置大量信息,你应该遵循以下约定:
以下配置展示了多个映射的例子:
- doctrine:
- orm:
- auto_mapping: false
- mappings:
- MyBundle1: ~
- MyBundle2: yml
- MyBundle3: { type: annotation, dir: Entity/ }
- MyBundle4: { type: xml, dir: Resources/config/doctrine/mapping }
- MyBundle5:
- type: yml
- dir: my-bundle-mappings-dir
- alias: BundleAlias
- doctrine_extensions:
- type: xml
- dir: %kernel.root_dir%/../src/vendor/DoctrineExtensions/lib/DoctrineExtensions/Entity
- prefix: DoctrineExtensions\Entity\
- alias: DExt
多实体管理
你可以在Symfony2应用程序中使用多实体管理。如果你使用不同的数据库甚至供应商使用完全不同的实体集。
下列配置代码展示了如何定义两个实体管理器
- doctrine:
- orm:
- default_entity_manager: default
- cache_driver: apc # array, apc, memcache, xcache
- entity_managers:
- default:
- connection: default
- mappings:
- MyBundle1: ~
- MyBundle2: ~
- customer:
- connection: customer
- mappings:
- MyBundle3: ~
与DBAL一样,如果你已经配置了多个实体管理器实例,并且想得到指定的那个,你可以从Doctrine注册中用它的名称检索到它:
- class UserController extends Controller
- {
- public function indexAction()
- {
- $em = $this->get('doctrine')->getEntityManager();
- $customerEm = $this->get('doctrine')->getEntityManager('customer');
- }
- }
注册事件监听和订阅
Doctrine 使用轻量级的Doctrine\Common\EventManager类来跟踪你想要“钩进”的大量不同的事件。你可以通过doctrine.event_listener或doctrine.event_subscriber使用服务容器来标识各自的服务,从而注册事件监听器或订阅。
要注册事件监听器或订阅(监听器来源于此)服务,你必须要使用适当的名称来标识它们。依赖你的用户,你可以将监听器“钩进”每个DBAL连接和ORM实体管理器中,或者只是一个指定的DBAL连接和使用该连接的所有实体管理器。
- doctrine:
- dbal:
- default_connection: default
- connections:
- default:
- driver: pdo_sqlite
- memory: true
- services:
- my.listener:
- class: MyEventListener
- tags:
- - { name: doctrine.event_listener }
- my.listener2:
- class: MyEventListener2
- tags:
- - { name: doctrine.event_listener, connection: default }
- my.subscriber:
- class: MyEventSubscriber
- tags:
- - { name: doctrine.event_subscriber, connection: default }
注册自定义的DQL函数
你可以通过配置注册自定义的DQL函数。
- # app/config/config.yml
- doctrine:
- orm:
- # ...
- entity_managers:
- default:
- # ...
- dql:
- string_functions:
- test_string: Acme\HelloBundle\DQL\StringFunction
- second_string: Acme\HelloBundle\DQL\SecondStringFunction
- numeric_functions:
- test_numeric: Acme\HelloBundle\DQL\NumericFunction
- datetime_functions:
- test_datetime: Acme\HelloBundle\DQL\DatetimeFunction
控制行命令
Doctrine2 ORM 在doctrine名称空间下整合提供了一些控制行命令,为了看到你可以在控制行运行的命令列表,不要加任何参数或选项:
- $ php app/console
- ...
- doctrine
- :ensure-production-settings Verify that Doctrine is properly configured for a production environment.
- :schema-tool Processes the schema and either apply it directly on EntityManager or generate the SQL output.
- doctrine:cache
- :clear-metadata Clear all metadata cache for a entity manager.
- :clear-query Clear all query cache for a entity manager.
- :clear-result Clear result cache for a entity manager.
- doctrine:fixtures
- :load Load data fixtures to your database.
- doctrine:database
- :create Create the configured databases.
- :drop Drop the configured databases.
- doctrine:generate
- :entities Generate entity classes and method stubs from your mapping information.
- :entity Generate a new Doctrine entity inside a bundle.
- :proxies Generates proxy classes for
- entity classes.
- :repositories Generate repository classes from your mapping information.
- doctrine:mapping
- :convert Convert mapping information between supported formats.
- :convert-d1-schema Convert a Doctrine1 schema to Doctrine2 mapping files.
- :import Import mapping information from an existing database.
- doctrine:query
- :dql Executes arbitrary DQL directly from the command line.
- :sql Executes arbitrary SQL directly from the command line.
- doctrine:schema
- :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.
- ...
为了能引导数据夹到你的数据库中,你需要安装DoctrineFixturesBundle,如何安装请参见食谱条目如何在Symfony2中创建数据夹 。
表单集成
在Doctrine ORM和Symfony2 Form组件之间的集成是紧密的。因为Doctrine实体是POPO(plain old php objects),在缺省情况下可以很好地集成到Form组件中,至少原始的数据类型如字符串、整数和字段没有问题。你也可以使用associations来很好地集成它们。
使用专用类型EntityType是有帮助的,它提供了来自被选实体的选择列表:
- use Symfony\Bridge\Doctrine\Form\Type\EntityType;
- $builder->add('users','entity',
- array('class' => 'Acme\\HelloBundle\\Entity\\User',
- ));
必填的class选项需要一个实体类名作为参数,可选的property选项允许你选择用于展示的实体属性(如果没有设置则使用__toString)。可选的query_builder选项需要一个QueryBuilder实例或封装的检索repository作为参数,并返回QueryBuilder用来得到选择。如果没有设置则将使用所有实体。