galafeno/lingo is a Laravel package for a neat rest abstraction.
It currently has 2 GitHub stars and 6 downloads on Packagist (latest version 0.0.4).
Install it with composer require galafeno/lingo.
Discover more Laravel packages by galafeno
or browse all Laravel packages to compare alternatives.
Last updated
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.
Use the package manager composer to install Lingo.
composer require galafeno/lingo
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).
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();
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();
To define body parameters, create a data property into your Lingo Class
protected $data = [
'username' => 'superuser',
'email' => '[email protected]'
];
That will insert the follow body parameters in every request:
POST https://awesome.api/v1/movies
{
"username": "superuser",
"email": "[email protected]"
}
You can also define extra body parameters in runtime like so:
Lingo::awesomeApi()
->command('getMovie',1)
->withData(['user_id' => 1])
->send();
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/{:?}
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.
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
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' => [
...
]
];
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
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
]
sync section to a swagger fileshouldReturn section, so you can deal with dynamically generated mockup datamake:lingo. it will be nice create, for instance a PaymentLingo that is a interface and a StripeLingo as a concrete class that implements PaymentLingoPull 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.
