PHPackages develme/restful-lists - 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. develme/restful-lists ActiveLibrary[API Development](/categories/api) develme/restful-lists ===================== Adds filter, order, and pagination to your restful resource lists v1.0.0-alpha-04102021-001(5y ago)110MITPHPPHP >=8.0 Since Mar 27Pushed 3y ago2 watchersCompare [ Source](https://github.com/develme/restful-lists)[ Packagist](https://packagist.org/packages/develme/restful-lists)[ RSS](/packages/develme-restful-lists/feed)WikiDiscussions master Synced today READMEChangelogDependencies (9)Versions (5)Used By (0) [![Build Status](https://camo.githubusercontent.com/21d9c704325bae304ac3950f5909c19d74dc8b035269465b8d813a2e7ca7da65/68747470733a2f2f7472617669732d63692e636f6d2f646576656c6d652f7265737466756c2d6c697374732e737667)](https://travis-ci.com/develme/restful-lists)[![Total Downloads](https://camo.githubusercontent.com/e1455a000aedfc2c62fafa04175cdc76c1b7ceb6d64bf5c2b18c02db58b64a73/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f646576656c6d652f7265737466756c2d6c69737473)](https://packagist.org/packages/develme/restful-lists)[![Latest Stable Version](https://camo.githubusercontent.com/6305f1f767122c3a6d2f452713efd568cbcb0427e1d6d78f16d0a5cefb1c1dc2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f646576656c6d652f7265737466756c2d6c69737473)](https://packagist.org/packages/develme/restful-lists)[![License](https://camo.githubusercontent.com/442bec37d6ddaa9c1ddbb452788e1c48470aacc1beeef07076ce0565e52ad2e5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f646576656c6d652f7265737466756c2d6c69737473)](https://packagist.org/packages/develme/restful-lists) Restful Lists is a library that allows a list style endpoint to instantly support common features like filtering, sorting, and pagination. Wrap your data in an engine or service class to quickly parse get/post variables detailing what filters, orders, and pagination to apply. Install ------- [](#install) ``` composer require develme/restful-lists ``` Data Types ---------- [](#data-types) Data types are the different forms of persistent data the engine attempts to filter, order and paginate. This is the layer one can use to add support for various data layers like Redis, SQL, Plain Arrays, even data stored in files or other API endpoints. ### Supported [](#supported) - Collection - Eloquent's Model Builder ### Coming Soon [](#coming-soon) - Array - Eloquent's Query Builder Examples -------- [](#examples) ### Using the service within a laravel/lumen controller [](#using-the-service-within-a-laravellumen-controller) This example uses the service class. The service class automatically parses get and post vars to apply filtering, sorting and pagination. You can find example javascript and url structures below. ``` use DevelMe\RestfulList\Model\Service; use Symfony\Component\HttpFoundation\Response; use Tests\Models\Example; public function index(Example $example, Service $service): Response { return $service->model($example)->json(); } ``` ### Using the engine directly [](#using-the-engine-directly) ``` $myData = []; // $data = new \Illuminate\Support\Collection($myData); $orchestrator = new \DevelMe\RestfulList\Collection\Orchestration\Orchestrator(); $orchestrator->register(); $engine = new \DevelMe\RestfulList\Engines\Collection($data, $orchestrator); // Filters $engine->filters([ 'status' => 'Open', // status equals 'Open' - Simple filters default to equals 'name' => ['field' => 'name', 'type' => 'contains', 'value' => 'John'], // name contains 'John' | Results in '%John%' for SQL ]); // Orders $engine->orders([ 'state', // order by state ascending - Simple orders default to ascending 'created_at' => 'desc', // order by created_at descending - key => value equates to field => direction 'title' => ['field' => 'title', 'direction' => 'desc'], // order by title descending - Explicitly defining field and direction ]); // Pagination - simple $engine->pagination([100, 200]); // start at 100 end at 200 - Index 0 is start, index 1 is end | offset 100 limit 100 for SQL // Pagination - explicit $engine->pagination(['start' => 100, 'end' => 200]); // Results $results = $engine->go(); ``` Example javascript object structure ``` let parameters = { "filters" : { 'status' : 'Open', // status equals 'Open' - Simple filters default to equals 'name' : {'field' : 'name', 'type' : 'contains', 'value' : 'John'}, // name contains 'John' | Results in '%John%' for SQL }, 'orders' : { 'state' : null, // order by state ascending - Simple orders default to ascending 'created_at' : 'desc', // order by created_at descending - key => value equates to field => direction 'title' : {'field' : 'title', 'direction' : 'desc'}, // order by title descending - Explicitly defining field and direction }, 'pagination' : { 'page' : 2, 'size' : 30, } } // One could use jQuery.param to convert it to a query string or choose to post JSON back. let query = jQuery.param(parameters); let url = `https://www.develme.com/example?${query}`; ``` Example URL created from the javascript object ``` https://www.develme.com/example?filters%5Bstatus%5D=Open&filters%5Bname%5D%5Bfield%5D=name&filters%5Bname%5D%5Btype%5D=contains&filters%5Bname%5D%5Bvalue%5D=John&orders%5B0%5D=state&orders%5Bcreated_at%5D=desc&orders%5Btitle%5D%5Bfield%5D=title&orders%5Btitle%5D%5Bdirection%5D=desc&pagination%5Bpage%5D=2&pagination%5Bsize%5D=30 ``` Example PHP array structure as a result of the javascript passed back ``` $parameters = [ 'filters' => [ 'status' => 'Open', // status equals 'Open' - Simple filters default to equals 'name' => ['field' => 'name', 'type' => 'contains', 'value' => 'John'], // name contains 'John' | Results in '%John%' for SQL ], 'orders' => [ 'state', // order by state ascending - Simple orders default to ascending 'created_at' => 'desc', // order by created_at descending - key => value equates to field => direction 'title' => ['field' => 'title', 'direction' => 'desc'], // order by title descending - Explicitly defining field and direction ], 'pagination' => [ 'page' => 2, 'size' => 30, ] ] ``` Customization ------------- [](#customization) ### Data Types [](#data-types-1) ### Custom Data Types [](#custom-data-types) Since data types are completely decoupled from the engine, it is fairly straight forward to add support for custom data types. Implement the DevelMe\\RestfulList\\Contracts\\Orchestration interface, taking care of the various calls the engine makes to the implementation with various filter/sort/paginate settings. A custom engine is also needed to handle your custom data type. #### Instantiating the engine with a custom data type [](#instantiating-the-engine-with-a-custom-data-type) ``` /** * Engine that supports the custom data */ class CustomDataEngine extends \DevelMe\RestfulList\Engines\Base { protected $data; public function __construct($customData, \DevelMe\RestfulList\Contracts\Orchestration $orchestrator) { parent::__construct($orchestrator); $this->data = $customData; } } /** * Handles calls for filtering, sorting, paginating and fetching results. Naturally the Orchestrator wants to use the * Strategy behavioral pattern to break out the necessary functionality into smaller class implementations. * * Below, we are returning CustomDataHandler which can implement the interfaces specified in the method tags, keeping * all the code together, if desired * * @method \DevelMe\RestfulList\Contracts\Counter counter() * @method \DevelMe\RestfulList\Contracts\Engine\Filtration filter() * @method \DevelMe\RestfulList\Contracts\Engine\Arrangement order() * @method \DevelMe\RestfulList\Contracts\Engine\Paginator pagination() * @method \DevelMe\RestfulList\Contracts\Engine\Result result() */ class CustomOrchestrator implements \DevelMe\RestfulList\Contracts\Orchestration { /** * We're letting CustomDataHandler handle everything, but one should leverage the dynamic method call implemented * here to return single responsibility implementations of what is being requested in the $ask variable. */ public function orchestrate(string $ask): mixed { return new CustomDataHandler; } public function __call(string $name,array $arguments) { $this->orchestrate($name); } } /** * This handler can handle everything. It has way too many responsibilities, and breaking the behaviors into different * class implementations would be the desired result. */ class CustomDataHandler implements \DevelMe\RestfulList\Contracts\Counter, \DevelMe\RestfulList\Contracts\Engine\Filtration, \DevelMe\RestfulList\Contracts\Engine\Arrangement, \DevelMe\RestfulList\Contracts\Engine\Paginator, \DevelMe\RestfulList\Contracts\Engine\Result { public function arrange(\DevelMe\RestfulList\Contracts\Engine\Data $data,array $orders) { // TODO: Implement arrange() method. } public function count(\DevelMe\RestfulList\Contracts\Engine\Data $data) : int { // TODO: Implement count() method. } public function filter(\DevelMe\RestfulList\Contracts\Engine\Data $data,array $filters) { // TODO: Implement filter() method. } public function paginate(\DevelMe\RestfulList\Contracts\Engine\Data $data,array $pagination) { // TODO: Implement paginate() method. } public function get(\DevelMe\RestfulList\Contracts\Engine\Data $data) { // TODO: Implement get() method. } } $data = new My\Custom\XML\Loader('path-to-xml-file.xml'); $orchestrator = new CustomOrchestrator(); $engine = new CustomDataEngine($data, $orchestrator); $results = $engine->filters([])->orders([])->pagination([])->go(); ``` ### Health Score 22 — LowBetter than 22% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity7 Limited adoption so far Community8 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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. ### Release Activity Cadence Every ~7 days Total 3 Last Release 1856d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/e9a3bd10e177bfb2a6be7cc5c3655324f6e3e47e7cea0c7af6c638a2054d6322?d=identicon)[Verron](/maintainers/Verron) --- Top Contributors [![Verron](https://avatars.githubusercontent.com/u/1887313?v=4)](https://github.com/Verron "Verron (96 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/develme-restful-lists/health.svg) ``` [![Health](https://phpackages.com/badges/develme-restful-lists/health.svg)](https://phpackages.com/packages/develme-restful-lists) ``` ### Alternatives [spatie/laravel-query-builder Easily build Eloquent queries from API requests 4.4k26.9M220](/packages/spatie-laravel-query-builder)[laravel/cashier Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services. 2.5k25.9M107](/packages/laravel-cashier)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k12.1M99](/packages/laravel-pulse)[essa/api-tool-kit set of tools to build an api with laravel 52680.5k](/packages/essa-api-tool-kit)[laravel/cashier-paddle Cashier Paddle provides an expressive, fluent interface to Paddle's subscription billing services. 264778.4k3](/packages/laravel-cashier-paddle)[flat3/lodata OData v4.01 Producer for Laravel 96320.9k](/packages/flat3-lodata) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)