PHPackages borisguery/paginated-resource - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. borisguery/paginated-resource ActiveLibrary[API Development](/categories/api) borisguery/paginated-resource ============================= A resource wrapper to encapsulate paginated resource into REST-like API. 116.9k2PHP Since Dec 24Pushed 13y ago1 watchersCompare [ Source](https://github.com/borisguery/PaginatedResource)[ Packagist](https://packagist.org/packages/borisguery/paginated-resource)[ RSS](/packages/borisguery-paginated-resource/feed)WikiDiscussions master Synced 3w ago READMEChangelogDependenciesVersions (2)Used By (0) PaginatedResource [![Build Status](https://camo.githubusercontent.com/700c50a505ccaac77a8f6fda2392baa9edd6f6e071db949fbd97fa5e5b22287a/68747470733a2f2f7472617669732d63692e6f72672f626f72697367756572792f506167696e617465645265736f757263652e706e67)](https://travis-ci.org/borisguery/PaginatedResource) ========================================================================================================================================================================================================================================================================================================= [](#paginatedresource--) Table of contents ----------------- [](#table-of-contents) 1. [Description](#description) 2. [Installation](#installation) 3. [Usage](#usage) 4. [Basic usage](#basic-usage) 5. [Using the `ResourceFactory`](#using-the-resourcefactory) 6. [Using `ResourceFactory` and JMSSerializerBundle](#using-resourcefactory-and-jmsserializerbundle) 1. [JMSSerializerBundle config to the rescue](#jmsserializerbundle-config-to-the-rescue) 7. [Custom Resources](#custom-resources) 1. [Available Resources](#available-resources) 2. [Adding custom Resource](#adding-custom-resource) 8. [Run the test](#run-the-test) 9. [Contributing](#contributing) 10. [Requirements](#requirements) 11. [Authors](#authors) 12. [License](#license) Description ----------- [](#description) A resource wrapper to encapsulate paginated resource into REST-like API. It is designed to provide paging data along with a resource collection. It is mostly supposed to be used with JMSSerializerBundle but there are no dependencies against it and it should work with/without any other Serializer component. This library is mostly a draft but has been heavily tested and it should be production ready in most case. Installation ------------ [](#installation) Using [Composer](http://getcomposer.org/), just require the borisguery/paginated-resource package: ``` { "require": { "borisguery/paginated-resource": "dev-master" } } ``` If you wish to use this library with Pagerfanta or Doctrine 2 ArrayCollection, install the according dependencies: ``` { "require": { "pagerfanta/pagerfanta": "*", "doctrine/common": ">2.0", } } ``` It may not be needed if you already use Doctrine2 ORM and/or any of the Pagerfanta Bundle. Usage ----- [](#usage) ### Basic usage [](#basic-usage) ``` 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(), ) ); } } ``` The result will looks like: ``` { "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 } } ``` Obviously, this isn't really usefull since we have to know both the initial resource type and we need to serialize the data ourselve. Thanks to the `ResourceFactory` you can dynamically create resource according to their initial type. ### Using the `ResourceFactory` [](#using-the-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'); } } ``` Will result the same as above. ### Using ResourceFactory and JMSSerializerBundle [](#using-resourcefactory-and-jmsserializerbundle) Taking the previous example, you may need to manually configure how the serialized result will look like. Let's try with the JMSSerializerBundle. If we assume the 'serializer' service from the above example is an instance of `JMS\SerializerBundle\Serializer\Serializer`the result will looks like this: ``` { { "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 } } ``` Not really sexy. #### JMSSerializerBundle config to the rescue [](#jmsserializerbundle-config-to-the-rescue) In the `contrib/` folder, you will find a basic configuration which will make the Serializer acts as we want to. In order to configure it you need to specify to the Serializer where are the associated configuration for the base class. This may be found in `contrib/jms-serializer/PaginatedResource/Resource/AbstractResource.yml` Just add: ``` jms_serializer: metadata: directories: BgyPaginatedResource: namespace_prefix: 'Bgy\PaginatedResource\Resource' path: "%kernel.root_dir%/../vendor/borisguery/paginated-resource/contrib/jms-serializer/Bgy/PaginatedResource/Resource" ``` To your `config.yml`. This will results in: ``` { "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 } } ``` ### Custom Resources [](#custom-resources) #### Available Resources [](#available-resources) There are currently 4 allowed Resources. - `NullResource`, usefull when your collection is empty and returns `NULL` - `ArrayResource`, which takes a native PHP array - `ArrayCollectionResource`, intended to work with `Doctrine\Common\Collection\ArrayCollection` - `PagerfantaResource`, works with the Pagerfanta paginator #### Adding custom Resource [](#adding-custom-resource) If you want to make it work with your own type, you can add Custom Resource, just implement the `ResourceInterface`. It may be tricky to implement it yourself, and you likely want to extend the `AbstractResource` because the properties need to exist to make the serializer works correctly. Take a look at the existing Resource to know what to do with it, it is really simple, I promise. Run the test ------------ [](#run-the-test) First make sure you have installed all the dependencies, run: `$ composer install --dev` then, run the test from within the root directory: `$ phpunit` Contributing ------------ [](#contributing) If you have some time to spare on an useless project and would like to help take a look at the [list of issues](http://github.com/borisguery/PaginatedResource/issues). Requirements ------------ [](#requirements) - PHP 5.3+ - Internet connection Authors ------- [](#authors) Boris Guéry - - - License ------- [](#license) `Bgy\PaginatedResource` is licensed under the WTFPL License - see the LICENSE file for details ### Health Score 28 — LowBetter than 52% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity29 Limited adoption so far Community11 Small or concentrated contributor base Maturity43 Maturing project, gaining track record Bus Factor1 Top contributor holds 96.6% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/e697c30c60bfd1c329e9661645ba5a79dd62d6375e48656b9ba9eaf54fd59956?d=identicon)[borisguery](/maintainers/borisguery) --- Top Contributors [![borisguery](https://avatars.githubusercontent.com/u/345495?v=4)](https://github.com/borisguery "borisguery (28 commits)")[![choomz](https://avatars.githubusercontent.com/u/1176482?v=4)](https://github.com/choomz "choomz (1 commits)") ### Embed Badge ![Health badge](/badges/borisguery-paginated-resource/health.svg) ``` [![Health](https://phpackages.com/badges/borisguery-paginated-resource/health.svg)](https://phpackages.com/packages/borisguery-paginated-resource) ``` ### Alternatives [exsyst/swagger A php library to manipulate Swagger specifications 35816.3M7](/packages/exsyst-swagger)[hubspot/api-client Hubspot API client 24015.5M18](/packages/hubspot-api-client)[pocketmine/bedrock-protocol An implementation of the Minecraft: Bedrock Edition protocol in PHP 172437.8k11](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram Telegram driver for BotMan 93452.6k6](/packages/botman-driver-telegram)[pixelant/pxa-social-feed Add Facebook, Instagram, and Twitter feeds to your site. 2349.3k](/packages/pixelant-pxa-social-feed) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)