glesys/butler-service

Web service library based on Laravel


README

🚧 Not ready for production.

Butler Service

A Laravel-based micro-framework for web services using GraphQL and RabbitMQ.

Getting Started

Requires a working Laravel app with a database connection.

composer require glesys/butler-service
php artisan vendor:publish --provider="Butler\Service\ServiceProvider" --tag=config # optional
php artisan migrate

Replace Illuminate\Foundation\Application with Butler\Service\Foundation\Application in bootstrap/app.php.

It is optional (but recommended) to extend your TestCase (or whatever file that extends Laravels TestCase) with Butler\Service\Testing\TestCase.

use Butler\Service\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    //
}

Service Providers

All service providers in your app/Providers directory will be registered automatically.

Config

You can use your configuration files as usual. See src/config for our defaults.

ℹ️ Remember that your applications config/butler.php only merges the first level of the default configuration.

Default routes

There are 3 default routes; "front", "graphql" and "health". They can be updated at butler.service.routes in config/butler.php.

For example you might want to listen for graphql on /api instead of /graphql.

Their views can be updated by publishing them:

php artisan vendor:publish --provider="Butler\Service\ServiceProvider" --tag=views

Extra

If you dont want a config/app.php you can use butler.service.extra in config/butler.php to add "providers", "aliases" and "config". Note that "config" will not merge with existing config.

    // example
    'providers' => [
        Foo\BarServiceProvider::class,
    ],
    'aliases' => [
        'Backend' => App\Facades\Backend::class,
    ],
    'config' => [
        'trustedproxy.proxies' => [
            '10.0.0.0/8',
        ],
    ],

Authentication with butler-auth

$consumer = \Butler\Service\Models\Consumer::create(['name' => 'Service A']);

$token = $consumer->createToken(abilities: ['*'], name: 'token-name')->plainTextToken;

See butler-auth for more information.

Authorization

GraphQL operations are authorized by the "graphql" Gate ability defined in the ServiceProvider.

// allow "query" operations only
$consumer->createToken(['query'], 'my read-only token');

// allow "mutation" operations only
$consumer->createToken(['mutation'], 'my write-only token');

// allow any operations
$consumer->createToken(['*'], 'my full-access token');
$consumer->createToken(['query', 'mutation', 'subscription'], 'my graphql token');

GraphQL with butler-graphql

See butler-graphql.

RabbitMQ with butler-guru

See butler-guru.

Audit with butler-audit

See butler-audit.

Health checks with butler-health

See butler-health for more information.

Testing

vendor/bin/phpunit
vendor/bin/phpcs

How To Contribute

Development happens at GitHub; any typical workflow using Pull Requests are welcome. In the same spirit, we use the GitHub issue tracker for all reports (regardless of the nature of the report, feature request, bugs, etc.).

Code standard

As the library is intended for use in Laravel applications we encourage code standard to follow upstream Laravel practices - in short that would mean PSR-2 and PSR-4.