🚧 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 --tag=butler-assets
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.

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.

Views

Views can be updated by publishing them:

php artisan vendor:publish --tag=butler-views

Extra

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

    // example
    'config' => [
        'foo' => 'bar',
        'trustedproxy.proxies' => [
            '10.0.0.0/8',
        ],
    ],

index.php

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 OAuth

Configure butler.sso in config/butler.php.

Set butler.sso.fake to true to fake to login process.

See laravel/socialite for more information.

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 specific operations
$consumer->createToken(['query:ping'], 'my "ping" token');
$consumer->createToken(['query', 'mutation:start'], 'my "start" token');

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

Redacting secrets from Bugsnag

Bugsnag only redacts metadata by key, never error messages. When Bugsnag is enabled, values of the config keys in butler.service.redact_bugsnag_config are therefore replaced with their config key in error messages (including previous errors) and metadata, e.g. https://hooks.slack.com/[services.slack.webhook]. Wildcards are supported, see RedactSecrets::DEFAULT_CONFIG for the defaults.

Credentials in urls (scheme://user:password@host) and Slack webhook urls not found in config are always redacted. Use an empty array to disable.

    // example
    'redact_bugsnag_config' => [
        ...\Butler\Service\Bugsnag\Middlewares\RedactSecrets::DEFAULT_CONFIG,
        'services.netbox.key',
    ],

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.

Testing

vendor/bin/phpunit
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.