PHP Doctrine ORM 持久化（一）

最新推荐文章于 2025-04-06 10:37:17 发布

绝不原创的飞龙

最新推荐文章于 2025-04-06 10:37:17 发布

阅读量1.2k

点赞数 12

分类专栏： FreeLearning 文章标签： java python go c++ javascript

License CC BY-NC-SA 4.0 / 自豪地采用谷歌翻译

本文链接：https://blog.csdn.net/wizardforcel/article/details/140544179

版权

FreeLearning 专栏收录该内容

2681 篇文章

订阅专栏

原文：zh.annas-archive.org/md5/b34bd0528134548b9e95e991c08297b5

译者：飞龙

协议：CC BY-NC-SA 4.0

前言

Doctrine 2 已成为 PHP 最流行的现代持久化系统。它与 Symfony2 框架的标准版一起分发，可以独立在任何 PHP 项目中使用，并与 Zend Framework 2，CodeIgniter 或 Laravel 集成得非常好。它高效，自动抽象出流行的数据库管理系统，支持 PHP 5.3 功能（包括命名空间），可以通过 Composer 安装，并且具有经过广泛测试的高质量代码库。

Doctrine 的 ORM 库允许轻松持久化和检索 PHP 对象图，而无需手动编写任何 SQL 查询。它还提供了一个强大的面向对象的类似 SQL 的查询语言称为 DQL，一个数据库模式生成工具，一个事件系统等等。

为了发现这个必不可少的库，我们将一起构建一个典型的小型博客引擎。

本书涵盖的内容

第一章，“开始使用 Doctrine 2”，解释了如何通过 Composer 安装 Common，DBAL 和 ORM 库，获取我们的第一个实体管理器，并在介绍了我们在整本书中构建的项目之后配置命令行工具（Doctrine 的架构和开发环境的配置）。

第二章，“实体和映射信息”，介绍了 Doctrine 实体的概念。我们将创建第一个实体，使用注释将其映射到数据库，生成数据库模式，创建数据夹具，并最终奠定博客用户界面的基础。

第三章，“关联”，解释了如何处理 PHP 对象和 ORM 之间的关联。我们将创建新实体，详细说明一对一，一对多和多对多的关联，生成底层数据库模式，创建数据夹具，并在用户界面中使用关联。

第四章，“构建查询”，创建实体存储库，并帮助理解如何使用查询构建器生成 DQL 查询和检索实体。我们还将看一下聚合函数。

第五章，“更进一步”，将介绍 Doctrine 的高级功能。我们将看到 Doctrine 管理对象继承的不同方式，玩转实体生命周期事件，并创建本机 SQL 查询。

本书所需的内容

要执行本书的示例，您只需要 PHP 5.4+文本编辑器或 PHP IDE 以及您喜欢的浏览器。

本书适合的读者

读者应该对面向对象编程，PHP（包括 PHP 5.3 和 5.4 中引入的功能）和一般数据库概念有很好的了解。

约定

在本书中，您会发现一些文本样式，用于区分不同类型的信息。以下是一些这些样式的示例，以及它们的含义解释。

文本中的代码词，数据库表名，文件夹名，文件名，文件扩展名，路径名，虚拟 URL 和用户输入显示如下：“NativeQuery类允许您执行本机 SQL 查询并将其结果作为 Doctrine 实体获取。”

代码块设置如下：

    /**
     * Adds comment
     *
     * @param  Comment $comment
     * @return Post
     */
    public function addComment(Comment $comment)
    {
        $this->comments[] = $comment;
        $comment->setPost($this);

        return $this;
    }

当我们希望引起您对代码块的特定部分的注意时，相关行或项目将以粗体显示：

    /**
     * Adds comment
     *
     * @param  Comment $comment
     * @return Post
     */
    public function addComment(Comment $comment)
    {
        $this->comments[] = $comment;
 **$comment->setPost($this);**

        return $this;
    }

任何命令行输入或输出都以以下方式编写：

**# php bin/load-fixtures.php**

新术语和重要单词以粗体显示。例如，屏幕上显示的单词，例如菜单或对话框中的单词，会以这样的方式出现在文本中：“以下文本必须在终端中打印：注意：此操作不应在生产环境中执行。”

注意

警告或重要说明会出现在这样的框中。

提示

提示和技巧会以这样的方式出现。

第一章：开始使用 Doctrine 2

Doctrine 项目是一组库，提供了在 PHP 应用程序中轻松实现数据持久性的实用程序。它使得可以在很短的时间内创建与流行的 DBMS 兼容的复杂模型层，包括 SQLite、MySQL 和 PostgreSQL。为了发现和理解 Doctrine，我们将在本书中从头开始创建一个小型博客，主要使用以下 Doctrine 组件：

Common提供了 PHP 标准库中没有的实用程序，包括类自动加载器、注解解析器、集合结构和缓存系统。
数据库抽象层（DBAL）公开了一个独特的接口，用于访问流行的 DBMS。其 API 类似于 PDO（在可能的情况下使用 PDO）。DBAL 组件还能够通过内部重写查询来使用特定构造和模拟缺失功能，在不同的 DBMS 上执行相同的 SQL 查询。
对象关系映射器（ORM）允许通过面向对象的 API 访问和管理关系数据库表和行。借助它，我们将直接操作 PHP 对象，并且它将透明地生成 SQL 查询来填充、持久化、更新和删除它们。它是建立在 DBAL 之上的，并且将是本书的主要主题。

注意

有关 PHP 数据对象和 PHP 提供的数据访问抽象层的更多信息，请参考以下链接：php.net/manual/en/book.pdo.php

为了学习 Doctrine，我们将一起构建一个具有以下高级功能的微型博客引擎：

帖子列表、创建、编辑和删除
评论
标签过滤
帖子和评论作者的配置文件
统计
数据夹具

以下是博客的屏幕截图：

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

在本章中，我们将学习以下主题：

理解 Doctrine 背后的概念
创建项目的结构
安装 Composer
通过 Compose 安装 Doctrine ORM、DBAL 和 Common
引导应用程序
使用 Doctrine 的实体管理器
配置 Doctrine 命令行工具

先决条件

为了跟随本教程，我们需要正确安装 PHP 5.4 或更高版本的 CLI。我们还将使用curl命令来下载 Composer 存档和 SQLite 3 客户端。

注意

有关 PHP CLI、curl 和 SQLite 的更多信息，请参考以下链接：[www.php.net/manual/en/features.commandline.php, http://curl.haxx.se](http://www.php.net/manual/en/features.commandline.php, http://curl.haxx.se)和www.sqlite.org

在示例中，我们将使用 PHP 内置的 Web 服务器和 SQLite 作为 DBMS。Doctrine 是一个纯 PHP 库。它与支持 PHP 的任何 Web 服务器兼容，但不限于 Apache 和 Nginx。当然，它也可以用于不打算在 Web 服务器上运行的应用程序，例如命令行工具。在数据库方面，官方支持 SQLite、MySQL、PostgreSQL、Oracle 和 Microsoft SQL Server。

由于 DBAL 组件，我们的博客应该可以在所有这些 DBMS 上正常工作。它已经在 SQLite 和 MySQL 上进行了测试。

Doctrine 项目还为 NoSQL 数据库（包括 MongoDB、CouchDB、PHPCR 和 OrientDB）提供了对象文档映射器（ODM）。这些主题不在本书中涵盖。

注意

在阅读本书时，请随时查阅以下链接中指定的 Doctrine 文档：www.doctrine-project.org

理解 Doctrine 背后的概念

Doctrine ORM 实现了数据映射器和工作单元设计模式。

数据映射器是一个设计用来同步数据库中存储的数据与其领域层相关对象的层。换句话说，它执行以下操作：

从对象属性中插入和更新数据库中的行
当相关实体标记为删除时，删除数据库中的行
使用从数据库检索的数据来水合内存中的对象

注意

有关数据映射器和工作单元设计模式的更多信息，您可以参考以下链接：martinfowler.com/eaaCatalog/dataMapper.html和martinfowler.com/eaaCatalog/unitOfWork.html

在 Doctrine 术语中，数据映射器称为实体管理器。实体是领域层的普通旧 PHP 对象。

由于实体管理器，它们不必知道它们将存储在数据库中。实际上，他们不需要知道实体管理器本身的存在。这种设计模式允许重用实体类，而不受持久性系统的影响。

出于性能和数据一致性的考虑，实体管理器不会在每次修改实体时将实体与数据库同步。工作单元设计模式用于保持数据映射器管理的对象的状态。只有在通过调用实体管理器的flush()方法请求时，数据库同步才会发生，并且在事务中进行（如果在将实体同步到数据库时出现问题，则数据库将回滚到同步尝试之前的状态）。

想象一个具有公共$name属性的实体。想象执行以下代码：

  $myEntity->name = 'My name';
  $myEntity->name = 'Kévin';
  $entityManager->flush($myEntity);

由于工作单元设计模式的实现，Doctrine 只会发出类似以下的一个 SQL 查询：

 **UPDATE MyEntity SET name='Kévin' WHERE id=1312;**

注意

出于性能原因，Doctrine 使用预处理语句，因此查询是相似的。

我们将以简要概述实体管理器方法及其相关实体状态来完成理论部分。

以下是表示实体及其实体管理器的类图的摘录：

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

find()方法水合并返回第一个参数中传递的类型的实体，其第二个参数作为标识符。数据通过SELECT查询从数据库中检索。返回实体的状态为受控。这意味着在调用flush()方法时，对其进行的更改将同步到数据库。find()方法是一个方便的方法，它在内部使用实体存储库从数据库中检索数据并水合实体。受控实体的状态可以通过调用detach()方法更改为分离。对分离实体所做的修改将不会同步到数据库（即使调用flush()方法时也是如此），直到通过调用merge()方法将其状态设置回受控为止。

注意

第三章关联的开始将专门用于实体存储库。

persist()方法告诉 Doctrine 将传递的实体状态设置为受控。这仅对尚未至少一次同步到数据库的实体有用（新创建对象的默认状态为new），因为从现有数据中水合的实体自动具有受控状态。
remove()方法将传入实体的状态设置为已删除。与此实体相关的数据将在下次调用flush()方法时通过DELETE SQL 查询有效地从数据库中删除。
flush()方法将实体的数据与受控和已删除状态同步到数据库。Doctrine 将为同步发出INSERT，UPDATE和DELETE SQL 查询。在调用该方法之前，所有更改都仅在内存中，并且从未同步到数据库。

注意

Doctrine 的实体管理器有很多其他有用的方法，这些方法在 Doctrine 网站上有文档，www.doctrine-project.org/api/orm/2.4/class-Doctrine.ORM.EntityManager.html。

目前这是抽象的，但是我们将通过本书中的许多示例更好地理解实体管理器的工作原理。

创建项目结构

以下是我们应用程序的文件夹结构：

blog/：之前创建的应用根目录
bin/：我们博客应用程序的特定命令行工具
config/：我们应用程序的配置文件
data/：SQLite 数据库将存储在这里
src/：我们编写的所有 PHP 类将在这里
vendor/：这是Composer（见下一节）存储所有已下载依赖项的地方，包括 Doctrine 的源代码
bin/：这是由 Composer 安装的依赖项提供的命令行工具
web/：这是包含 PHP 页面和资产（如图像、CSS 和 JavaScript 文件）的公共目录

我们必须创建所有这些目录，除了vendor/，它将在以后自动生成。

安装 Composer

与大多数现代 PHP 库一样，Doctrine 可以通过 Composer 获得，这是一个强大的依赖管理器。还有一个 PEAR 频道可用。

注意

有关 Composer 和 Pear 软件包的更多信息，请参考以下链接：getcomposer.org 和 pear.doctrine-project.org

安装 Composer 应执行以下步骤：

安装 Doctrine ORM 的第一步是获取最新版本的 Composer。
打开您喜欢的终端，转到blog/目录（我们项目的根目录），并输入以下命令来安装 Composer：

 **curl -sS https://getcomposer.org/installer | php**

一个名为composer.phar的新文件已经在目录中下载。这是 Composer 的一个自包含存档。

现在输入以下命令：

 **php composer.phar**

如果一切正常，将列出所有可用的命令。您的 Composer 安装已经准备就绪！

安装 Doctrine

安装 Doctrine 应执行以下步骤：

要安装 Doctrine，我们需要在新的blog目录中创建一个名为composer.json的文件。它列出了我们项目的依赖项，如下面的代码所示：

{
    "name": "myname/blog",
    "type": "project",
    "description": "My small blog to play with Doctrine",

    "require": {
 **"doctrine/orm": "2.4.*"**
    },

    "autoload": {
 **"psr-0": { "": "src/" }**
    }
}

Composer 将解析这个标准的 JSON 文件，以下载和安装所有指定的依赖项。一旦安装完成，Composer 将自动加载这些库的所有类。

name、type和description属性是可选的，但最好总是填写它们。它们提供了关于我们正在开发的项目的一般信息。

这个composer.json文件更有趣的部分是require字段。为了让 Composer 安装它，我们应用程序使用的所有库都必须在这里列出。许多 PHP 库都可以在Packagist上找到，这是默认的 Composer 包存储库。当然，Doctrine 项目也是如此。

注意

有关 Packagist 的更多信息，请访问以下链接：packagist.org/

我们指定需要 Doctrine ORM 2.4 分支的最新次要版本。您可以在这里设置主要或次要版本，甚至更复杂的东西。

注意

有关软件包版本的更多信息，请参考以下链接：getcomposer.org/doc/01-basic-usage.md#package-versions

autoload字段在这里告诉 Composer 自动加载我们应用程序的类。我们将把我们的特定代码放在一个名为src/的目录中。我们的文件和类将遵循PSR-0命名空间和文件命名标准。

注意

PHP 规范请求是为了改进 PHP 应用程序和库的互操作性而尝试的。它们可以在www.php-fig.org/找到。

现在是使用 Composer 来安装 ORM 的时候了。运行以下命令：

 **php composer.phar install**

vendor/目录中出现了新文件。Doctrine ORM 已经安装，Composer 足够智能，可以获取所有它的依赖，包括 Doctrine DBAL 和 Doctrine Common。

还创建了一个composer.lock文件。它包含已安装库的确切版本。这对于部署应用程序很有用。有了这个文件，运行install命令时，Composer 将能够检索与开发中使用的相同版本。

Doctrine 现在已经正确安装。很容易，不是吗？

要在 2.4 分支中有新版本发布时更新库，我们只需要输入以下命令：

 **php composer.phar update**

引导应用程序

需要执行以下步骤来引导应用程序：

创建一个名为config/config.php的新文件，其中包含我们应用程序的配置参数，如下所示：

  <?php

  // App configuration
  $dbParams = [
    'driver' => 'pdo_sqlite',
    'path' => __DIR__.'/../data/blog.db'
  ];

  // Dev mode?
  $dev = true;

Doctrine 的配置参数存储在$dbParams数组中。我们将使用一个名为blog.db的 SQLite 数据库，存储在data/目录中。如果你想使用 MySQL 或任何其他 DBMS，你将在这里配置要使用的驱动程序、数据库名称和访问凭据。

注意

以下是使用 MySQL 而不是 SQLite 的示例配置：

$dbParams = [
    'driver' => 'pdo_mysql',
    'host' => '127.0.0.1',
    'dbname' => 'blog',
    'user' => 'root',
    'password' => ''
];

配置键是不言自明的。

如果$dev变量为true，一些优化将被禁用以便于调试。禁用dev模式允许 Doctrine 将大量数据（如元数据）放入强大的缓存中，以提高应用程序的整体性能。

注意

它需要缓存驱动程序的安装和额外的配置，可在docs.doctrine-project.org/en/latest/reference/caching.html找到。

接下来，我们需要一种方法来引导我们的应用程序。在src/目录中创建一个名为bootstrap.php的文件。这个文件将加载我们需要的一切，如下面的代码所示：

  <?php

  require_once __DIR__.'/../vendor/autoload.php';
  require_once __DIR__.'/../config/config.php';

第一行需要 Composer 自动加载程序。它允许您自动加载 Doctrine 的类、项目的类（将在src/目录中），以及使用 Composer 安装的任何库的类。

第二行导入了应用程序的配置文件。项目结构已创建，应用程序的初始化过程已完成。我们准备开始使用 Doctrine。

使用 Doctrine 的实体管理器

ORM 的原则是通过面向对象的 API 管理存储在关系数据库中的数据。我们在本章的前面已经了解了它的基本概念。

每个实体类都映射到相关的数据库表。实体类的属性映射到表的列。

因此，数据库表的行在 PHP 应用程序中由一组实体表示。

Doctrine ORM 能够从数据库中检索数据并用它们填充实体。这个过程称为水合。

注意

Doctrine 可以以不同的方式填充 PHP 数组（使用对象图、使用矩形结果集等）。还可以通过参考以下链接创建自定义水合器：docs.doctrine-project.org/en/latest/reference/dql-doctrine-query-language.html#hydration-modes

正如我们在数据映射器设计模式中学到的，它也做了相反的工作：将实体持有的数据持久化到数据库中。

我们以后会大量使用实体。

Doctrine 附带以下文件来将实体映射到表：

注释块中的注解直接嵌入实体
XML 配置文件
YAML 配置文件
纯 PHP 文件

注释在 PHP 世界中是相当新的（它们在 Java 中很受欢迎），但它们已经被 Doctrine 和 Symfony 社区广泛使用。这种方法的优势在于代码旁边的映射信息，使得代码易读且易于维护。但是，在某些情况下，直接将映射信息放入代码中也可能是一个缺点，特别是对于使用多个持久性系统的大型项目。

在本书中，我们将使用注释方法，但 Doctrine 文档中还描述了其他方法。我们将在第二章中返回它们，实体和映射信息。

在下一章，第二章中，实体和映射信息，我们将发现 Doctrine 足够智能，可以使用映射信息自动创建相关的数据库模式。

现在，我们将专注于检索实体管理器。因为实体是通过它检索、持久化、更新和删除的，这是 Doctrine ORM 的入口点。

编辑src/bootstrap.php文件以检索 Doctrine 的实体管理器。在文件末尾添加以下代码：

  $entitiesPath = array(__DIR__.'/Blog/Entity');
  $config = **Setup::createAnnotationMetadataConfiguration**    **($entitiesPath, $dev);**
  $entityManager = **EntityManager::create**($dbParams, $config);

提示

下载示例代码

您可以从您在www.packtpub.com购买的所有 Packt 图书的帐户中下载示例代码文件。如果您在其他地方购买了本书，您可以访问www.packtpub.com/support注册并直接通过电子邮件接收文件。

$entitiesPath属性包含存储实体类的目录路径列表。我们已经提到我们的应用程序将遵循PSR-0命名空间约定。\Blog文件夹将是根命名空间，实体类将在\Blog\Entity文件夹中。

创建了一个 Doctrine 配置，用于使用注释进行映射信息，并能够定位我们将创建的博客实体。

创建并配置了一个新的EntityManager，以使用我们的数据库和 Doctrine 设置。

为简单起见，我们创建了一个在整个应用程序中将被使用的唯一实体管理器。对于真实世界的应用程序，您应该查看依赖注入设计模式。

注意

在以下链接找到有关依赖注入模式的更多信息：en.wikipedia.org/wiki/Dependency_injection

配置 Doctrine 命令行工具

Doctrine 库捆绑了一些有用的命令行工具。它们提供了许多有用的功能，包括但不限于根据实体映射创建数据库模式的能力。

Composer 已经在vendor/bin/目录中安装了 Doctrine 的命令行工具。但是，在能够使用它们之前，必须进行一些配置。命令行工具内部使用实体管理器。我们需要告诉它们如何检索它。

在这里，我们只需要在config/目录中创建一个名为cli-config.php的文件，如下所示：

  <?php

// Doctrine CLI configuration file

use Doctrine\ORM\Tools\Console\ConsoleRunner;

require_once __DIR__.'/../src/bootstrap.php';

return ConsoleRunner::createHelperSet($entityManager);

由于 Doctrine 的约定，该文件将被自动检测并被 Doctrine CLI 使用。

注意

命令行工具将在当前目录和config/目录中查找名为cli-config.php的文件。

该文件只是使用我们之前创建的实用类获取一个新的实体管理器，并配置 Doctrine CLI 以使用它。

键入以下命令以获取可用的 Doctrine 命令列表：

 **php vendor/bin/doctrine.php**

总结

在本章中，我们了解了 Doctrine 的基础知识。我们现在知道了实体和实体管理器是什么，我们已经使用 Composer 依赖管理器安装了 Doctrine，创建了博客应用程序的框架，并成功运行了命令行工具。

在下一章中，我们将创建我们的第一个实体类，发现许多注解来将其映射到数据库，生成数据库架构，并开始处理实体。到下一章结束时，我们博客的发布系统将会运作！

第二章：实体和映射信息

在上一章中，我们了解了 Doctrine 背后的概念，学习了如何使用 Composer 进行安装，设置了 Doctrine 命令行工具，并深入了解了实体管理器。

在本章中，我们将涵盖以下主题：

创建我们的第一个实体类
使用注释将其映射到相关的数据库表和列
使用 Doctrine 提供的命令助手自动生成数据库模式
创建一些固定数据，并处理实体管理器以在 Web 用户界面中显示我们的数据

因为我们正在构建一个博客，我们的主要实体类将被称为Post，如下图所示：

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

我们的Post实体类具有以下四个属性：

id：跨数据库表（和博客）的帖子的唯一标识符
title：帖子的标题
body：帖子的正文
publicationDate：帖子的发布日期

创建实体类

如第一章开始使用 Doctrine 2中所述，Doctrine 实体只是将保存在数据库中的 PHP 对象。Doctrine 注释添加在实体类属性的 PHP DocBlock注释中。Doctrine 使用注释将对象映射到相关的数据库表和属性到列。

注意

DocBlocks的最初目的是将技术文档直接集成到源代码中。解析 DocBlocks 的最流行的文档生成器是phpDocumentator，可以在此网站上找到：www.phpdoc.org。

每个实体一旦通过 Doctrine 持久化，将与数据库表的一行相关联。

在src/Blog/Entity/位置创建一个名为Post.php的新文件，其中包含以下代码的实体类：

  <?php

  namespace Blog\Entity;

  use Doctrine\ORM\Mapping\Entity;
  use Doctrine\ORM\Mapping\Table;
  use Doctrine\ORM\Mapping\Index;
  use Doctrine\ORM\Mapping\Id;
  use Doctrine\ORM\Mapping\GeneratedValue;
  use Doctrine\ORM\Mapping\Column;

  /**
   * Blog Post entity
   *
   * **@Entity**
   * **@Table(indexes={**
   * **@Index(name="publication_date_idx",**    **columns="publicationDate")**
   * })
   */
  class Post
  {
    /**
     * @var int
     *
     * **@Id**
     * **@GeneratedValue**
     * **@Column(type="integer")**
     */
    protected $id;
    /**
     * @var string
     *
     * **@Column(type="string")**
     */
    protected $title;
    /**
     * @var string
     *
     * **@Column(type="text")**
     */
    protected $body;
    /**
     * @var \DateTime
     *
     * **@Column(type="datetime")**
     */
    protected $publicationDate;
  }

生成 getter 和 setter

我们在第一章开始使用 Doctrine 2中配置的 Doctrine 命令行工具包括一个有用的命令，用于为我们生成实体类的 getter 和 setter 方法。我们将使用它来避免编写Post类的 getter 和 setter 方法。

运行以下命令，生成应用程序所有实体类的 getter 和 setter：

 **php vendor/bin/doctrine.php orm:generate:entities src/**

注意

如果您有多个实体，不想为所有实体生成 getter 和 setter，请使用orm:generate:entities命令的filter选项。

使用 Doctrine 注释进行映射

Post是一个简单的类，有四个属性。$id的 setter 实际上并没有被生成。Doctrine 在实体解析阶段直接填充$id实例变量。我们稍后会看到如何将 ID 生成委托给 DBMS。

Doctrine 注释从\Doctrine\ORM\Mapping命名空间导入，使用use语句。它们用于在 DocBlocks 中为类及其属性添加映射信息。DocBlocks 只是以/**开头的一种特殊的注释。

了解`@Entity`注释

@Entity注释用于类级别的 DocBlock 中，指定此类是实体类。

此注释的最重要属性是repositoryClass。它允许指定自定义实体存储库类。我们将在第四章构建查询中学习有关实体存储库的知识，包括如何制作自定义存储库。

理解`@Table`、`@Index`和`@UniqueConstraint`注释

@Table注释是可选的。它可用于向与实体类相关的表添加一些映射信息。

相关的数据库表名默认为实体类名。在这里，它是Post。可以使用注释的name属性进行更改。让 Doctrine 自动生成表和列名称是一个好习惯，但更改它们以匹配现有模式可能会很有用。

正如您所看到的，我们使用@Table注释在底层表上创建索引。为此，我们使用一个名为indexes的属性，其中包含索引列表。每个索引由@Index注释定义。每个@Index必须包含以下两个属性：

name：索引的名称
columns：索引列的列表

对于Post实体类，我们在publicationDate列上创建一个名为publication_date_idx的索引。

@Table注释的最后一个可选属性是uniqueConstraints（此处未使用）。它允许在列和列组上创建 SQL 级别的唯一约束。其语法类似于@Index：name来命名约束和columns来指定应用约束的列。

此属性仅由模式生成器使用。即使使用了uniqueConstraints属性，Doctrine 也不会自动检查值在整个表中是否唯一。底层的 DBMS 将会执行此操作，但可能会导致 DBMS 级别的 SQL 错误。如果我们想要强制数据的唯一性，我们应该在保存新数据之前执行检查。

深入了解@Column 注释

每个属性都通过@Column注释映射到数据库列。

映射的数据库列的名称默认为属性名称，但可以使用name参数进行更改。与表名一样，最好让 Doctrine 自动生成名称。

注意

与表名的情况一样，列名将默认为实体类属性名（如果正确遵循 PSR 样式，则为驼峰命名法）。

Doctrine 还提供了下划线命名策略（例如，与名为MyEntity的类相关的数据库表将是my_entity），并且可以编写自定义策略。

在 Doctrine 文档中了解更多信息：docs.doctrine-project.org/en/latest/reference/namingstrategy.html

如果属性没有标记为@Column注释，Doctrine 将忽略它。

其type属性指示列的 Doctrine 映射类型（请参阅下一节）。这是此注释的唯一必需属性。

此注释支持一些更多的属性。与其他注释一样，支持的属性的完整列表可在 Doctrine 文档中找到。最重要的属性如下：

unique：如果为true，则此列的值必须在相关数据库表中是唯一的
nullable：如果为false，则值可以是NULL。默认情况下，列不能是NULL。
length：string类型的列的长度
scale：decimal类型的列的比例
precision：decimal类型的列的精度

与@Table一样，Doctrine 不使用@Column注释的属性来验证数据。这些属性仅用于映射和生成数据库模式。没有其他用途。出于安全和用户体验的原因，您必须验证用户提供的每一条数据。本书不涵盖此主题。如果您不想手动处理数据验证，请尝试来自symfony.com/components/Validator的 Symfony 验证器组件。

注意

也可以使用生命周期事件（参见第五章，“进一步”）来处理数据验证：docs.doctrine-project.org/projects/doctrine-orm/en/latest/cookbook/validation-of-entities.html

了解@Id 和@GeneratedValue 注释

$id属性有点特殊。这是一个映射到整数的列，但这主要是我们对象的唯一标识符。

通过@Id注释，此列将被用作表的主键。

默认情况下，开发人员负责确保此属性的值在整个表中是唯一的。几乎所有的 DBMS 都提供了在插入新行时自动递增标识符的机制。@GeneratedValue注释利用了这一点。当属性标记为@GeneratedValue时，Doctrine 将把标识符的生成委托给底层的 DBMS。

注意

其他 ID 生成策略可在docs.doctrine-project.org/en/latest/reference/basic-mapping.html#identifier-generation-strategies找到。

Doctrine 还支持复合主键。只需在复合主键的所有列上添加@Id注释。

我们将在第三章中学习另一个例子，使用唯一字符串作为标识符，关联。

使用其他注释

存在许多 Doctrine 映射注释。我们将在第三章中使用一些新的注释，关联，以创建实体之间的关系。

可在 Doctrine 文档中找到所有可用注释的完整列表，网址为docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/annotations-reference.html。

了解 Doctrine 映射类型

在@Column注释中使用的 Doctrine 映射类型既不是 SQL 类型也不是 PHP 类型，但它们都被映射到。例如，Doctrine 的text类型将被转换为实体中的string PHP 类型，并存储在具有CLOB类型的数据库列中。

以下是 Doctrine 映射类型的 PHP 类型和 SQL 类型的对应表：

Doctrine 映射类型	PHP 类型	SQL 类型
`string`	`string`	`VARCHAR`
`integer`	`integer`	`INT`
`smallint`	`integer`	`SMALLINT`
`bigint`	`string`	`BIGINT`
`boolean`	`boolean`	`BOOLEAN`
`decimal`	`double`	`DECIMAL`
`date`	`\DateTime`	`DATETIME`
`time`	`\DateTime`	`TIME`
`datetime`	`\DateTime`	`DATETIME`或`TIMESTAMP`
`text`	`string`	`CLOB`
`object`	使用`serialize()`和`unserialize()`方法的对象	`CLOB`
`array`	使用`serialize()`和`unserialize()`方法的`array`	`CLOB`
`float`	`double`	`FLOAT`（双精度）
`simple_array`	使用`implode()`和`explode()`的`array`，值不能包含逗号	`CLOB`
`json_array`	使用`json_encode()`和`json_decode()`方法的`object`	`CLOB`
`guid`	`string`	如果 DBMS 支持`GUID`或`UUID`，则为`GUID`，否则为`VARCHAR`
`blob`	`resource stream`（参见`www.php.net/manual/en/language.types.resource.php`）	`BLOB`

注意

请记住，我们可以创建自定义类型。要了解更多信息，请参阅：docs.doctrine-project.org/en/latest/cookbook/custom-mapping-types.html

创建数据库模式

Doctrine 足够智能，可以生成与实体映射信息相对应的数据库模式。

注意

在设计相关数据库模式之前，首先设计实体是一个很好的做法。

为此，我们将再次使用第一章安装的命令行工具。在项目的根目录中键入以下命令：

 **php vendor/bin/doctrine.php orm:schema-tool:create**

以下文本必须在终端中打印：

注意：此操作不应在生产环境中执行。

创建数据库模式…

数据库模式创建成功！

数据库中创建了一个名为Post的新表。您可以使用 SQLite 客户端来显示生成的表的结构：

 **sqlite3 data/blog.db ".schema Post"**

它应该返回以下查询：

  CREATE TABLE Post (id INTEGER NOT NULL, title VARCHAR(255) NOT NULL, body CLOB NOT NULL, publicationDate DATETIME NOT NULL, PRIMARY KEY(id));
  CREATE INDEX publication_date_idx ON Post (publicationDate);

以下屏幕截图是表 Post 的结构：

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

Doctrine 也能够为 MySQL 和其他支持的 DBMS 生成模式。如果我们配置我们的应用程序使用 MySQL 服务器作为 DBMS，并运行相同的命令，生成的表将类似于以下屏幕截图：

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

安装数据 fixtures

Fixtures是允许在每次安装后无需手动创建数据就可以测试应用程序的虚假数据。它们对自动化测试过程很有用，并且使新开发人员更容易开始在我们的项目上工作。

注意

任何应用程序都应该有自动化测试。我们正在构建的博客应用程序由 Behat（behat.org/）测试覆盖。它们可以在 Packt 网站提供的下载中找到。

Doctrine 有一个名为 Data Fixtures 的扩展，可以简化 fixtures 的创建。我们将安装它并使用它来创建一些虚假的博客帖子。

在项目的根目录中键入以下命令，通过 Composer 安装 Doctrine Data Fixtures：

  php composer.phar require doctrine/data-fixtures:1.0.*

使用 Doctrine Data Fixtures 的第一步是创建一个 fixture 类。在src/Blog/DataFixtures目录中创建一个名为LoadPostData.php的文件，如下面的代码所示：

  <?php

  namespace Blog\DataFixtures;

  use Blog\Entity\Post;
  use Doctrine\Common\DataFixtures\FixtureInterface;
  use Doctrine\Common\Persistence\ObjectManager;

  /**
   * Post fixtures
   */
  class LoadPostData implements **FixtureInterface**
  {
    /**
     * Number of posts to add
     */
    const NUMBER_OF_POSTS = 10;

    /**
     * {@inheritDoc}
     */
    public function **load(ObjectManager $manager)**
    {
        for ($i = 1; $i <= self::NUMBER_OF_POSTS; $i++) {
            $post = **new Post()**;
            $post
                **setTitle**(sprintf('Blog post number %d', $i))
                **setBody**(<<<EOTLorem ipsum dolor sit amet, consectetur adipiscing elit.EOT
                )
                **setPublicationDate**(**new \DateTime**(sprintf('-%d days', self::NUMBER_OF_POSTS - $i)))
            ;

            **$manager->persist($post);**
        }

        **$manager->flush();**
    }
}

这个LoadPostData类包含创建虚假数据的逻辑。它创建了十篇博客帖子，其中包括生成的标题、发布日期和正文。

LoadPostData类实现了\Doctrine\Common\DataFixtures\FixtureInterface目录中定义的load()方法。这个方法接受一个EntityManager实例的参数：

第一章的一些提醒，使用 Doctrine 2 入门：调用EntityManager::persist()将每个新实体的状态设置为已管理
在过程结束时，调用flush()方法将使 Doctrine 执行INSERT查询，有效地保存数据到数据库中

我们仍然需要为我们的 fixtures 类创建一个加载器。在项目的bin/目录中创建一个名为load-fixtures.php的文件，并使用以下代码：

  <?php

  require_once __DIR__.'/../src/bootstrap.php';

  use Doctrine\Common\DataFixtures\Loader;
  use Doctrine\Common\DataFixtures\Purger\ORMPurger;
  use Doctrine\Common\DataFixtures\Executor\ORMExecutor;

 **$loader = new Loader();**
 **$loader->loadFromDirectory(__DIR__.'/../src/Blog/DataFixtures');**

 **$purger = new ORMPurger();**
 **$executor = new ORMExecutor($entityManager, $purger);**
  $executor->execute($loader->getFixtures());

在这个实用程序中，我们初始化我们的应用程序并按照第一章中的说明获取实体管理器，使用 Doctrine 2 入门。然后，我们实例化了 Doctrine Data Fixtures 提供的 fixtures 加载器，并告诉它在哪里找到我们的 fixtures 文件。

目前我们只有LoadPostData类，但我们将在接下来的章节中创建额外的 fixtures。

ORMExecutor方法被实例化并执行。它使用ORMPurger从数据库中删除现有数据。然后它用我们的 fixtures 填充数据库。

在我们项目的根目录中运行以下命令来加载我们的 fixtures：

 **php bin/load-fixtures.php**

我们的 fixtures 已经插入到数据库中。请注意，每次运行此命令时，数据库中的所有数据都将被永久删除。

检查我们的数据库是否已经用以下命令填充：

 **sqlite3 data/blog.db "SELECT * FROM Post;"**

您应该看到十行类似于以下内容的行：

1|博客帖子编号 1|Lorem ipsum dolor sit amet，consectetur adipiscing elit。|2013-11-08 20:01:13

2|博客帖子编号 2|Lorem ipsum dolor sit amet，consectetur adipiscing elit。|2013-11-09 20:01:13

创建一个简单的 UI

我们将创建一个简单的 UI 来处理我们的帖子。这个界面将让我们创建、检索、更新和删除博客帖子。你可能已经猜到我们将使用实体管理器来做到这一点。

为了简洁并专注于 Doctrine 部分，这个 UI 将有很多缺点。它不应该在任何生产或公共服务器上使用。主要问题如下：

一点也不安全：每个人都可以访问一切，因为没有认证系统，没有数据验证，也没有 CSRF 保护
设计不良：没有关注点分离，没有使用类似 MVC 的模式，没有 REST 架构，没有面向对象的代码等等。

当然，这将是…图形上极简主义的！

跨站点请求伪造（CSRF）：en.wikipedia.org/wiki/Cross-site_request_forgery
关注点分离：en.wikipedia.org/wiki/Separation_of_concerns
模型-视图-控制器（MVC）元模式：en.wikipedia.org/wiki/Model-view-controller
表述状态转移（REST）：en.wikipedia.org/wiki/Representational_state_transfer

对于真实世界的应用程序，您应该看一下 Symfony，这是一个强大的框架，包括 Doctrine 和大量功能（已经介绍了验证组件，表单框架，模板引擎，国际化系统等）：symfony.com/

列出帖子

话虽如此，在web/index.php文件中创建列出帖子的页面，代码如下：

  <?php

  /**
   * Lists all blog posts
   */

  require_once __DIR__.'/../src/bootstrap.php';

  /** @var $posts \Blog\Entity\Post[] Retrieve the list of all blog posts */
  **$posts = $entityManager->getRepository('Blog\Entity\Post')-**    **>findAll();**
  ?>

  <!DOCTYPE html>
  <html>
  <head>
    <meta charset="utf-8">
    <title>My blog</title>
  </head>
  <body>
  <h1>My blog</h1>

 **<?php foreach ($posts as $post): ?>**
    <article>
        <h1>
            <?=htmlspecialchars(**$post->getTitle()**)?>
        </h1>
        Date of publication: <?=**$post->getPublicationDate()->format('Y-m-d H:i:s')**?>

        <p>
            <?=nl2br(htmlspecialchars(**$post->getBody()**))?>
        </p>

        <ul>
            <li>
                <a href="edit-post.php?id=<?=**$post->getId()**?>">Edit this post</a>
            </li>
            <li>
                <a href="delete-post.php?id=<?=**$post->getId()**?>">Delete this post</a>
            </li>
        </ul>
    </article>
  <?php endforeach ?>
  <?php if (empty($posts)): ?>
    <p>
        No post, for now!
    </p>
  <?php endif ?>

  <a href="edit-post.php">
    Create a new post
  </a>
  </html>

这个第一个文件是博客的主页面。它列出所有帖子，并显示链接到创建、更新或删除帖子的页面。

在应用程序初始化之后，我们使用我们在第一章中编写的代码来获取EntityManager以配置命令行工具。

我们使用这个EntityManager来检索我们的\Blog\Entity\Post实体的存储库。目前，我们使用 Doctrine 提供的默认实体存储库。我们将在第四章中了解更多关于它们的信息，构建查询。这个默认存储库提供了一个findAll()方法，用于检索从数据库中获取的所有实体的集合。

注意

Collection接口类似于常规的 PHP 数组（带有一些增强功能）。这个类是 Doctrine Common 的一部分：www.doctrine-project.org/api/common/2.4/class-Doctrine.Common.Collections.Collection.html

调用它时，Doctrine 将查询数据库以查找Post表的所有行，并使用检索到的数据填充\Blog\Entity\Post对象的集合。这个集合被分配给$posts变量。

要浏览此页面，请在项目的根目录中运行以下命令：

  php -S localhost:8000 -t web/

这将运行内置的 PHP Web 服务器。在您喜欢的 Web 浏览器中转到http://localhost:8000，您将看到我们的十个虚假帖子。

注意

如果不起作用，请确保您的 PHP 版本至少为 5.4。

创建和编辑帖子

是时候创建一个页面来添加新的博客帖子了。将其放在web/edit-post.php文件中，如下面的代码所示：

  <?php

  /**
   * Creates or edits a blog post
   */

  use Blog\Entity\Post;

  require_once __DIR__.'/../src/bootstrap.php';

  // Retrieve the blog post if an id parameter exists
  if (isset ($_GET['id'])) {
    /** @var Post $post The post to edit */
    **$post = $entityManager->find('Blog\Entity\Post', $_GET['id']);**

    if (!$post) {
        throw new \Exception('Post not found');
    }
}

  // Create or update the blog post
  if ('POST' === $_SERVER['REQUEST_METHOD']) {
    // Create a new post if a post has not been retrieved and set its date of publication
    if (!isset ($post)) {
 **$post = new Post();**
        // Manage the entity
 **$entityManager->persist($post);**

 **$post->setPublicationDate(new \DateTime());**
    }

 **$post**
 **->setTitle($_POST['title'])**
 **->setBody($_POST['body'])**
 **;**

    // Flush changes to the database
 **$entityManager->flush();**

    // Redirect to the index
    header('Location: index.php');
    exit;
}

  /** @var string Page title */
  $pageTitle = isset ($post) ? sprintf('Edit post #%d', $post->getId()) : 'Create a new post';
  ?>

  <!DOCTYPE html>
  <html>
  <head>
    <meta charset="utf-8">
    <title><?=$pageTitle?> - My blog</title>
  </head>
  <body>
  <h1>
    <?=$pageTitle?>
  </h1>

  <form method="POST">
    <label>
        Title
        <input type="text" name="title" value="<?=isset ($post) ? htmlspecialchars($post->getTitle()) : ''?>" maxlength="255" required>
    </label><br>

    <label>
        Body
        <textarea name="body" cols="20" rows="10" required><?=isset ($post) ? htmlspecialchars($post->getBody()) : ''?></textarea>
    </label><br>

    <input type="submit">
  </form>

  <a href="index.php">Back to the index</a>

这个页面有点棘手：

在 URL 中带有id参数时，它会处理具有给定 ID 的Post实体

注意

最佳实践是使用 slug 而不是标识符。它们隐藏了应用程序的内部，可以被人类记住，并且对于搜索引擎优化更好：en.wikipedia.org/wiki/Slug_(publishing)。

没有id参数时，它会实例化一个新的Post实体
当使用GET HTTP 方法调用时，它会显示一个填充有当前Post数据的表单，以进行编辑
当使用Post HTTP 方法（当表单被提交时）时，它会创建或更新Post实体，然后重定向到博客的主页

如果通过 URL 提供了 ID，则实体管理器的find()方法用于检索存储在数据库中的具有此 ID 的实体。Doctrine 查询数据库并为我们填充实体。

如果找不到具有此 ID 的Post，则将NULL值分配给$post变量，而不是\Blog\Entity\Post的实例。为了避免进一步的错误，如果是这种情况，我们会抛出一个异常。要了解更多关于 PHP 异常的信息，请参考网站php.net/manual/en/language.exceptions.php。

然后，我们使用我们的新实体作为参数调用实体管理器的persist()方法。如第一章使用 Doctrine 2 入门中所述，对persist()方法的调用将实体的状态设置为受管理状态。这仅对新实体是必要的，因为通过 Doctrine 检索的实体已经具有受管理状态。

接下来，我们设置我们新创建对象的发布日期。多亏了 Doctrine 映射系统，我们只需要将\DateTime实例传递给setPublicationDate()方法，ORM 将为我们将其转换为 DBMS 所需的格式（参考类型对应表）。

我们还使用先前生成的 getter 和 setter 的流畅接口设置了$title和$body属性。

注意

如果您不了解流畅接口，请阅读以下文章：martinfowler.com/bliki/FluentInterface.html

当调用flush()方法时，实体管理器告诉 Doctrine 将所有受管理的实体与数据库同步。在这种情况下，只有我们的Post实体是受管理的。如果它是一个新实体，将生成一个INSERT SQL 语句。如果它是一个现有实体，将向 DBMS 发送一个UPDATE语句。

默认情况下，Doctrine 在调用EntityManager::flush()方法时自动将所有操作包装在事务中。如果发生错误，数据库状态将恢复到刷新调用之前的状态（回滚）。

这通常是最好的选择，但如果您有特定的需求，可以停用此自动提交模式。可以在docs.doctrine-project.org/en/latest/reference/transactions-and-concurrency.html中找到相关信息。

删除帖子

让我们在web/delete-post.php文件中创建一个删除帖子的页面。

  <?php

  /**
   * Deletes a blog post
   */

  require_once __DIR__.'/../src/bootstrap.php';

  /** @var Post The post to delete */
 **$post = $entityManager->find('Blog\Entity\Post', $_GET['id']);**
  if (!$post) {
    throw new \Exception('Post not found');
  }

  // Delete the entity and flush
 **$entityManager->remove($post);**
 **$entityManager->flush();**

  // Redirects to the index
  header('Location: index.php');
  exit;

我们使用 URL 中的 ID 参数检索要删除的帖子。我们告诉 Doctrine 安排删除它，调用EntityManager::remove()方法。在此调用之后，实体的状态被移除。当调用flush()方法时，Doctrine 执行DELETE SQL 查询以从数据库中删除数据。

注意

请注意，在调用flush()方法并从数据库中删除后，实体仍然存在于内存中。

总结

现在我们有一个最小但可用的博客应用程序！多亏了 Doctrine，将数据持久化、检索和删除到数据库中从未如此简单。

我们已经学会了如何使用注释将实体类映射到数据库表和行，我们生成了数据库模式而不需要输入一行 SQL，我们创建了固定装置，并且我们使用实体管理器将数据与数据库同步。

在下一章中，我们将学习如何在实体之间映射和管理一对一、一对多/多对一和多对多的关联。

第三章：关联

在上一章中，我们学习了如何使用 Doctrine 注释向实体类添加映射信息。我们使用了 Doctrine 命令行工具提供的代码和数据库模式生成器，并创建了一个使用EntityManager类来创建、更新、删除和显示博客文章的极简主义博客软件。

在第三章中，我们将学习如何通过以下主题处理实体之间的关联：

开始使用 Doctrine 关联
理解注释系统中的@ManyToOne 和@OneToMany 注释
理解标签的@ManyToMany 注释

开始使用 Doctrine 关联

我们将使用注释指定 Doctrine 关联，以及其他映射信息（还支持其他方法，如 XML 和 YAML 配置文件。请参阅第二章，实体和映射信息）。Doctrine 支持以下关联类型：

一对一：一个实体与一个实体相关联
多对一：多个实体与一个实体相关联（仅适用于双向关联，始终是一对多关联的反向方）
一对多：一个实体与多个实体相关联
多对多：多个实体与多个实体相关联

关联可以是单向的或双向的。单向关联只有一个拥有方，而双向关联既有拥有方又有反向方。换句话说，它们可以解释如下：

单向关联只能以一种方式使用：相关实体可以从主实体中检索。例如，用户有关联地址。地址可以从用户中检索，但用户无法从地址中检索。
双向关联可以以两种方式使用：相关实体可以从主实体中检索，主实体可以从相关实体中检索。例如，用户有关联订单。订单可以从用户中检索，用户也可以从订单中检索。

Doctrine 只管理关联的拥有方。这意味着您始终需要设置拥有方；否则，如果您只设置关联的反向方，它将不会由EntityManager类持久化。

有一种简单的方法来识别双向关联的方向。拥有方必须具有inversedBy属性，而反向方必须具有mappedBy属性。这些属性指的是相关的实体类。

默认情况下，一对一和多对一关联在 SQL 级别上使用存储相关 ID 和外键的列进行持久化。多对多关联始终使用关联表。

Doctrine 会自动生成列和表的名称（如果适用）。可以使用@JoinColumn注释更改名称，并使用@JoinTable注释强制使用关联表。

理解注释系统中的@ManyToOne 和@OneToMany 注释

让我们从评论开始。我们博客的访问者应该能够对我们的帖子做出反应。我们必须创建一个新的Comment Doctrine 实体类型，存储读者的评论。Comment实体将与一个Post实体相关联。一个帖子可以有多条评论，一条评论与一个帖子相关联。

以下 E-R 图表示将使用映射信息生成的 MySQL 模式：

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

创建评论实体类（拥有方）

Comment实体具有以下四个属性：

id：这是评论的唯一标识符
body：这代表评论的文本
publicationDate：这是评论发布的日期
post_id：这代表与评论相关的帖子

这是Comment实体的第一个代码片段，包含有注释的属性。它必须放在Comment.php文件中，位于src/Blog/Entity/位置。

<?php

namespace Blog\Entity;

use Doctrine\ORM\Mapping\Entity;
use Doctrine\ORM\Mapping\Id;
use Doctrine\ORM\Mapping\GeneratedValue;
use Doctrine\ORM\Mapping\Column;
use Doctrine\ORM\Mapping\ManyToOne;

/**
 * Comment entity
 *
 * @Entity
 */
class Comment
{
    /**
     * @var int
     *
     * @Id
     * @GeneratedValue
     * @Column(type="integer")
     */
    protected $id;
    /**
     * @var string
     *
     * @Column(type="text")
     */
    protected $body;
    /**
     * @var \DateTime
     *
     * @Column(type="datetime")
     */
    protected $publicationDate;
    /**
     * @var Post
     *
     * @ManyToOne(targetEntity="Post", inversedBy="comments")
     */
    protected $post;
}

这个实体类类似于第二章中创建的Post实体类，实体和映射信息。我们使用@ManyToOne注释在Comment和Post实体之间创建多对一关联。使用targetEntity属性指定相关实体类是必需的。

为了能够直接从Post实体中检索评论，这个关联必须是双向的。inversedBy属性将此关联标记为双向，并指示Post实体类拥有这个关联的反向端的属性。在这里，这是Post的$comments属性。

注意

对于每个具有private或protected属性的实体类，Comment类必须公开 getter 和 setter 来访问它们。我们将在本章后面为我们应用程序的每个实体类生成 getter 和 setter。

为`Post`实体类添加反向端

现在，我们需要修改Post实体类以添加这个关联的反向端。需要执行以下步骤：

打开src/Blog/Entity/位置的Post.php文件，并从前一个代码片段中添加 use 语句：

  use Doctrine\ORM\Mapping\OneToMany;
  use Doctrine\Common\Collections\ArrayCollection;

按照以下代码片段中所示添加$comments属性：

    /**
     * @var Comment[]
     *
     * @OneToMany(targetEntity="Comment", mappedBy="post")
     */
    protected $comments;

将其初始化代码添加到构造函数中，如下一个代码片段所示：

    /**
     * Initializes collections
     */
    public function __construct()
    {
        $this->comments = new ArrayCollection();
    }

使用 Doctrine 命令行工具提供的实体生成器为我们刚刚添加到Comment和Post类的属性创建 getter 和 setter：

**php vendor/bin/doctrine.php orm:generate:entities src/**

在生成的addComment()方法中，添加以下代码片段中的突出显示行以自动设置关联的拥有端：

    public function addComment(\Blog\Entity\Comment$comments)
    {
        $this->comments[] = $comments;
        $comments->setPost($this);

        return $this;
    }

$comments属性保存与Post实体相关联的评论集合。我们使用@OneToMany注释将此属性标记为关联的反向端，之前在Comment的$post属性中定义。我们已经解释了targetEntity属性。mappedBy属性是关联的反向端的inversedBy属性的等价物。它指示相关实体类的属性拥有关联的另一端。

为了让 Doctrine 正确管理元素的集合，必须使用 Doctrine Common 组件提供的特殊类。Post实体的$comments属性在构造函数中初始化为Doctrine\Common\Collections\ArrayCollection的实例。ArrayCollection实现了Doctrine\Common\Collections\Collection接口。这将使 Doctrine 能够填充和管理集合。

Doctrine Collection类实现了Countable、IteratorAggregate和ArrayAccess接口（这些接口在 PHP 或 SPL 中预定义）。因此，Doctrine 集合可以像标准的 PHP 数组一样使用，并且可以在 foreach 循环中透明地迭代。

注意

有关预定义接口和标准 PHP 库（SPL）提供的接口的更多信息，请参阅以下 PHP 手册：

php.net/manual/en/reserved.interfaces.php和php.net/manual/en/spl.interfaces.php

Doctrine 命令行工具生成的addComment()和removeComment()方法演示了如何使用 Doctrine Collection类的方法来添加和删除项目。

注意

可用方法的完整列表在 Doctrine 网站上有文档，如下所示：

docs.doctrine-project.org/en/latest/reference/working-with-associations.html

另一个重要的事情，正如已经解释的那样，Doctrine 只管理关联的拥有方。这就是为什么我们在addComment()方法中调用Comment实体的setPost()方法。这允许从反向方面进行关联的持久化。

注意

这仅在实体的更改跟踪策略是延迟隐式时才有效（这是默认情况）。延迟隐式策略是最方便的使用方式，但可能对性能产生负面影响。

再次参考 Doctrine 文档，了解更多可以使用的不同更改跟踪策略：

docs.doctrine-project.org/en/latest/reference/change-tracking-policies.html

接下来，我们将更新我们的 UI 以添加评论功能。首先必须更新数据库模式。

更新数据库模式

与其他注释一样，Doctrine 能够自动创建在 SQL 层存储关联所需的列和外键。再次运行orm:schema-tool:update命令，与命令行工具捆绑在一起，如下所示：

**php vendor/bin/doctrine.php orm:schema-tool:update --force**

Doctrine 将自动检测对映的更改，并相应地更新 SQL 模式。可以添加--force标志来有效执行查询。

注意

orm:schema-tool:update命令不应该在生产中使用。它可能会永久删除数据（例如，当删除列时）。相反，应该使用 Doctrine Migrations 库来正确处理复杂的迁移。即使这个库还没有被认为是稳定的，它非常方便。我们可以在以下网站找到这个库：

docs.doctrine-project.org/projects/doctrine-migrations/en/latest/reference/introduction.html

为评论添加装置

至于帖子，我们将为评论创建一些装置。在src/Blog/DataFixtures/位置创建一个名为LoadCommentData.php的新文件。下一个代码片段用于此目的：

<?php

namespace Blog\DataFixtures;

use Blog\Entity\Comment;
use Doctrine\Common\DataFixtures\DependentFixtureInterface;
use Doctrine\Common\DataFixtures\Doctrine;
use Doctrine\Common\DataFixtures\FixtureInterface;
use Doctrine\Common\Persistence\ObjectManager;

/**
 * Comment fixtures
 */
class LoadCommentData implements FixtureInterface,DependentFixtureInterface
{
    /**
     * Number of comments to add by post
     */
    const NUMBER_OF_COMMENTS_BY_POST = 5;

    /**
     * {@inheritDoc}
     */
    public function load(ObjectManager $manager)
    {
        $posts = $manager->getRepository('Blog\Entity\Post')->findAll();

        foreach ($posts as $post) {
            for ($i = 1; $i <= self::NUMBER_OF_COMMENTS_BY_POST;$i++) {
                $comment = new Comment();
                $comment
                    ->setBody(<<<EOTLorem ipsum dolor sit amet, consectetur adipiscing elit.EOT
                    )
                    ->setPublicationDate(new \DateTime(sprintf('-%ddays', self::NUMBER_OF_COMMENTS_BY_POST - $i)))
                    ->setPost($post)
                ;

                $manager->persist($comment);
            }
        }

        $manager->flush();
    }

    /**
     * {@inheritDoc}
     */
    public function getDependencies()
    {
        return ['Blog\DataFixtures\LoadPostData'];
    }
}

我们使用EntityManager类来检索Post实体存储库，然后我们使用这个存储库来检索所有的帖子。我们为每个帖子添加了五条评论。这个数据装置类实现了Doctrine\Common\DataFixtures\DependentFixtureInterface接口（getDependencies()方法）。它告诉数据加载器首先加载LoadPostData，因为这个数据装置类依赖于它。

列出和创建评论

是时候更新 UI 了。在web/位置创建一个名为view-post.php的文件。这个页面显示一个帖子和它的所有评论，还有一个添加新评论的表单，并处理评论的创建。

用于检索帖子和处理评论创建的代码如下：

<?php

/**
 * View a blog post
 */

use Blog\Entity\Comment;

require_once __DIR__ . '/../src/bootstrap.php';
/** @var \Blog\Entity\Post $post The post to edit */
$post = $entityManager->find('Blog\Entity\Post', $_GET['id']);

if (!$post) {
    throw new \Exception('Post not found');
}

// Add a comment
if ('POST' === $_SERVER['REQUEST_METHOD']) {
    $comment = new Comment();
    $comment
        ->setBody($_POST['body'])
        ->setPublicationDate(new \DateTime())
        ->setPost($post)
    ;

    $entityManager->persist($comment);
    $entityManager->flush();

    header(sprintf('Location: view-post.php?id=%d', $post->getId()));
    exit;
}
?>

正如你所看到的，使用 Doctrine 管理简单的关联是很容易的。设置关系就像调用一个带有实体链接的 setter 一样简单。使用 getter 可以访问相关实体。用于显示帖子的详细信息、相关评论和发布新评论的表单的代码（将其放在同一个文件的底部）如下：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title><?=htmlspecialchars($post->getTitle())?> - My blog</title>
</head>
<body>

<article>
    <h1>
        <?=htmlspecialchars($post->getTitle())?>
    </h1>
    Date of publication: <?=$post->getPublicationDate()->format('Y-m-d H:i:s')?>
    <p>
        <?=nl2br(htmlspecialchars($post->getBody()))?>
    </p>
    <?php if (count($post->getComments())): ?>
        <h2>Comments</h2>

        <?php foreach ($post->getComments() as $comment): ?>
            <article>
                <?=$comment->getPublicationDate()->format('Y-m-dH:i:s')?>

                <p><?=htmlspecialchars($comment->getBody())?></p>

                <a href="delete-comment.php?id=<?=$comment->getId()?>">Delete this comment</a>
            </article>
        <?php endforeach ?>
    <?php endif ?>

    <form method="POST">
        <h2>Post a comment</h2>

        <label>
            Comment
            <textarea name="body"></textarea>
        </label><br>

        <input type="submit">
    </form>
</article>

<a href="index.php">Back to the index</a>

默认情况下，Doctrine 会延迟加载关联的实体。这意味着，在我们的例子中，当调用getComments()时，Doctrine 首先向 DBMS 发送一个查询来检索帖子，然后再发送另一个查询来检索关联的评论。好处是，如果不调用getComments()方法，检索关联评论的查询将永远不会执行。但是当关联评论总是被获取时，这是一个无用的开销。

注意

为了使延迟加载功能起作用，Doctrine 在内部将实体包装成代理类。代理类负责在请求时获取尚未从数据库加载的关联实体的数据。关于这方面的一些细节可以在以下网址找到：

docs.doctrine-project.org/en/latest/reference/working-with-objects.html#entity-object-graph-traversal

我们可以通过在关联注释上设置fetch属性来更改这种行为。该属性可以采用以下值：

EAGER：通常在第一个查询中使用 SQL 连接获取相关实体。
懒加载：相关实体只有在使用另一个 SQL 查询请求时才会被获取。这是默认值。
EXTRA_LAZY：这允许在不加载整个集合到内存中的情况下执行一些操作，例如计数。要了解更多信息，请参阅以下教程：

docs.doctrine-project.org/en/latest/tutorials/extra-lazy-associations.html

另一种急切加载相关实体的方法是使用 Doctrine 查询构建器来自定义生成的请求。我们将在第四章中展示查询构建器的强大功能。

通过在view-post.php页面中删除评论，我们创建了一个允许删除评论的链接。要使此功能正常工作，需要在web/位置的delete-comment.php文件中放入以下代码：

<?php

/**
 * Deletes a comment
 */

require_once __DIR__ . '/../src/bootstrap.php';
/** @var Comment $comment The comment to delete */
$comment = $entityManager->find('Blog\Entity\Comment', $_GET['id']);

if (!$comment) {
    throw new \Exception('Comment not found');
}

// Delete the entity and flush
$entityManager->remove($comment);
$entityManager->flush();

// Redirect to the blog post
header(sprintf('Location: view-post.php?id=%d', $comment->getPost()->getId()));
exit;

这个文件与第一章中在web/位置创建的delete-post.php文件非常相似，开始使用 Doctrine 2。它通过EntityManager类检索存储库，使用它检索要删除的评论，调用remove()，并使用flush()将更改持久化到 DBMS。

更新索引

更新web/位置的index.php文件，创建一个链接到新的详细帖子视图，如下所示：

        <h1>
            <?=htmlspecialchars($post->getTitle())?>
        </h1>

为了使我们的评论功能准备就绪，请使用以下代码替换前面的代码：

        <h1>
            <a href="view-post.php?id=<?=$post->getId()?>">
                <?=htmlspecialchars($post->getTitle())?>
            </a>
        </h1>

理解标签的@ManyToMany 注释

标签按主题对帖子进行分组。一个标签包含多个帖子，一个帖子有多个标签。这是一个多对多双向关联。Doctrine 在 SQL 级别上透明地管理存储多对多关系所需的关联表。将生成的 MySQL 模式显示在以下截图中：

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

创建`Tag`实体类（反向端）

Tag实体类只有两个属性：

name：这是标签的名称，它是唯一的，并且是实体的标识符
posts：这是与此标签关联的帖子集合

以下是创建Tag实体类的步骤：

在src/Blog/Entity/位置创建一个Tag.php文件，其中包含使用以下代码片段的实体类：

<?php

namespace Blog\Entity;

use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\ORM\Mapping\Entity;
use Doctrine\ORM\Mapping\Column;
use Doctrine\ORM\Mapping\Id;
use Doctrine\ORM\Mapping\ManyToMany;

/**
 * Tag entity
 *
 * @Entity
 */
class Tag
{
    /**
     * @var string
     *
     * @Id
     * @Column(type="string")
     */
    protected $name;
    /**
     * @var Post[]
     *
     * @ManyToMany(targetEntity="Post", mappedBy="tags")
     */
    protected $posts;

    /**
     * Initializes collection
     */
    public function __construct()
    {
        $this->posts = new ArrayCollection();
    }

    /**
     * String representation
     *
     * @return string
     */
    public function __toString()
    {
        return $this->getName();
    }
}

使用以下命令生成 getter 和 setter：

**php vendor/bin/doctrine.php orm:generate:entities src/**

在addPost()方法中的$this->posts[] = $posts;之后添加以下代码行以设置关联的拥有端：

$posts->addTag($this);

$name属性是Tag实体的标识符。与Post和Comment实体不同，它的值不是由 DBMS 自动生成的；它是标签的名称。这就是为什么这里不使用@GeneratedValue注释。标签的名称必须是唯一的，并且必须由应用程序设置。

@ManyToMany注释用于标记关联。targetEntity和mappedBy属性的含义与@OneToMany注释相同。@ManyToMany注释接受mappedBy属性作为反向端，inversedBy作为拥有端。这个关联的拥有端在Post实体上。与任何 Doctrine 集合一样，$posts属性在构造函数中被初始化。我们还创建一个__toString()方法，返回标签的名称，以便能够将Tag的实例转换为字符串。

注意

__toString()魔术方法允许我们将对象转换为字符串。有关更多详细信息，我们可以参考以下链接：

www.php.net/manual/en/language.oop5.magic.php#object.tostring

更新 Post 实体类（拥有方）

修改src/Blog/Entity/位置的Post.php文件，以添加关联的拥有方使用以下步骤：

添加以下use语句：

use Doctrine\ORM\Mapping\ManyToMany;
use Doctrine\ORM\Mapping\JoinTable;
use Doctrine\ORM\Mapping\JoinColumn;

使用以下代码片段添加mapped属性：

    /**
     * @var Tag[]
     *
     * @ManyToMany(targetEntity="Tag", inversedBy="posts",fetch="EAGER", cascade={"persist"}, orphanRemoval=true)
     * @JoinTable(
     *      inverseJoinColumns={@JoinColumn(name="tag_name",referencedColumnName="name")}
     * )
     */
    protected $tags;

按照以下代码片段中所示的方式在构造函数中初始化属性：

    public function __construct()
    {
        // …
        $this->tags = new ArrayCollection();
    }

要生成 getter 和 setter，可以使用以下命令：

**php vendor/bin/doctrine.php orm:generate:entities src/**

这里介绍了@ManyToMany注释的两个新属性，即cascade和orphanRemoval。

默认情况下，当设置主实体时，关联实体不会自动设置为托管状态。这必须通过对每个关联实体的EntityManager类的persist()方法进行手动调用来完成。如果cascade属性与persist一起使用，相关实体将在持久化主实体时自动持久化。

在这里，当持久化Post实体时，相关标签将一起持久化。cascade属性可以采用其他值，其中最有用的是remove。使用remove时，当删除主实体时，相关实体将被删除。

**对象关系映射器（ORM）**在内存中处理CASCADE操作。它们不等同于 SQL 的DELETE CASCADE操作，并且可能使用大量内存。应该谨慎使用以保持应用程序的性能。

可以通过@JoinColumn注释的onDelete属性添加 SQLDELETE CASCADE操作。

将orphanRemoval属性设置为true，Doctrine 将自动删除不再与主实体关联的实体。如果从Post实体的$tags集合中删除Tag实体，并且这个Post实体是唯一与Tag实体关联的实体，那么Tag实体将被永久删除。

fetch属性已在本章中进行了解释。使用EAGER值，它告诉 Doctrine 在检索帖子时自动使用JOIN查询检索相关标签。在我们的应用程序环境中，这是有用的，因为Post实体的标签在每次显示帖子时都会显示。

由于Tag的标识符没有标记@GeneratedValue注释，Doctrine 将无法猜测它。@JoinTable和@JoinColumn注释在这里用于覆盖默认行为。

我们使用@JoinColumn为关联方（反向方）设置自定义JOIN列，通过@JoinTable的inverseJoinColumns属性。@JoinColumn的referencedColumnName属性告诉 Doctrine 在 SQL 级联表中查找Tag的标识符的$name属性（默认情况下是$id）。name属性将Tag的标识符的列名称设置为tag_name（默认情况下是tag_id）。

再次更新模式

现在是时候再次更新 SQL 模式以匹配我们的更改。我们在命令行上使用以下命令：

**php vendor/bin/doctrine.php orm:schema-tool:update --force**

创建标签固定装置

在src/Blog/DataFixtures/创建一个LoadTagData.php文件，其中包含使用以下代码片段的标签固定装置：

<?php

namespace Blog\DataFixtures;

use Blog\Entity\Tag;
use Doctrine\Common\DataFixtures\DependentFixtureInterface;
use Doctrine\Common\DataFixtures\Doctrine;
use Doctrine\Common\DataFixtures\FixtureInterface;
use Doctrine\Common\Persistence\ObjectManager;

/**
 * Tag fixtures
 */
class LoadTagData implements FixtureInterface,DependentFixtureInterface
{
    /**
     * Number of comments to add by post
     */
    const NUMBER_OF_TAGS = 5;
    /**
     * {@inheritDoc}
     */
    public function load(ObjectManager $manager)
    {
        $tags = [];
        for ($i = 1; $i <= self::NUMBER_OF_TAGS; $i++) {
            $tag = new Tag();
            $tag->setName(sprintf("tag%d", $i));

            $tags[] = $tag;
        }

        $posts = $manager->getRepository('Blog\Entity\Post')->findAll();

        $tagsToAdd = 1;
        foreach ($posts as $post) {
            for ($j = 0; $j < $tagsToAdd; $j++) {
                $post->addTag($tags[$j]);
            }

            $tagsToAdd = $tagsToAdd % 5 + 1;
        }

        $manager->flush();
    }

    /**
     * {@inheritDoc}
     */
    public function getDependencies()
    {
        return ['Blog\DataFixtures\LoadPostData'];
    }
}

由于persist属性，我们可以在不手动持久化的情况下向帖子添加标签。

固定装置后，我们必须更新 UI。

管理帖子的标签

编辑web/位置的edit-post.php文件，并按以下步骤添加代码来管理标签：

在文件顶部添加以下use语句：

use Blog\Entity\Tag;

找到以下代码片段：

    $post
        ->setTitle($_POST['title'])
        ->setBody($_POST['body'])
    ;

在to extract和管理提交的标签后添加此代码：

    $newTags = [];
    foreach (explode(',', $_POST['tags']) as $tagName) {
        $trimmedTagName = trim($tagName);
        $tag = $entityManager->find('Blog\Entity\Tag',$trimmedTagName);
        if (!$tag) {
            $tag = new Tag();
            $tag->setName($trimmedTagName);
        }

        $newTags[] = $tag;
    }

    // Removes unused tags
    foreach (array_diff($post->getTags()->toArray(),$newTags) as $tag) {
        $post->removeTag($tag);
    }

    // Adds new tags
    foreach (array_diff($newTags, $post->getTags()->toArray()) as $tag) {
        $post->addTag($tag);
    }

找到以下代码片段：

    <label>
        Body
        <textarea name="body" cols="20" rows="10"required><?=isset ($post) ? htmlspecialchars($post-
        >getBody()) : ''?></textarea>
    </label><br>

在to display后添加以下表单部件以更新标签：

    <label>
        Tags
        <input type="text" name="tags" value="<?=isset($post) ? htmlspecialchars(implode(', ', $post->getTags()->toArray())) : ''?>" required>
    </label><br>

从提交的字符串中提取每个标签名称。从存储库中检索相应的Tag实体，如果找不到则创建。

由于它的toArray()方法，Post对象的tag集合被转换为标准的 PHP 数组。

标准的array_diff()函数用于识别已删除和已添加的Tag对象。array_diff()的参数必须是可以转换为字符串的对象数组。这里可以使用，因为我们的Tag类实现了__toString()魔术方法。

已删除的标签通过Post::removeTag()函数移除，新标签通过Post::addTag()添加。

感谢在Post实体类中定义的CASCADE属性，我们不需要针对每个新标签单独持久化。

在模板中，标签列表按照“tagname1，tagname2，tagname3”的模式转换为字符串。

总结

在本章中，我们学习了如何管理 Doctrine ORM 支持的所有类型的关联。我们学习了单向和双向关联以及拥有方和反向方的概念。我们还运用了我们在之前章节学到的知识，特别是EntityManager类、装置加载器和生成器。

在下一章中，我们将学习如何使用 DQL 和 Query Builder 创建复杂的查询。

由于它们，我们将创建按标签分组的帖子列表。我们还将研究聚合函数。

第四章：构建查询

在上一章中，我们为我们的博客软件添加了评论和标记支持。虽然它运行良好，但一些功能可以得到增强。

在本章中，我们将利用 Doctrine 的一些非常重要的部分：Doctrine 查询语言（DQL）、实体存储库和查询构建器。我们将在本章中涵盖以下方面：

优化评论功能
创建一个页面来通过标签过滤帖子
在主页上显示帖子的评论数量

理解 DQL

DQL 是 Doctrine 查询语言的缩写。它是一种特定领域的语言，非常类似于 SQL，但不是 SQL。DQL 不是用于查询数据库表和行，而是设计用于查询对象模型的实体和映射属性。

DQL 受 Hibernate 的查询语言 HQL 的启发和类似，Hibernate 是 Java 的流行 ORM 的查询语言。有关更多详细信息，您可以访问此网站：www.hibernate.org/。

注

在以下网站了解更多关于特定领域语言的信息：

en.wikipedia.org/wiki/Domain-specific_language

为了更好地理解其含义，让我们运行我们的第一个 DQL 查询。

Doctrine 命令行工具就像瑞士军刀一样实用。它们包括一个名为orm:run-dql的命令，用于运行 DQL 查询并显示结果。使用它来检索带有1作为标识符的帖子的title和所有评论：

php vendor/bin/doctrine.php orm:run-dql "SELECT p.title, c.bodyFROM Blog\Entity\Post p JOIN p.comments c WHERE p.id=1"

它看起来像一个 SQL 查询，但绝对不是 SQL 查询。检查FROM和JOIN子句；它们包含以下方面：

在FROM子句中使用完全限定的实体类名作为查询的根
所有与所选“帖子”实体相关联的“评论”实体都被连接在一起，这要归功于“帖子”实体类中的“评论”属性在JOIN子句中的存在

正如您所看到的，可以以面向对象的方式请求与主实体相关联的实体的数据。持有关联的属性（在拥有方或反向方）可以在JOIN子句中使用。

尽管存在一些限制（特别是在子查询领域），我们将看到如何绕过第五章中的限制，进一步，DQL 是一种强大而灵活的语言，用于检索对象图。在内部，Doctrine 解析 DQL 查询，通过**数据库抽象层（DBAL）**生成和执行它们对应的 SQL 查询，并使用结果填充数据结构。

注

到目前为止，我们只使用 Doctrine 来检索 PHP 对象。Doctrine 能够填充其他类型的数据结构，特别是数组和基本类型。还可以编写自定义水合器来填充任何数据结构。

如果您仔细观察上一次调用orm:run-dql的返回，您会发现它是一个数组，而不是一个对象图，已经被填充。

与本书中涵盖的所有主题一样，有关内置水合模式和自定义水合器的更多信息可在以下网站的 Doctrine 文档中找到：

docs.doctrine-project.org/en/latest/reference/dql-doctrine-query-language.html#hydration-modes

使用实体存储库

实体存储库是负责访问和管理实体的类。就像实体与数据库行相关联一样，实体存储库与数据库表相关联。

我们已经在前几章中使用了 Doctrine 提供的默认实体存储库来检索实体。所有的 DQL 查询都应该写在与它们检索的实体类型相关的实体存储库中。它将 ORM 隐藏在应用程序的其他组件中，并使其更容易重用、重构和优化查询。

注

Doctrine 实体存储库是表数据网关设计模式的一种实现。有关更多详细信息，请访问以下网站：

martinfowler.com/eaaCatalog/tableDataGateway.html

为每个实体提供的基本存储库提供了管理实体的有用方法，如下所示：

find($id): 返回具有$id作为标识符的实体，或null

注意

它在实体管理器的find()方法内部使用。我们在前面的章节中多次使用了这个快捷方式。

findAll(): 检索包含此存储库中所有实体的数组
findBy(['property1' => 'value', 'property2' => 1], ['property3' => 'DESC', 'property4' => 'ASC']): 检索包含第一个参数中传递的所有条件匹配的实体的数组，并按照第二个参数排序
findOneBy(['property1' => 'value', 'property2' => 1]): 类似于findBy()，但只检索第一个实体，如果没有实体与条件匹配，则返回null

注意

实体存储库还提供了快捷方法，允许单个属性过滤实体。它们遵循这种模式：findBy*()和findOneBy*()。

例如，调用findByTitle('My title')等同于调用findBy(['title' => 'My title'])。

此功能使用了神奇的__call() PHP 方法。有关更多详细信息，请访问以下网站：

php.net/manual/en/language.oop5.overloading.php#object.call

如第三章，“关联”中所述，这些快捷方法不会连接相关实体，除非我们在实体类的关联注释中添加了fetch="EAGER"属性。如果（且仅当）通过方法调用请求了相关实体（或实体集合），则会发出另一个 SQL 查询。

在我们的博客应用中，我们希望在详细的帖子视图中显示评论，但不需要从帖子列表中获取它们。通过fetch属性的急切加载不适合列表，而延迟加载会减慢详细视图的速度。

解决这个问题的方法是创建一个具有额外方法来执行我们自己的查询的自定义存储库。我们将编写一个在详细视图中整理评论的自定义方法。

创建自定义实体存储库

自定义实体存储库是扩展了 Doctrine 提供的基本实体存储库类的类。它们旨在接收运行 DQL 查询的自定义方法。

像往常一样，我们将使用映射信息告诉 Doctrine 使用自定义存储库类。这是@Entity注释的repositoryClass属性的作用。

请执行以下步骤创建自定义实体存储库：

重新打开Post.php文件，位于src/Blog/Entity/位置，并在现有的@Entity注释中添加一个repositoryClass属性，就像下面的代码行一样：

@Entity(repositoryClass="PostRepository")

Doctrine 命令行工具还提供了实体存储库生成器。输入以下命令来使用它：

**php vendor/bin/doctrine.php orm:generate:repositories src/**

打开这个新的空自定义存储库，我们刚刚在src/Blog/Entity/位置生成的PostRepository.php文件。添加以下方法来检索帖子和评论：

   /**
     * Finds a post with its comments
     *
     * @param  int  $id
     * @return Post
     */
    public function findWithComments($id)
    {
        return $this
            ->createQueryBuilder('p')
            ->addSelect('c')
            ->leftJoin('p.comments', 'c')
            ->where('p.id = :id')
            ->orderBy('c.publicationDate', 'ASC')
            ->setParameter('id', $id)
            ->getQuery()
            ->getOneOrNullResult()
        ;
    }

我们的自定义存储库扩展了 Doctrine 提供的默认实体存储库。前面章节中描述的标准方法仍然可用。

开始使用查询构建器

QueryBuilder是一个旨在通过 PHP API 和流畅的接口帮助构建 DQL 查询的对象（要了解更多关于流畅接口的信息，请参见第二章，“实体和映射信息”）。它允许我们通过getDql()方法检索生成的 DQL 查询（用于调试）或直接使用Query对象（由 Doctrine 提供）。

注意

为了提高性能，QueryBuilder缓存生成的 DQL 查询并管理内部状态。

DQL 查询的完整 API 和状态在以下网站上有文档：

docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/query-builder.html

我们将对我们在PostRepository类中创建的findWithComments()方法进行深入解释。

首先，使用从基本实体存储库继承的createQueryBuilder()方法创建一个QueryBuilder实例。QueryBuilder实例以字符串作为参数。此字符串将用作主实体类的别名。默认情况下，选择主实体类的所有字段，并且除了SELECT和FROM之外没有其他子句。

leftJoin()调用创建一个JOIN子句，用于检索与帖子相关联的评论。它的第一个参数是要加入的属性，第二个是别名；这些将在查询中用于加入的实体类（这里，字母c将用作Comment类的别名）。

注意

除非使用 SQL JOIN子句，否则 DQL 查询将自动获取与主实体相关联的实体。不需要像ON或USING这样的关键字。Doctrine 会自动知道是使用连接表还是外键列。

addSelect()调用将注释数据附加到SELECT子句。实体类的别名用于检索所有字段（这类似于 SQL 中的*运算符）。与本章的第一个 DQL 查询一样，可以使用表示法alias.propertyName检索特定字段。

你猜对了，对where()方法的调用设置了查询的WHERE部分。

在幕后，Doctrine 使用准备好的 SQL 语句。它们比标准 SQL 查询更有效。

id参数将由setParameter()调用设置的值填充。

再次感谢准备好的语句和这个setParameter()方法，自动避免了 SQL 注入攻击。

注意

SQL 注入攻击是使用未转义的用户输入执行恶意 SQL 查询的一种方法。让我们来看一个检查用户是否具有特定角色的糟糕 DQL 查询的例子：

$query = $entityManager->createQuery('SELECT ur FROMUserRole ur WHERE ur.username = "' . $username . '" ANDur.role = "' . $role . '"');
$hasRole = count($query->getResult());

这个 DQL 查询将由 Doctrine 翻译成 SQL。如果有人输入以下用户名：

" OR "a"="a

字符串中包含的 SQL 代码将被注入，查询将始终返回一些结果。攻击者现在已经获得了对私人区域的访问权限。

正确的方法应该是使用以下代码：

$query = $entityManager->createQuery("SELECT ur FROMUserRole WHERE username = :username and role = :role");
$query->setParameters([
    'username' => $username,
    'role' => $role
]);
$hasRole = count($query->getResult());

由于准备好的语句，用户名中包含的特殊字符（如引号）并不危险，这段代码将按预期工作。

orderBy()调用生成一个ORDER BY子句，按评论的发布日期对结果进行排序，先是较早的。

提示

大多数 SQL 指令在 DQL 中也有一个面向对象的等价物。最常见的连接类型可以使用 DQL 进行；它们通常具有相同的名称。

getQuery()调用告诉查询构建器生成 DQL 查询（如果需要，它将尽可能从缓存中获取查询），实例化 Doctrine Query对象，并用生成的 DQL 查询填充它。

这个生成的 DQL 查询将如下所示：

SELECT p, c FROM Blog\Entity\Post p LEFT JOIN p.comments c WHEREp.id = :id ORDER BY c.publicationDate ASC

Query对象还公开了另一个用于调试的有用方法：getSql()。顾名思义，getSql()返回与 DQL 查询对应的 SQL 查询，Doctrine 将在 DBMS 上运行。对于我们的 DQL 查询，底层 SQL 查询如下：

SELECT p0_.id AS id0, p0_.title AS title1, p0_.body AS body2,p0_.publicationDate AS publicationDate3, c1_.id AS id4, c1_.bodyAS body5, c1_.publicationDate AS publicationDate6, c1_.post_id ASpost_id7 FROM Post p0_ LEFT JOIN Comment c1_ ON p0_.id =c1_.post_id WHERE p0_.id = ? ORDER BY c1_.publicationDate ASC

getOneOrNullResult()方法执行它，检索第一个结果，并将其作为Post实体实例返回（如果找不到结果，则此方法返回null）。

注意

与QueryBuilder对象一样，Query对象管理内部状态，仅在必要时生成底层 SQL 查询。

在使用 Doctrine 时，性能是需要非常小心的。当设置为生产模式时（参见第一章，使用 Doctrine 2 入门），ORM 能够缓存生成的查询（DQL 通过QueryBuilder对象，SQL 通过Query对象）和查询的结果。

ORM 必须配置为使用以下网站显示的其中一个快速支持系统（APC，Memcache，XCache 或 Redis）：

docs.doctrine-project.org/en/latest/reference/caching.html

我们仍然需要更新视图层来处理我们的新的findWithComments()方法。

打开web/位置的view-post.php文件，在那里你会找到以下代码片段：

$post = $entityManager->getRepository('Blog\Entity\Post')->find($_GET['id']);

用以下代码片段替换前面的代码行：

$post = $entityManager->getRepository('Blog\Entity\Post')->findWithComments($_GET['id']);

按标签过滤

为了发现更高级的 QueryBuilder 和 DQL 的用法，我们将创建一个具有一个或多个标签的帖子列表。

标签过滤对于搜索引擎优化很有用，并且允许读者轻松找到他们感兴趣的内容。我们将构建一个能够列出具有多个共同标签的帖子的系统；例如，所有标记有 Doctrine 和 Symfony 的帖子。

要使用标签过滤我们的帖子，请执行以下步骤：

在我们的自定义PostRepository类（src/Blog/Entity/PostRepository.php）中添加另一个方法，使用以下代码：

    /**
     * Finds posts having tags
     *
     * @param string[] $tagNames
     * @return Post[]
     */
    public function findHavingTags(array $tagNames)
    {
        return $queryBuilder = $this
            ->createQueryBuilder('p')
                  ->addSelect('t')
            ->join('p.tags', 't')
            ->where('t.name IN (:tagNames)')
            ->groupBy('p.id')
            ->having('COUNT(t.name) >= :numberOfTags')
            ->setParameter('tagNames', $tagNames)
            ->setParameter('numberOfTags',count($tagNames))
            ->getQuery()
            ->getResult()
        ;
    }

这个方法有点复杂。它以标签名称数组的参数形式接受参数，并返回具有所有这些标签的帖子数组。

查询值得一些解释，如下所示：

主实体类（由继承的createQueryBuilder()方法自动设置）是Post，其别名是字母p。
我们通过JOIN子句连接相关标签；Tag类由t别名。
由于调用了where()，我们只检索通过参数传递的标签之一标记的帖子。我们使用 Doctrine 的一个很棒的功能，允许我们直接使用数组作为查询参数。
where()的结果通过调用groupBy()按id分组。
我们在HAVING子句中使用聚合函数COUNT()来过滤由$tagNames数组的一些标签标记的帖子，但不是所有的。

编辑web/中的index.php文件以使用我们的新方法。在这里，你会找到以下代码：

/** @var $posts \Blog\Entity\Post[] Retrieve the list ofall blog posts */
$posts = $entityManager->getRepository('Blog\Entity\Post')->findAll();

并用下一个代码片段替换前面的代码：

$repository = $entityManager->getRepository('Blog\Entity\Post');
/** @var $posts \Blog\Entity\Post[] Retrieve the list ofall blog posts */
$posts = isset($_GET['tags']) ? $repository->findHavingTags($_GET['tags']) : $repository->findAll();

现在，当 URL 中存在名为tags的GET参数时，它将用于过滤帖子。更好的是，如果传入了多个逗号分隔的标签，只会显示具有所有这些标签的帖子。

在您喜欢的浏览器中键入http://localhost:8000/index.php?tags=tag4,tag5。由于我们在上一章中创建的固定装置，应该列出帖子 5 和 10。
在同一个文件中，找到以下代码：

        <p>
            <?=nl2br(htmlspecialchars($post->getBody()))?>
        </p>

并按以下方式添加标签列表：

        <ul>
        <?php foreach ($post->getTags() as $tag): ?>
            <li>
                <a href="index.php?tags=<?=urlencode($tag)?>"><?=htmlspecialchars($tag)?></a>
            </li>
        <?php endforeach ?>
        </ul>

显示带有指向标签页面的链接的智能标签列表。您可以复制此代码，然后将其粘贴到web/位置的view-post.php文件中；或者更好的是，不要重复自己：创建一个小的辅助函数来显示标签。

计数评论

我们仍然需要进行一些外观上的改变。评论很多的帖子吸引了很多读者。如果每篇帖子的评论数量可以直接从列表页面获得会更好。Doctrine 可以将包含对aggregate函数调用的结果的数组作为第一行，并将实体作为第二行。

添加以下方法，用于检索具有相关评论的帖子，到PostRepository类：

    /**
     * Finds posts with comment count
     *
     * @return array
     */
    public function findWithCommentCount()
    {
        return $this
            ->createQueryBuilder('p')
            ->leftJoin('p.comments', 'c')
            ->addSelect('COUNT(c.id)')
            ->groupBy('p.id')
            ->getQuery()
            ->getResult()
        ;
    }

由于GROUP BY子句和调用addSelect()，此方法将返回一个二维数组，而不是Post实体的数组。返回的数组中包含两个值，如下所示：

我们的Post实体在第一个索引处
DQL 的COUNT()函数的结果（评论数量）在第二个索引处

在web/位置的index.php文件中，找到以下代码：

    $posts = $repository->findHavingTags(explode(',',$_GET['tags']));
} else {
    $posts = $repository->findAll();
}

并用以下代码替换前面的代码以使用我们的新方法：

    $results = $repository->findHavingTags(explode(',',$_GET['tags']));
} else {
    $results = $repository->findWithCommentCount();
}

为了匹配findWithCommentCount()返回的新结构，找到以下代码：

<?php foreach ($posts as $post): ?>

并用下一个代码片段替换前面的代码：

<?php
    foreach ($results as $result):
        $post = $result[0];
        $commentCount = $result[1];
?>

注意

如前所述，在处理这种情况时使用自定义水合器是一个更好的做法。

您还应该查看以下网站上显示的自定义 AST Walker：

docs.doctrine-project.org/en/latest/cookbook/dql-custom-walkers.html

找到以下代码片段：

<?php if (empty($posts)): ?>

并用下一个代码片段替换前面的代码：

<?php if (empty($results)): ?>

是时候显示评论数量了。在标签列表后插入以下代码：

        <?php if ($commentCount == 0): ?>
            Be the first to comment this post.
        <?php elseif ($commentCount == 1): ?>
            One comment
        <?php else: ?>
            <?= $commentCount ?> comments
        <?php endif ?>

由于web/位置的index.php文件还使用findHavingTags()方法来显示标记文章的列表，我们也需要更新这个方法。使用以下代码完成：

            // …
            ->addSelect('t')
            ->addSelect('COUNT(c.id)')
            ->leftJoin('p.comments', 'c')
            // …

总结

在本章中，我们学习了 DQL，它与 SQL 的区别，以及它的查询构建器。我们还学习了实体存储库的概念以及如何创建自定义存储库。

即使从这些主题和 Doctrine 中还有很多东西可以学习，我们的知识应该足够开始使用 Doctrine 作为持久系统开发完整和复杂的应用程序。

在第五章，“进一步”，这本书的最后一章，我们将进一步讨论一些更高级的主题，包括如何处理继承，如何进行本地 SQL 查询以及事件系统的基础知识。

PHP Doctrine ORM 持久化（一）

前言

本书涵盖的内容

本书所需的内容

本书适合的读者

约定

注意

提示

第一章：开始使用 Doctrine 2

注意

先决条件

注意

注意

理解 Doctrine 背后的概念

注意

注意

注意

注意

创建项目结构

安装 Composer

注意

安装 Doctrine

注意

注意

注意

引导应用程序

注意

注意

使用 Doctrine 的实体管理器

注意

提示

注意

配置 Doctrine 命令行工具

注意

总结

第二章：实体和映射信息

创建实体类

注意

生成 getter 和 setter

注意

使用 Doctrine 注释进行映射

了解@Entity注释

理解@Table、@Index和@UniqueConstraint注释

深入了解@Column 注释

注意

注意

了解@Id 和@GeneratedValue 注释

注意

使用其他注释

了解 Doctrine 映射类型

注意

创建数据库模式

注意

安装数据 fixtures

注意

创建一个简单的 UI

列出帖子

注意

注意

创建和编辑帖子

注意

注意

删除帖子

注意

总结

第三章：关联

开始使用 Doctrine 关联

理解注释系统中的@ManyToOne 和@OneToMany 注释

创建评论实体类（拥有方）

注意

为Post实体类添加反向端

注意

注意

注意

更新数据库模式

注意

为评论添加装置

列出和创建评论

注意

更新索引

了解`@Entity`注释

理解`@Table`、`@Index`和`@UniqueConstraint`注释

为`Post`实体类添加反向端

创建`Tag`实体类（反向端）