Web service library based on Laravel


🚧 Not ready for production.

Butler Service

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

Getting Started

Requires a working Laravel app with a database connection.

composer require glesys/butler-service

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

php artisan vendor:publish --tag=butler-config
php artisan migrate

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.


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 --tag=butler-views


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' => [
    'aliases' => [
        'Backend' => App\Facades\Backend::class,
    'config' => [
        'trustedproxy.proxies' => [


To keep your applications "index.php" up to date you can publish the one in butler-service.

ℹ️ Maintenance mode is not supported.

php artisan vendor:publish --force --tag=butler-index

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.


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.

Audit with butler-audit

See butler-audit.

Health checks with butler-health

See butler-health for more information.

Database host maintenance

For applications using multiple database hosts, you may add a maintenance option on your database connection with a cron expression for when the host with the same index as the expression should be in maintenance mode.

In the example below, "host1" will not be used by the application between 01:00 and 01:59.

    // config/database.php
    'host' => ['host1', 'host2', 'host3'],
    'maintenance' => ['* 1 * * *', '* 2 * * *', '* 3 * * *'],

ℹ️ When running i.e. laravel-octane you need to use the DisconnectFromDatabases listener.


vendor/bin/pint --test

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.