README

The official Beacon driver for Laravel Pennant, enabling seamless feature flag management through the Beacon platform.

Full Documentation

Installation

You can install the package via Composer:

composer require beacon-hq/pennant-driver

The package will automatically register its service provider through Laravel's package auto-discovery.

Configuration

Environment Variables

Add the following environment variables to your .env file:

BEACON_API_URL=https://your-beacon-instance.com
BEACON_API_TOKEN=your-api-token
BEACON_APP_NAME=YourAppName
BEACON_API_PATH_PREFIX=/api
BEACON_API_TIMEOUT=3000 # in milliseconds

Pennant Configuration

Update your config/pennant.php file to include the Beacon driver:

<?php

return [
    'default' => env('PENNANT_STORE', 'beacon'),

    'stores' => [
        'beacon' => [
            'driver' => 'beacon',
            'app_name' => env('BEACON_APP_NAME', env('APP_NAME', 'Laravel')),
            'environment' => env('BEACON_ENVIRONMENT', env('APP_ENV', 'local')),
            'url' => env('BEACON_API_URL', 'https://api.beaconhq.io/'),
            'path_prefix' => env('BEACON_API_PATH_PREFIX', '/api'),
            'cache_store' => env('BEACON_CACHE_STORE', config('cache.default', 'array')),
            'cache_ttl' => env('BEACON_CACHE_TTL', 1800),
            'api_key' => env('BEACON_ACCESS_TOKEN'),
            'api_timeout' => env('BEACON_API_TIMEOUT', 3000),
        ],
    ],
];

Configuration Options

• app_name: The name of your application as registered in Beacon
• environment: The environment name (e.g., production, staging, local)
• url: The base URL of your Beacon API instance
• path_prefix: The API path prefix (default: /api)
• cache_store: The cache store to use (default: Laravel's default cache store)
• cache_ttl: Cache time-to-live in seconds (default: 1800 seconds / 30 minutes)
• api_key: Your Beacon API authentication token
• api_timeout: Beacon API request timeout, (recommended: no less than 100ms no greater than 3000ms)

Usage

Once configured, you can use Laravel Pennant's standard API to interact with feature flags:

Basic Feature Checking

use Laravel\Pennant\Feature;

// Check if a feature is active
if (Feature::active('new-dashboard')) {
    // Show new dashboard
}

// Check if a feature is inactive
if (Feature::inactive('legacy-feature')) {
    // Hide legacy feature
}

Scoped Features

use Laravel\Pennant\Feature;

// Check feature for a specific user
$user = auth()->user();
if (Feature::for($user)->active('premium-features')) {
    // Show premium features
}

// Check feature for a team
$team = $user->team;
if (Feature::for($team)->active('team-collaboration')) {
    // Enable team collaboration features
}

Retrieving Feature Values

use Laravel\Pennant\Feature;

// Get feature value (boolean, string, array, etc.)
$config = Feature::value('feature-config');

Conditional Execution

use Laravel\Pennant\Feature;

// Execute code when feature is active
Feature::when('new-feature', function () {
    // Code to run when feature is active
}, function () {
    // Code to run when feature is inactive (optional)
});

Context Information

The Beacon driver automatically sends contextual information with each request:

• Scope Type: The class name of the scoped object (e.g., User, Team)
• Scope: The actual scope object or identifier
• App Name: Your application name
• Environment: Current Laravel environment
• Session ID: Current session identifier (if available)
• IP Address: Client IP address
• User Agent: Client user agent string
• Referrer: HTTP referrer header
• URL: Current request URL
• Method: HTTP request method

This context helps Beacon make intelligent feature flag decisions based on your application's state.

Caching

The driver includes built-in caching to improve performance:

• Feature responses are cached for the configured TTL (default: 30 minutes)
• Cache keys are generated based on feature names and scope serialization
• You can flush the cache using the driver's flushCache() method

Testing

Run the test suite:

composer test

Run code style checks:

composer lint

Requirements

• PHP 8.1 or higher
• Laravel 10.0 or higher
• Laravel Pennant 1.14 or higher

License

This package is open-sourced software licensed under the MIT license.

Credits

• Davey Shafik

Support

For support, please contact Beacon HQ or open an issue on GitHub.