PHPackages youkoulayley/laravel-api-handler - 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. [HTTP & Networking](/categories/http) 4. / 5. youkoulayley/laravel-api-handler ActiveLibrary[HTTP & Networking](/categories/http) youkoulayley/laravel-api-handler ================================ Package providing helper functions for a Laravel REST-API v1.0.2(5y ago)031MITPHPPHP >=7.4 Since Apr 13Pushed 5y agoCompare [ Source](https://github.com/youkoulayley/laravel-api-handler)[ Packagist](https://packagist.org/packages/youkoulayley/laravel-api-handler)[ Docs](http://github.com/youkoulayley/laravel-api-handler)[ RSS](/packages/youkoulayley-laravel-api-handler/feed)WikiDiscussions master Synced today READMEChangelogDependencies (5)Versions (34)Used By (0) Laravel API Handler ------------------- [](#laravel-api-handler) This helper package provides functionality for parsing the URL of a REST-API request. ### Installation [](#installation) ***Note:*** This version is for Laravel 5. When using Laravel 4 you need to use version 0.4.x. Install the package through composer by running ``` composer require youkoulayley/laravel-api-handler ``` Once composer finished add the service provider to the `providers` array in `app/config/app.php`: ``` Youkoulayley\ApiHandler\ApiHandlerServiceProvider::class, ``` Now import the `ApiHandler` facade into your classes: ``` use Youkoulayley\ApiHandler\Facades\ApiHandler; ``` Or set an alias in `app.php`: ``` 'ApiHandler' => Youkoulayley\ApiHandler\Facades\ApiHandler::class, ``` That's it! ### Migrate from 0.3.x to >= 0.4.x [](#migrate-from-03x-to--04x) #### Relation annotations [](#relation-annotations) Relation methods now need an `@Relation` annotation to prove that they are relation methods and not any other methods (see issue #11). ``` /** * @Relation */ public function author() { return $this->belongsTo('Author'); } ``` #### Custom identification columns [](#custom-identification-columns) If you pass an array as the second parameter to `parseSingle`, there now have to be column/value pairs. This allows us to pass multiple conditions like: ``` ApiHandler::parseSingle($books, array('id_origin' => 'Random Bookstore Ltd', 'id' => 1337)); ``` ### Configuration [](#configuration) To override the configuration, create a file called `apihandler.php` in the config folder of your app. Check out the config file in the package source to see what options are available. ### URL parsing [](#url-parsing) Url parsing currently supports: - Limit the fields - Filtering - Full text search - Sorting - Define limit and offset - Append related models - Append meta information (counts) There are two kind of api resources supported, a single object and a collection of objects. #### Single object [](#single-object) If you handle a GET request on a resource representing a single object like for example `/api/books/1`, use the `parseSingle` method. **parseSingle($queryBuilder, $identification, \[$queryParams\]):** - **$queryBuilder**: Query builder object, Eloquent model or Eloquent relation - **$identification**: An integer used in the `id` column or an array column/value pair(s) (`array('isbn' => '1234')`) used as a unique identifier of the object. - **$queryParams**: An array containing the query parameters. If not defined, the original GET parameters are used. ``` ApiHandler::parseSingle($book, 1); ``` #### Collection of objects [](#collection-of-objects) If you handle a GET request on a resource representing multiple objects like for example `/api/books`, use the `parseMultiple` method. **parseMultiple($queryBuilder, $fullTextSearchColumns, \[$queryParams\]):** - **$queryBuilder**: Query builder object, Eloquent model or Eloquent relation - **$fullTextSearchColumns**: An array which defines the columns used for full text search. - **$queryParams**: An array containing the query parameters. If not defined, the original GET parameters are used. ``` ApiHandler::parseMultiple($book, array('title', 'isbn', 'description')); ``` #### Result [](#result) Both `parseSingle` and `parseMultiple` return a `Result` object with the following methods available: **getBuilder():**Returns the original `$queryBuilder` with all the functions applied to it. **getResult():**Returns the result object returned by Laravel's `get()` or `first()` functions. **getResultOrFail():**Returns the result object returned by Laravel's `get()` function if you expect multiple objects or `firstOrFail()` if you expect a single object. **getResponse($resultOrFail = false):**Returns a Laravel `Response` object including body, headers and HTTP status code. If `$resultOrFail` is true, the `getResultOrFail()` method will be used internally instead of `getResult()`. **getHeaders():**Returns an array of prepared headers. **getMetaProviders():**Returns an array of meta provider objects. Each of these objects provide a specific type of meta data through its `get()` method. **cleanup($cleanup):**If true, the resulting array will get cleaned up from unintentionally added relations. Such relations can get automatically added if they are accessed as properties in model accessors. The global default for the cleanup can be defined using the config option `cleanup_relations` which defaults to `false`. ``` ApiHandler::parseSingle($books, 42)->cleanup(true)->getResponse(); ``` #### Filtering [](#filtering) Every query parameter, except the predefined functions `_fields`, `_with`, `_sort`, `_limit`, `_offset`, `_config` and `_q`, is interpreted as a filter. Be sure to remove additional parameters not meant for filtering before passing them to `parseMultiple`. ``` /api/books?title=The Lord of the Rings ``` All the filters are combined with an `AND` operator. ``` /api/books?title-lk=The Lord*&created_at-min=2014-03-14 12:55:02 ``` The above example would result in the following SQL where: ``` WHERE `title` LIKE "The Lord%" AND `created_at` >= "2014-03-14 12:55:02" ``` Its also possible to use multiple values for one filter. Multiple values are separated by a pipe `|`. Multiple values are combined with `OR` except when there is a `-not` suffix, then they are combined with `AND`. For example all the books with the id 5 or 6: ``` /api/books?id=5|6 ``` Or all the books except the ones with id 5 or 6: ``` /api/books?id-not=5|6 ``` The same could be achieved using the `-in` suffix: ``` /api/books?id-in=5,6 ``` Respectively the `not-in` suffix: ``` /api/books?id-not-in=5,6 ``` ##### Suffixes [](#suffixes) SuffixOperatorMeaning-lkLIKESame as the SQL `LIKE` operator-not-lkNOT LIKESame as the SQL `NOT LIKE` operator-inINSame as the SQL `IN` operator-not-inNOT INSame as the SQL `NOT IN` operator-min>=Greater than or equal to-max<=Smaller than or equal to-st<Smaller than-gt>Greater than-not!=Not equal to#### Sorting [](#sorting) Two ways of sorting, ascending and descending. Every column which should be sorted descending always starts with a `-`. ``` /api/books?_sort=-title,created_at ``` #### Fulltext search [](#fulltext-search) Two implementations of full text search are supported. You can choose which one to use by changing the `fulltext` option in the config file to either `default` or `native`. ***Note:*** When using an empty `_q` param the search will always return an empty result. **Limited custom implementation (default)** A given text is split into keywords which then are searched in the database. Whenever one of the keyword exists, the corresponding row is included in the result set. ``` /api/books?_q=The Lord of the Rings ``` The above example returns every row that contains one of the keywords `The`, `Lord`, `of`, `the`, `Rings` in one of its columns. The columns to consider in full text search are passed to `parseMultiple`. **Native MySQL implementation** If your MySQL version supports fulltext search for the engine you use you can use this advanced search in the api handler. Just change the `fulltext` config option to `native` and make sure that there is a proper fulltext index on the columns you pass to `parseMultiple`. Each result will also contain a `_score` column which allows you to sort the results according to how well they match with the search terms. E.g. ``` /api/books?_q=The Lord of the Rings&_sort=-_score ``` You can adjust the name of this column by modifying the `fulltext_score_column` setting in the config file. #### Limit the result set [](#limit-the-result-set) To define the maximum amount of datasets in the result, use `_limit`. ``` /api/books?_limit=50 ``` To define the offset of the datasets in the result, use `_offset`. ``` /api/books?_offset=20&_limit=50 ``` Be aware that in order to use `offset` you always have to specify a `limit` too. MySQL throws an error for offset definition without a limit. #### Include related models [](#include-related-models) The api handler also supports Eloquent relationships. So if you want to get all the books with their authors, just add the authors to the `_with` parameter. ``` /api/books?_with=author ``` Relationships, can also be nested: ``` /api/books?_with=author.awards ``` To get this to work though you have to add the `@Relation` annotation to each of your relation methods like: ``` /** * @Relation */ public function author() { return $this->belongsTo('Author'); } ``` This is necessary for security reasons, so that only real relation methods can be invoked by using `_with`. ***Note:*** Whenever you limit the fields with `_fields` in combination with `_with`. Under the hood the fields are extended with the primary/foreign keys of the relation. Eloquent needs the linking keys to get related models. #### Include meta information [](#include-meta-information) It's possible to add additional information to a response. There are currently two types of counts which can be added to the response headers. The `total-count` which represents the count of all elements of a resource or to be more specific, the count on the originally passed query builder instance. The `filter-count` which additionally takes filters into account. They can for example be useful to implement pagination. ``` /api/books?id-gt=5&_config=meta-total-count,meta-filter-count ``` All meta fields are provided in the response header by default. The following custom headers are used: ConfigHeadermeta-total-countMeta-Total-Countmeta-filter-countMeta-Filter-Count#### Use an envelope for the response [](#use-an-envelope-for-the-response) By default meta data is included in the response header. If you want to have everything together in the response body you can request a so called "envelope" either by including `response-envelope` in the `_config` parameter or by overriding the default `config.php` of the package. The envelope has the following structure: ``` { "meta": { }, "data": [ ] } ``` ### Health Score 31 — LowBetter than 68% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity7 Limited adoption so far Community12 Small or concentrated contributor base Maturity74 Established project with proven stability Bus Factor1 Top contributor holds 78.9% 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 ~109 days Recently: every ~66 days Total 24 Last Release 1901d ago Major Versions v0.10.0 → v1.0.02020-10-21 PHP version history (3 changes)v0.1.0PHP >=5.3.0 v0.5.0PHP >=5.4.0 v1.0.1PHP >=7.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/5a7c4a91845d4a7c993fa8fe0be54c298690060412be23503274cc373908bcd8?d=identicon)[Youkoulayley](/maintainers/Youkoulayley) --- Top Contributors [![marcelgwerder](https://avatars.githubusercontent.com/u/4008557?v=4)](https://github.com/marcelgwerder "marcelgwerder (60 commits)")[![diego-betalabs](https://avatars.githubusercontent.com/u/1482834?v=4)](https://github.com/diego-betalabs "diego-betalabs (6 commits)")[![jeremykenedy](https://avatars.githubusercontent.com/u/6244570?v=4)](https://github.com/jeremykenedy "jeremykenedy (5 commits)")[![youkoulayley](https://avatars.githubusercontent.com/u/2247492?v=4)](https://github.com/youkoulayley "youkoulayley (2 commits)")[![fernandobandeira](https://avatars.githubusercontent.com/u/8373980?v=4)](https://github.com/fernandobandeira "fernandobandeira (1 commits)")[![lloy0076](https://avatars.githubusercontent.com/u/1174532?v=4)](https://github.com/lloy0076 "lloy0076 (1 commits)")[![diegohq](https://avatars.githubusercontent.com/u/1486939?v=4)](https://github.com/diegohq "diegohq (1 commits)") --- Tags urlapilaravelrestmysqlparse ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/youkoulayley-laravel-api-handler/health.svg) ``` [![Health](https://phpackages.com/badges/youkoulayley-laravel-api-handler/health.svg)](https://phpackages.com/packages/youkoulayley-laravel-api-handler) ``` ### Alternatives [marcelgwerder/laravel-api-handler Package providing helper functions for a Laravel REST-API 16092.6k](/packages/marcelgwerder-laravel-api-handler)[api-platform/laravel API Platform support for Laravel 59126.4k6](/packages/api-platform-laravel)[bjerke/api-query-builder A query builder for Laravel that parses the request and uses Eloquent ORM to query database 267.7k1](/packages/bjerke-api-query-builder)[dragon-code/laravel-http-logger Logging incoming HTTP requests 319.8k3](/packages/dragon-code-laravel-http-logger)[bjerke/laravel-bread A boilerplate package for BREAD operations through REST API in Laravel 115.2k](/packages/bjerke-laravel-bread)[laragear/api-manager Manage multiple REST servers to make requests in few lines and fluently. 161.8k](/packages/laragear-api-manager) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)