Просте керування Feature Flags у Laravel за допомогою Laravel Toggle

Laravel Toggle — це легкий пакет для керування feature flags, орієнтований на глобальні перемикачі (on/off). На відміну від стандартного інструменту Pennant, створеного для сегментації користувачів та A/B-тестування, Laravel Toggle значно простіший: він не прив'язується до конкретних користувачів, а дозволяє керувати прапорцями через .env, базу даних або їхню комбінацію.

# Встановлення

Пакет потребує PHP 8.2+ та Laravel 11, 12 або 13.

composer require offload-project/laravel-toggle
 
php artisan vendor:publish --tag=toggle-config

Якщо ви плануєте використовувати драйвер бази даних, опублікуйте та запустіть міграції:

php artisan vendor:publish --tag=toggle-migrations
php artisan migrate

# Визначення та перевірка прапорців

Налаштування зберігаються у config/toggle.php і можуть залежати від змінних оточення:

'flags' => [
    'comments' => env('TOGGLE_COMMENTS', true),
    'related-articles' => env('TOGGLE_RELATED_ARTICLES', false),
],

Перевірка здійснюється через facade Toggle. Наприклад, контролер може завантажувати зв’язки лише за умови активного прапорця, не перевантажуючи запит зайвою логікою:

use OffloadProject\Toggle\Facades\Toggle;
 
class ArticleController
{
    public function show(string $slug)
    {
        $article = Article::where('slug', $slug)
            ->when(Toggle::active('comments'), fn ($q) => $q->with('comments.author'))
            ->firstOrFail();
 
        return view('articles.show', [
            'article' => $article,
            'related' => Toggle::active('related-articles')
                ? RelatedArticles::for($article)
                : collect(),
        ]);
    }
}

Метод Toggle::inactive() зручний для логіки, яка має спрацьовувати лише при вимкненій функції — наприклад, перехід на спрощену email-розсилку, якщо нова система неактивна:

if (Toggle::inactive('newsletter-v2')) {
    Mail::to($subscriber)->queue(new WeeklyDigest($articles));
}

Blade-шаблони отримали спеціальні директиви, що позбавляють потреби писати умовні конструкції вручну. Типовий приклад — відображення блоку коментарів:

@toggle('comments')
    <livewire:article.comments :article="$article" />
@elsetoggle
    <p class="text-sm text-gray-500">Comments are closed on this post.</p>
@endtoggle

Для кращої типізації можна використовувати enums. Централізація назв у Feature enum забезпечує автодоповнення коду та полегшує пошук застарілих прапорців:

enum Feature: string
{
    case Comments = 'comments';
    case RelatedArticles = 'related-articles';
    case Paywall = 'paywall';
}
 
if (Toggle::active(Feature::Paywall) & $article->isPremium()) {
    return view('articles.paywall', compact('article'));
}

# Драйвери

Laravel Toggle підтримує два типи сховищ, що обираються через TOGGLE_DRIVER:

TOGGLE_DRIVER=config   # Тільки для читання, використовує config/toggle.php
TOGGLE_DRIVER=database # Читання та запис, із fallback до конфігурації

Драйвер config працює лише на читання (з .env). Драйвер database спочатку перевіряє базу даних, а за відсутності запису повертається до значень із конфігурації.

Ви також можете комбінувати обидва підходи, визначивши окремий список для бази даних:

'flags' => [
    'comments' => env('TOGGLE_COMMENTS', true),
    'related-articles' => env('TOGGLE_RELATED_ARTICLES', false),
],
 
'database_flags' => [
    'breaking-news-banner',
    'newsletter-signup-modal',
],

Прапорці з database_flags завжди використовують БД, тоді як звичайні flags залишаються доступними лише для читання. Це дозволяє тримати стабільні налаштування в .env, а оперативні функції вмикати без деплою.

# Керування в реальному часі та кешування

З драйвером бази даних ви можете змінювати стан прапорців програмно. Наприклад, редактор може миттєво активувати банер термінових новин через адмін-панель:

Toggle::enable('breaking-news-banner');
 
// Коли новина втрачає актуальність
Toggle::disable('breaking-news-banner');
 
// Або видалити запис, щоб повернутися до значення за замовчуванням
Toggle::delete('breaking-news-banner');
 
Toggle::all(); // Отримати стан усіх прапорців

Результати перевірок кешуються. Налаштувати сховище та час життя кешу (TTL) можна через .env:

TOGGLE_CACHE_ENABLED=true
TOGGLE_CACHE_STORE=redis
TOGGLE_CACHE_TTL=3600

Eloquent-модель Toggle автоматично очищує кеш при збереженні або видаленні записів. Також це можна зробити вручну через Toggle::forgetCache('name') або Toggle::flushCache().

Поведінку для невизначених прапорців можна гнучко налаштувати: повертати false, true або викидати виняток ToggleNotFoundException для суворого контролю під час розробки.

TOGGLE_DEFAULT=false
TOGGLE_DEFAULT=true
TOGGLE_DEFAULT=exception

# Inertia та Artisan

Для фронтенду на Inertia передбачено middleware ShareTogglesWithInertia, який автоматично передає всі прапорці у props. Це дозволяє Vue, React або Svelte компонентам керувати інтерфейсом без додаткових API-запитів:

use OffloadProject\Toggle\Middleware\ShareTogglesWithInertia;
 
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        ShareTogglesWithInertia::class,
    ]);
})

const { flags } = usePage().props
 
if (flags.breakingNewsBanner) {
    showBanner()
}

Також доступні Artisan-команди для повсякденної роботи: toggle:list для перегляду стану всіх прапорців, toggle:create для швидкого створення нових записів у config та .env, а також toggle:cache-clear для очищення кешу.

Дізнатися більше та переглянути вихідний код можна на GitHub.