exolnet / laravel-bento

Organize feature launches by custom user segments.

Laravel Bento

Bento helps you organize feature launches by custom user segments. Create and organize rules to make features available to certain users.

Define your features, define your segmentation strategies and let Bento launch each feature to the right people. Bento can also help you run A/B testing on your applications.

The core concepts of this library are inspired by Airbnb's Trebuchet project for Ruby.

Installation

Require this package with composer:

composer require eXolnet/laravel-bento

After installing Bento, publish its example service provider to hold your feature definitions:

php artisan vendor:publish --tag=bento-provider

Then, add it to the providers array in config/app.php:

App\Providers\BentoServiceProvider::class

Usage

Create Features

Define features and their launch segmentation strategies. You can define one strategy with the feature method:

Bento::feature('feature')->visitorPercent(10);

Or you can combine multiple strategies:

Bento::feature('feature')->visitorPercent(10)->hostname('example.com');

Your features could be grouped in the boot method of a service provider:

<?php

namespace App\Providers;

use Exolnet\Bento\Facades\Bento;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * @return void
     */
    public function boot(): void
    {
        Bento::feature('foo')->everyone();
        Bento::feature('bar')->everyone();
    }
}

Launch Your Features

You can check if a feature is launched for a visitor with the launch method:

if (Bento::launch('feature')) {
    //
}

Or check that a feature is awaiting launch:

if (Bento::await('feature')) {
    //
}

Blade

In Blade templates, handy macros are also available:

@launch('feature')
    Feature is launched!
@else
    Coming soon!
@endlaunch

@await('feature')
    Coming soon!
@else
    Feature is launched!
@endawait

Middleware

Since some strategy requires the request context to be evaluated, it's recommended to use middleware to limit a route:

1. Add the following middleware in the $routeMiddleware of your application's HTTP Kernel:

    protected $routeMiddleware = [
        // ...
        'await' => \Exolnet\Bento\Middleware\Await::class,
        'launch' => \Exolnet\Bento\Middleware\Launch::class,
        // ...
    ];

2. Then, you could use them to restrict your routes:

Route::middleware('launch:feature')->group(function () {
    //
});

Route::middleware('await:feature')->group(function () {
    //
});

Basic Segmentation Strategies

The following segmentation strategies are available to help quickly target your users:

• Callback
• Config
• Date
• Environment
• Everyone
• Guest
• Hostname
• Nobody
• Stub
• User (authenticated or specific user IDs)
• User Percent (a fraction of all connected visitors)
• Visitor Percent (a fraction of all your visitors)

Logic Segmentation Strategies

Additional logic segmentation strategies are available to help target your users with more complex rules.

Not

Bento::feature('feature')->not->everyone();

All

use \Exolnet\Bento\Strategy\AimsStrategies;

Bento::feature('feature')->all(function (AimsStrategies $aims) {
    $aims
        ->environment('production')
        ->visitorPercent(20);
});

Any

use \Exolnet\Bento\Strategy\AimsStrategies;

Bento::feature('feature')->any(function (AimsStrategies $aims) {
    $aims
        ->environment('staging')
        ->user([1, 2]);
});

Custom Segmentation Strategies

You can create custom strategies with dependency injection support similarly to Laravel Controllers' method injection. A common use-case for method injection is injecting the Illuminate\Contracts\Auth\Guard instance into your strategy to target users by property:

Callback

use Illuminate\Contracts\Auth\Guard;

Bento::feature('feature')->custom(function (Guard $guard, $role) {
    return $guard->user() && $guard->user()->role === 'admin';
});

Class

use Illuminate\Contracts\Auth\Guard;

class RoleStrategy {
    /**
     * @var \Illuminate\Contracts\Auth\Guard
     */
    protected $guard;
    
    /**
     * @var string 
     */
    protected $role;

    /**
     * @param \Illuminate\Contracts\Auth\Guard $guard
     */
    public function __construct(Guard $guard, string $role)
    {
        $this->guard = $guard;
        $this->role = $role;
    }

    /**
     * @return bool
     */
    public function launch(): bool
    {
        return $this->guard->user() && $this->guard->user()->role === $this->role;
    }
}

Bento::feature('feature')->aim(RoleStrategy::class, 'admin');

Testing

To run the PHPUnit tests, please use:

$ composer test

Contributing

Please see CONTRIBUTING and CODE OF CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Alexandre D'Eschambeault
• Airbnb Trebuchet
• All Contributors

License

This code is licensed under the MIT license. Please see the license file for more information.

laravel-bento's Issues

Add documentation on how to use custom strategies

Add a way to call directly the strategies through method call

Bento::feature('name')->visitorPercent(10)

instead of

Bento::feature('name')->aim('visitor-percent', 10).

Should we use isLaunched() or launch()?

Add documentation for all supported strategies

Ability to do A/B testing for a feature

Example:

Bento::ab('button-color', ['#ff0000', '#00ff00', '#0000ff']);

The same visitors will always be affected by the percent strategies

Blade directives should be registered in the boot method

Otherwise, it doesn't work with HTMLmin package.

Review the project's description and topics

Current: Control how your features are launched at your visitors.

Ability to have custom strategies

Strategy to look for a config value

Bento::feature('config')->aim('config', 'name.of.the.config');

Refactor conditions to have a more fluent interface like Laravel's query builder

Example:

Bento::feature('example')
    ->environment(['local', 'testing'])
    ->orAim(function ($feature) {
        $feature
            ->date('2020-01-01', '>=')
            ->custom(new CustomStrategy);
    });

Ability to inject classes with IoC to strategy with custom parameters

Example:

<?php namespace Exolnet\Bento\Strategy;

use Illuminate\Contracts\Auth\Guard;

class User extends Strategy
{
    /**
     * @var \Illuminate\Contracts\Auth\Guard
     */
    protected $guard;

    /**
     * @var array
     */
    protected $userIds;

    /**
     * @param \Illuminate\Contracts\Auth\Guard $guard
     * @param array|int $userIds
     */
    public function __construct(Guard $guard, $userIds)
    {
        $this->userIds = (array)$userIds;
        $this->guard = $guard;
    }

    /**
     * @return bool
     */
    public function launch()
    {
        $userId = $this->guard->id();

        return in_array($userId, $this->userIds);
    }
}

Add a CONTRIBUTING section to the README

Track feature launch in Google Analytics

Ability to override the visitor ID in the VisitorPercent strategy

Example:

Bento::setVisitorId(123);

Add a strategy to launch a feature for a date

Ability to do A/B testing for a matrix of feature

Example:

Bento::abMatrix('button-style', [
    'color' => ['#ff0000', '#00ff00', '#0000ff'],
    'font-size' => [14, 16, 18],
    'font-weight' => ['normal', 'bold'],
]);