PHPackages galafeno/lingo - 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. galafeno/lingo ActiveLibrary[HTTP & Networking](/categories/http) galafeno/lingo ============== A neat REST abstraction 0.0.4(5y ago)26MITPHP Since May 22Pushed 5y agoCompare [ Source](https://github.com/galafeno/lingo)[ Packagist](https://packagist.org/packages/galafeno/lingo)[ RSS](/packages/galafeno-lingo/feed)WikiDiscussions master Synced 1w ago READMEChangelog (3)Dependencies (2)Versions (5)Used By (0) Lingo ===== [](#lingo) Lingo is a package for Laravel that provides a layer of abstraction to any REST service. so it is possible to encapsulate http communication concepts in a much closer object-oriented design and thus improve developer experience. Installation ------------ [](#installation) Use the package manager [composer](https://getcomposer.org/) to install Lingo. ``` composer require galafeno/lingo ``` Usage ----- [](#usage) Use the command `make:lingo` to initialize a new Lingo inside your application. ``` php artisan make:lingo AwesomeApi --base_url=https://awesome.api/v1 ``` That command creates a class called `AwesomeApiLingo` within the folder `App\Lingos`. To model the API you should add the endpoints inside the `sync` section into the `AwesomeApiLingo` class. ``` protected $sync = [ 'base_url' => 'https://awesome.api/v1', 'commands' => [ 'getMovie' => [ 'verb' => 'get', 'url' => "/movies/{:?}" ], ] ]; ``` After that, you can use your Lingo inside your application like so: ``` $movie = Lingo::awesomeApi()->command('getMovie',1)->send(); echo $movie->name; // Batman v Superman: Dawn of Justice ``` The `command` method should receive at least one parameter (the command name). In that case it received 2 parameters because the `getMovie` command has a binding value (marked with the `{:?}` wildcard). #### Custom Headers [](#custom-headers) Lingo was designed to handle json data type, so it will always append the `Content-Type: application/json` and `Accept: application/json` into default headers. To define another headers, create a `headers` property into your Lingo Class ``` protected $headers = [ 'DomainId' => 15, 'SafeMode' => 'Unguarded' ]; ``` That will produce the follow headers in every request: ``` { "Content-Type": "application/json", "Accept": "application/json", "DomainId": "15", "SafeMode": "Unguarded" } ``` You can also define extra headers in runtime like so: ``` Lingo::awesomeApi() ->command('getMovie',1) ->withHeaders(['Scope' => 'readOnly']) ->send(); ``` #### Query parameters [](#query-parameters) To define query parameters, create a `params` property into your Lingo Class ``` protected $params = [ 'start' => '2020-02-02', 'end' => '2020-04-04' ]; ``` That will insert the follow query parameters in every request: ``` GET https://awesome.api/v1/movies/1?start=2020-02-02&end=2020-04-04 ``` You can also define extra query parameters in runtime like so: ``` Lingo::awesomeApi() ->command('getMovie',1) ->withParams(['user_id' => 1]) ->send(); ``` #### Body Parameters [](#body-parameters) To define body parameters, create a `data` property into your Lingo Class ``` protected $data = [ 'username' => 'superuser', 'email' => 'superuser@super.user' ]; ``` That will insert the follow body parameters in every request: ``` POST https://awesome.api/v1/movies { "username": "superuser", "email": "superuser@super.user" } ``` You can also define extra body parameters in runtime like so: ``` Lingo::awesomeApi() ->command('getMovie',1) ->withData(['user_id' => 1]) ->send(); ``` #### Closure Commands [](#closure-commands) Usually you should use Lingo as a way to map endpoints into commands. But using closure command syntax you can trigger a function instead of a real http request. That is a convenient way to append metadata about your api. To do so, use the keyword function inside your command configuration. Then just add the referred function in your Lingo class. ``` 'commands' => [ ... 'list' => [ 'function' => 'getCommandList' ], ... ]; ... protected function getCommandList($bindings) { foreach ($this->sync['commands'] as $command) { if ( isset($command['verb']) && isset($command['url']) ){ echo strtoupper($command['verb']) . " " . $command['url'] . PHP_EOL; } } } ... Lingo::awesomeApi()->command('list')->send(); // GET /peoples // POST /peoples // GET peoples/{:?} // PUT peoples/{:?} // DELETE peoples/{:?} ``` #### Handling Authentication [](#handling-authentication) In real world applications REST services implements some type of authentication scheme. If you are dealing with a simple approach like a signature or key into request headers you should simply use the `withHeaders` command to attach your auth configuration into Lingo. But some services utilizes specifics schemes. To handle it you should define an `auth` configuration within your lingo class. currently, this package supports `apiKeys` and `oauth2` auth methods. ##### apiKeys [](#apikeys) That method will attach the key configuration as a query parameter. ``` protected $sync = [ 'base_url' => 'https://protected.rest/v1', 'auth' => [ 'apiKeys' => [ 'my-key' => 'my-secret' ] ], 'commands' => [ ... ] ]; ``` ``` GET https://protected.rest/v1/someurl?my-key=my-secret ``` ##### oauth2 [](#oauth2) That method will handle the oauth2 flow to retrieve the jwt and cache it using your application cache configuration. ``` protected $sync = [ 'base_url' => 'https://protected.rest', 'auth' => [ 'oauth2' => [ 'url' => '/oauth/token', 'grant_type' => 'client_credentials', 'client_id' => 'my-client-id', 'client_secret' => 'my-client-secret' ] ], 'commands' => [ ... ] ]; ``` #### Mockup mode [](#mockup-mode) While testing your application you must define `APP_ENV=testing` in your `.env` to activate Lingo mockup mode. While using this mode the package will bypass any real request by a mocked static data. You should define that data within your command configuration section using the `shouldReturn` key. ``` protected $sync = [ 'base_url' => 'https://service.rest/v1', 'commands' => [ 'getMovie' => [ 'verb' => 'get', 'url' => "/movies/{:?}", 'shouldReturn' => [ 'id' => 1 'name' => 'static name', 'genre' => 'drama', 'length' => 97 ] ], ] ]; ... $movie = Lingo::awesomeApi()->command('getMovie',1)->send(); echo $movie->name; // static name ``` You can also set mockup mode in runtime like so: ``` $movie = Lingo::awesomeApi()->command('getMovie',1)->withMockup(true)->send(); echo $movie->name; // static name ``` Lingo use `static` as default mockup data mode. But you may set `function` mode with the `mockup` keyword. with that, Lingo will rely on a function to generate the mockup data. ``` protected $sync = [ 'base_url' => 'https://service.rest/v1', 'commands' => [ 'getMovie' => [ 'verb' => 'get', 'url' => "/movies/{:?}", 'mockup' => 'function', 'shouldReturn' => 'makeMovie' ], ] ]; ... protected function makeMovie($bindings) { $faker = \Faker\Factory::create(); return (object)[ 'id' => $bindings[0], 'name' => $faker->name, 'length' => $faker->numberBetween(90,180) ]; } ... $movie = Lingo::awesomeApi()->command('getMovie',1)->send(); echo $movie->name; // name generated by faker ``` #### Async Communication [](#async-communication) If your application utilize AWS infrastructure you may configure asynchronous message within your Lingo class. To do so, you must configure your `async` section. ``` protected $async = [ 'queue' => 'myqueue', 'commands' => [ 'sendEmail' => [ 'action' => 'SendEmail' ] ] ]; ``` To send a asynchronous you have to use the `async` method. ``` Lingo::awesomeApi()->command('sendEmail') ->withData($data) ->async() ->send(); ``` That will push to your sqs queue the payload: ``` [ 'action' => 'sendEmail', 'data' => $data ] ``` Roadmap ------- [](#roadmap) - unit and feature tests - export `sync` section to a swagger file - accepts a closure into `shouldReturn` section, so you can deal with dynamically generated mockup data - add a polymorphic option into `make:lingo`. it will be nice create, for instance a `PaymentLingo` that is a interface and a `StripeLingo` as a concrete class that implements `PaymentLingo` - to allow a sync command trigger a closure or a class method instead of a http request. - custom exceptions - a built-in log system Contributing ------------ [](#contributing) Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests as appropriate. License ------- [](#license) [MIT](https://choosealicense.com/licenses/mit/) ### Health Score 23 — LowBetter than 27% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity7 Limited adoption so far Community6 Small or concentrated contributor base Maturity49 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 ~1 days Total 4 Last Release 2182d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/3757b0955ffe0f907eb0939e7c031b6ace56e20dc08c5b8d7de86d7a55d24130?d=identicon)[rsbroetto](/maintainers/rsbroetto) --- Top Contributors [![rsbroetto](https://avatars.githubusercontent.com/u/37191017?v=4)](https://github.com/rsbroetto "rsbroetto (6 commits)") --- Tags awshttpjsonlaravelphprestsqshttpphpjsonlaravelawsrestsqs ### Embed Badge ![Health badge](/badges/galafeno-lingo/health.svg) ``` [![Health](https://phpackages.com/badges/galafeno-lingo/health.svg)](https://phpackages.com/packages/galafeno-lingo) ``` ### Alternatives [marcin-orlowski/laravel-api-response-builder Helps building nice, normalized and easy to consume Laravel REST API. 837458.6k3](/packages/marcin-orlowski-laravel-api-response-builder)[jacwright/restserver php rest server for very light-weight REST APIs 51070.0k3](/packages/jacwright-restserver)[givebutter/laravel-keyable Add API keys to your Laravel models 187144.5k2](/packages/givebutter-laravel-keyable)[rap2hpoutre/jacky Opinionated REST JSON HTTP API client for laravel 174.4k](/packages/rap2hpoutre-jacky)[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)