README

描述

将分页资源封装成类似REST的API的资源包装器。

它旨在提供分页数据和资源集合。

它主要用于与JMSSerializerBundle一起使用，但没有对此有依赖关系，并且它应该与/没有任何其他序列化组件一起工作。

这个库基本上是一个草案，但已经经过大量测试，并且大多数情况下应该已经准备好用于生产。

安装

使用Composer，只需要求borisguery/paginated-resource包

{
  "require": {
    "borisguery/paginated-resource": "dev-master"
  }
}

如果您希望使用此库与Pagerfanta或Doctrine 2 ArrayCollection一起使用，请安装相应的依赖项

{
  "require": {
    "pagerfanta/pagerfanta": "*",
    "doctrine/common": ">2.0",
  }
}

如果您已经使用Doctrine2 ORM和/或任何Pagerfanta Bundle，则可能不需要。

用法

基本用法

namespace Acme;

use Bgy\PaginatedResource\Resource\ArrayResource;

class ArticlesController {

    public function getArticles()
    {
        $articles = array(
            array(
                'title' => 'Lorem ipsum',
                'body'  => 'Not worth reading',
            ),
            array(
                'title' => 'Dolor sid amet',
                'body'  => 'Awesome blog post',
            ),
        );

        $resource = new ArrayResource($articles, 'articles');

        echo json_encode(
            array(
                $key     => $resource->getData(),
                'paging' => $resource->getPaging(),
            )
        );
    }
}

结果将如下所示

{
    "articles": [
       {
           "title": "Lorem ipsum",
           "body" : "Not worth reading"
       },
       {
           "title": "Dolor sid amet",
           "body" : "Awesome blog post"
       }
    ],
    "paging": {
        "total_item_count":    2,
        "total_page_count":    1,
        "item_count_per_page": 2,
        "current_page":        1,
        "current_item_count":  2
    }
}

显然，这并不是非常有用，因为我们必须知道初始资源类型，并且我们需要自己序列化数据。

感谢ResourceFactory，您可以根据它们的初始类型动态创建资源。

使用`ResourceFactory`

namespace Acme;

use Bgy\PaginatedResource\ResourceFactory;

class ArticlesController {

    public function getArticles()
    {
        $articles = array(
            array(
                'title' => 'Lorem ipsum',
                'body'  => 'Not worth reading',
            ),
            array(
                'title' => 'Dolor sid amet',
                'body'  => 'Awesome blog post',
            ),
        );

        $resource = ResourceFactory::create($articles, 'articles');

        echo $this->dependencyInjectionContainer->get('serializer')
            ->serialize($resource, 'json');
    }
}

结果与上面相同。

使用ResourceFactory和JMSSerializerBundle

根据前面的示例，您可能需要手动配置序列化结果的格式。让我们尝试使用JMSSerializerBundle。

如果我们假设上面的'serializer'服务是JMS\SerializerBundle\Serializer\Serializer的一个实例，结果将如下所示

{
    {
        "total_item_count":    2,
        "total_page_count":    1,
        "item_count_per_page": 2,
        "current_page":        1,
        "current_item_count":  2
    },
    "data_key": "articles",
    "articles": [
       {
           "title": "Lorem ipsum",
           "body" : "Not worth reading"
       },
       {
           "title": "Dolor sid amet",
           "body" : "Awesome blog post"
       }
    ],
    "paging": {
        "total_item_count":    2,
        "total_page_count":    1,
        "item_count_per_page": 2,
        "current_page":        1,
        "current_item_count":  2
    }
}

不太吸引人。

JMSSerializerBundle配置救命

在contrib/文件夹中，您将找到一个基本的配置，该配置将使序列化器按照我们想要的方式操作。为了配置它，您需要指定给序列化器的基础类相关联的配置位置。

这可以在contrib/jms-serializer/PaginatedResource/Resource/AbstractResource.yml中找到

只需添加

      jms_serializer:
          metadata:
              directories:
                  BgyPaginatedResource:
                    namespace_prefix: 'Bgy\PaginatedResource\Resource'
                    path: "%kernel.root_dir%/../vendor/borisguery/paginated-resource/contrib/jms-serializer/Bgy/PaginatedResource/Resource"

到您的config.yml。

这将得到以下结果

{
    "articles": [
       {
           "title": "Lorem ipsum",
           "body" : "Not worth reading"
       },
       {
           "title": "Dolor sid amet",
           "body" : "Awesome blog post"
       }
    ],
    "paging": {
        "total_item_count":    2,
        "total_page_count":    1,
        "item_count_per_page": 2,
        "current_page":        1,
        "current_item_count":  2
    }
}

自定义资源

可用资源

目前有4种允许的资源。

NullResource，当您的集合为空时非常有用，并返回NULL
ArrayResource，它接受一个原生PHP数组
ArrayCollectionResource，旨在与Doctrine\Common\Collection\ArrayCollection一起使用
PagerfantaResource，与Pagerfanta分页器一起使用

添加自定义资源

如果您想让它与您自己的类型一起工作，可以添加自定义资源，只需实现ResourceInterface。

自己实现可能有些棘手，并且您可能希望扩展AbstractResource，因为属性需要存在以使序列化器正确工作。

查看现有资源以了解如何使用它，它真的很简单，我保证。

运行测试

首先确保您已安装所有依赖项，在根目录下运行

$ composer install --dev

然后，从根目录运行测试

$ phpunit

贡献

如果您有些时间可以花在无用的项目上，并希望提供帮助，请查看问题列表。

需求

PHP 5.3+
互联网连接

作者

博里斯·格利 - guery.b@gmail.com - http://twitter.com/borisguery - http://borisguery.com

许可证

Bgy\PaginatedResource 使用 WTFPL 许可证授权 - 详细信息请参阅 LICENSE 文件

borisguery / paginated-resource

维护者

详细信息