README

Boomgo仍在开发中，最初是为Retentio开发的

Boomgo是在MongoDB的PHP原生驱动程序之上构建的一个轻量级和简单的对象文档映射器。

理念

Boomgo ODM专注于PHP对象与MongoDB文档之间的映射过程，它不抽象任何原生PHP驱动程序提供的功能。这样，Boomgo允许你完全控制MongoDB交互（查询、map reduce等）。

简而言之，Boomgo提供了一种方便的方式来使用PHP对象操作MongoDB文档。

特性

Boomgo为你的PHP对象生成映射器，允许你

从MongoDB结果集填充PHP对象。
将PHP对象序列化为可存储在mongo中的数组。
处理嵌套文档/集合的填充过程。

要求

Boomgo是用爱和（包括最佳实践和标准）构建的。它仅适用于使用结构匹配的PHP 5.3+项目PSR-0。此外，强烈建议使用composer。

安装

Composer

首先，在你的composer.json中添加Boomgo的依赖项。

{
    "require": {
        "retentio/boomgo": "dev-master"
    }
}

然后获取composer并运行安装命令。

$ wget -nc -nv https://getcomposer.org.cn/composer.phar
$ php composer.phar install

使用

目前，Boomgo仅支持注解定义。但是它只使用一个标签：默认为"@Persistent"（你可以更改它）。为了持久化模型的一些属性，Boomgo需要三样东西

为你的持久化类指定一个专用且唯一的命名空间部分（默认为"Document"）。
属性文档块的"@Persistent"标签。
该属性的getter和setter。

简单持久化

<?php

namespace VendorName\Project\Document;

class MyPersistedClass
{

    /**
     * @Persistent
     */
    private $myField

    public function getMyField()
    {
        return $this->myField;
    }

    public function setMyField($value)
    {
        $this->myField = $value;
    }
}

?>

然后，你可以使用命令生成你的映射器（如果你使用了composer）

$ vendor/bin/boomgo generate:mappers path/to/your/document/folder

Boomgo将生成一个映射器类，默认位置在你的文档文件夹旁边，名为VendorName\Project\Mapper\MyPersistedClassMapper。映射器公开了3个方法

->serialize($yourObject)
->unserialize($yourArray)
->hydrate($yourObject, $yourArray)

然后，使用方式变得非常简单

<?php

// Create your connection with the native mongoDB php driver
$mongo = new \MongoClient("mongodb://127.0.0.1:27017");

// Create your object
$object = new \VendorName\Project\Document\MyPersistedClass();
$object->setMyField('my value');

// Create the mapper
$mapper = new \VendorName\Project\Mapper\MyPersistedClassMapper();

// Serialize your object to a mongoable array
$mongoableArray = $mapper->serialize($object);

// Save with the native php driver
$mongo->selectDB('my_db')
    ->selectCollection('my_collection')
    ->save($mongoableArray);

// Fetch a result with the native driver
$result = $mongo->selectDB('my_db')
    ->selectCollection('my_collection')
    ->findOne(array('myField' => 'my value'));

// Unserialize the result to an object
$object = $mapper->unserialize($result);
$object->getMyField();

// You could also hydrate an existing object from a result
$object = new \VendorName\Project\Document\MyPersistedClass();
$mapper->hydrate($object, $result);

?>

高级持久化

Boomgo处理原生PHP Mongo类型（MongoId等）、嵌入式文档和嵌套集合。由于Boomgo喜欢简单且高效的事情，因此不使用注解。相反，它依赖于...文档块中著名的未使用@var标签。

<?php

namespace VendorName\Project\Document;

class DocumentClass
{
    /**
     * @Persistent
     * @var \MongoId
     */
    private $id // expect a MongoId native instance

    /**
     * @Persistent
     * @var string
     */
    private $myField // scalar type should be specified, avoid normalization process

    /**
     * @Persistent
     * @var array
     */
    private $myArray // composite type will be normalized

    /**
     * @Persistent
     */
    private $myVar // Default type will be "mixed" and processed as a composite type

    /**
     * @Persistent
     * @var VendorName\Project\EmbeddedDocument
     */
    private $embeddedDocument // a single embedded document

    /**
     * @Persistent
     * @var array [VendorName\Project\EmbeddedDocument]
     */
    private $embeddedCollection // many embedded documents the "[ ]" chars are mandatory

    // getters & setters
}

?>

在映射器生成后，使用方式几乎相同，保持明确，Boomgo不隐藏魔法。

<?php

// Create your connection with the native mongoDB php driver
$mongo = new \MongoClient("mongodb://127.0.0.1:27017");

// Create your object
$object = new \VendorName\Project\Document\DocumentClass();
$object->setId(new \MongoId());
$object->setMyField('my value');
$object->setMyArray(array('many','values'));
$object->setMyVar('anything');
$object->setEmbeddedDocument(new \VendorName\Project\Document\EmbeddedDocument());
$object->setEmbeddedCollection(array(new \VendorName\Project\Document\EmbeddedDocument()));

// Create the mapper
$mapper = new \VendorName\Project\Mapper\DocumentClassMapper();

// Serialize your object to a mongoable array
$mongoableArray = $mapper->serialize($object);

// Save with the native php driver
$mongo->selectDB('my_db')
    ->selectCollection('my_collection')
    ->save($mongoableArray);

// Fetch a result with the native driver
$result = $mongo->selectDB('my_db')
    ->selectCollection('my_collection')
    ->findOne(array('myField' => 'my value'));

// Unserialize the result to an object
$object = $mapper->unserialize($result);

?>

要查看@var标签中支持的完整类型/伪类型列表，请查看Boomgo\Builder\Definition注意，Boomgo不会进行转换或验证，它仅在映射过程中用于规范化和嵌套文档/集合。

限制

它不会也不会管理对象关系，原因很简单：MongoDB是一种非关系型存储。
它不会也不会提供身份映射等。
它不会也不会制作咖啡。

如果您正在寻找功能齐全的php ODM，您应该看看使用活动记录/类生成器实现的Mandango，以及数据映射实现的Doctrine MongoDB ODM。

已知问题

仅支持MongoId原生类型，但添加和测试其他原生类型非常容易。
Boomgo不完全符合PSR-0规范（实际上不处理下划线类名）
Boomgo格式化器需要改进/重构

路线图

提供管理器。
添加功能测试。
更多解析器（yml，xml和json）。
ActiveRecord实现。
为映射生成器提供更多替代方案（如平面文件结构）。
文档类生成（获取器 & 设置器，php 5.4的JsonSerializable接口）。
Json文档预览。
使用实时区分动态映射。

请随时贡献！

如何运行单元测试

Boomgo使用atoum进行单元测试，该依赖项默认不提供，使用composer，您必须运行以下命令

$ php composer.phar install --dev --prefer-source

要运行完整的测试套件，打开shell并输入

$ cd path/to/Boomgo
$ php vendor/bin/atoum -c .atoum.php -d tests

在贡献时只想测试单个类？这里有一个使用AnnotationParser类的示例

$ php vendor/bin/atoum -c .atoum.php -f tests/Boomgo/Tests/Units/Parser/AnnotationParser.php

框架集成

Boomgo已经集成了以下框架

Symfony2与PlemiBoomgoBundle

鸣谢

Boomgo是在许多开源项目和一些很棒的人的帮助下构建的

Atoum：KISS单元测试框架。
Composer：出色的依赖管理器。
Symfony：组件库节省了时间。
Twig Generator：使用twig进行代码生成的酷工具。
Doctrine，Mandango：ORM/ODM的灵感。
@willdurand，提供了很多有用的建议。
@jpetitcolas，正则表达式大师。
@Palleas，永远的忍者支持者。

retentio / boomgo

维护者

详细信息