README

一个围绕 Doctrine ODM 文档映射器的智能、轻量级 Laravel 包装器。内置便捷功能，如软删除、自动创建和修改时间，以及一致且灵活的响应格式（在开发 API 时非常有用）。

此 ODM 包装器与 jensseger 的 laravel-mongodb 库兼容，如果您想同时利用 Eloquent 和 Doctrine。

注意：此包目前需要“minimum-stability”为“dev”。

请查看 chefsplate/laravel-doctrine-odm-example 仓库，以了解如何使用此包在 Mongo 上创建基于 Doctrine 的 API 的完整示例。

目录

• 要求
• 安装
• 使用 Eloquent 类似包装方法
• IDE 辅助生成 phpDocumentation
• 响应格式
• 参考

要求

• PHP 5.4+
• Laravel 5.3+（对于 Laravel 5.1 - 5.2，请使用 5.1 分支）
• PHP mongo 扩展（ext-mongo）必须安装：[https://php.ac.cn/manual/en/mongo.installation.php](https://php.ac.cn/manual/en/mongo.installation.php)
  • 在 Mac 上，最简单的方法是通过 brew 安装此扩展：先执行 brew install php56，然后执行 brew install php56-mongo

安装

使用 Composer 安装此包的最新版本

composer require chefsplate/laravel-doctrine-odm:"0.1.x"

将 Service Provider 添加到 config/app.php 中的 providers 数组

ChefsPlate\ODM\Providers\DocumentMapperServiceProvider::class,

将外观添加到您的 config/app.php 中的类别名数组

'DocumentMapper' => ChefsPlate\ODM\Facades\DocumentMapper::class,

确保您已在 config/database.php 中设置了 mongodb 驱动的连接详细信息。有关更完整的示例，请参阅 vendor/chefsplate/laravel-odm/config/database.php

'mongodb' => [
    'driver'        => 'mongodb',
    'dsn'           => 'mongodb://:27017',
    'database'      => 'mydb', // Default DB to perform queries against (not authenticate against)
    'retryConnect'  => 2, // Number of connection retry attempts before failing (doctrine feature)
    'retryQuery'    => 1, // Number of query retry attempts before failing (doctrine feature)
    'options'       => [

    ],
    'driverOptions' => [

    ]
]

DSN 的格式为：mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db

将默认的 doctrine 和 ide-odm-helper 配置文件复制到您的应用程序的配置目录：cp vendor/chefsplate/laravel-odm/config/doctrine.php config/doctrine.php cp vendor/chefsplate/laravel-odm/config/ide-odm-helper.php config/ide-odm-helper.php 修改以适应您的环境

Eloquent 类似包装方法

first 和 where

first 是构建查询的 Eloquent 类似方式。它使用箭头（关联数组）表示法指定参数

$user = User::first([
    'username' => 'davidchchang'
]);

first 包装器将自动构建查询并获取返回的第一个结果，因此如果您想检索多个文档或想使用特定的查询构建器方法，则需要使用 where 方法。

$users_named_david_chang = User::where([
    'first_name' => 'David',
    'last_name' => 'Chang'
])->getQuery()->execute();

foreach ($users_named_david_chang as $user) {
    // do something with $user here
}

使用这些包装方法有一个额外的注意事项；first 和 where 包装方法仅与非实体（如字符串、布尔值、数字和正则表达式）一起使用。如果您想使用任何（非等于）条件运算符，您需要在执行查询之前将它们链接起来（注意：first 不支持链接，因为它会立即执行查询）。

$recent_user_tasks = Task::where([
    'status' => 'Active'
])->field('created_at')->gte(new \MongoDate($date->getTimestamp()))
  ->field('user')->references($user)
  ->getQuery()->execute();

投影

first 和 where 允许您定义要返回的投影数组。例如，如果您只关心返回的模型上的用户名和电子邮件地址字段被设置，您可以在第二个参数中指定此操作

$users_named_david = User::where([
    'first_name' => new \MongoRegex('/^David/i')
], ['username', 'email']);

find

find 将返回与特定 ID 对应的实体。

$user = User::find("davidchchang");

IDE 辅助生成 phpDocumentation

如果您熟悉用于生成PHP文档（有助于自动完成）的@barryvdh的IDE辅助工具，我们构建了一个基于其命令生成器的工具。

要开始使用，请将服务提供者添加到config/app.php中的providers数组中

ChefsPlate\ODM\Providers\IdeOdmHelperServiceProvider::class,

用法

默认用法将分析App\Entities下的所有模型，并将所有注释写入_ide_helper_models.php文件。

php artisan ide-helper:doctrine-models

您也可以选择将注释直接写入PHP文件本身的PHP DocBlock类注释中。

如果注释包含重复项，可以使用--reset选项替换现有的DocBlock注释

php artisan ide-helper:doctrine-models --reset

或者，具体来说，重置单个实体

php artisan ide-helper:doctrine-models App\Entities\ModelName --reset

要了解生成辅助注释的完整用法，请使用--help

php artisan ide-helper:doctrine-models --help

响应格式

如果您使用我们的Laravel API Response Formatter（与该包非常推荐），您可以利用内置的响应格式支持，这允许您自定义哪些字段希望从API返回到前端。

您需要遵循两个简单的步骤来在代码中利用响应格式。

第一步：定义您的响应格式

首先，我们定义我们希望返回模型中的哪些字段。例如，假设您的用户具有以下字段：id、username、first_name、last_name、email和password。在将用户对象返回到前端时，我们绝对不希望返回password字段。这可以通过在User.php模型中创建一个default响应格式来实现。

protected static $response_formats = [
    'default' => ['password'],
]

响应格式是一个黑名单数组，包含您不希望出现在响应中的字段。默认情况下，所有字段都会返回。

因此，如果您不需要名字、姓氏或密码，您将指定

protected static $response_formats = [
    'default' => ['first_name', 'last_name', 'password'],
]

请注意，如果不需要的字段比需要的字段多，这将变得相当繁琐。作为替代方案，您可以使用*符号指定排除所有字段，并使用特殊的|except:语法仅包含您想要的字段。这使得响应格式更像白名单。

例如

'default'   => ['*|except:first_name,email'],

这意味着，除了first_name和email之外，排除所有内容。

为模型添加多个响应格式

您可以添加任何数量的命名格式

例如，如果我们想为只包含用户名字和电子邮件地址的电子邮件格式添加一个新的响应格式，我们可以这样做：

protected static $response_formats = [
    'default' => ['password'],
    'email'   => ['*|except:first_name,email'],
]    

嵌套响应格式

如果您的模型引用了其他模型，您可以形成复杂的响应格式，限制引用模型的返回内容。例如，如果一个Project模型包含对User模型的引用，您可以指定您想要返回的用户字段（每个模型默认返回所有字段）。

在Project.php中

protected static $response_formats = [
    'listing_view' => ['created_at', 'updated_at', 'user.*|except:id,username'],
]

此示例结合了排除和包含类型过滤器。这相当于说：不要返回created_at和updated_at属性，也不要返回任何user字段，除了user.id和user.username。

这允许实现一些非常强大的嵌套响应格式，同时保持语法简单。

第二步：告知控制器端点使用哪些响应格式

现在，在模型中已经定义了格式，您可以指定在返回负载到前端时希望使用哪些模型。

在您的控制器中

return (new ResponseObject($projects))
    ->setResponseFormatsForModels(
        [
            Project::class   => 'listing_view',
            User::class      => 'email',
        ]
    );

为了展示响应格式的强大功能，考虑以下示例

这里$projects是一个Project对象的数组，其中包含对User的引用以及一个内嵌的Comment列表。而Comment模型引用了User模型。由于这里没有定义Comment的响应格式，所以假设使用默认格式。如果Comment.php中没有定义默认响应格式，则将返回所有字段。

然而，由于我们指定了用于User的响应格式，我们的API响应格式化器将自动使用email响应格式格式化Comment中引用的User实体。正如我们上面所描述的，Project上的listing_view已经指出了它想要如何格式化其User引用，因此它不会使用email响应格式进行格式化。

ODM Helper（即将推出）

OdmHelper

convertCarbonToMongoDate会将Carbon日期转换为Mongo日期

OdmHelper::convertCarbonToMongoDate(Carbon::parse('2016-11-17'))

参考

更多信息请参阅

• 使用PHP库（PHPLIB）
• Doctrine MongoDB ODM的文档
• chefsplate/laravel-doctrine-odm-example，这是一个完全工作的示例
• PHP Annotations插件用于PhpStorm，与Doctrine兼容