README

A Laravel package that provides dynamic option registration for dropdowns, select boxes, and any UI component that needs predefined or dynamic data.

What is Optioner?

Optioner solves the common problem of managing option lists in Laravel applications. Instead of writing repetitive code to fetch and format data for dropdowns, Optioner handles it all through dynamic registration within Laravel Service Providers.

Key Features

✅ Dynamic Registration - Register options programmatically in Service Providers
✅ Static & Callable Data - Support for both arrays and closures
✅ Automatic Caching - Built-in caching with configurable TTL
✅ Model Cache Invalidation - Automatic cache clearing on model changes
✅ RESTful API - Clean API endpoints for frontend consumption
✅ Artisan Commands - Developer tools for cache management

Installation

Install the package via Composer:

composer require sgflores/optioner

Quick Setup

1. Publish Configuration

php artisan vendor:publish --tag=optioner-config

2. Publish Example Provider and Registrars

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

This creates the following under app/Providers/Optioner/:

OptionServiceProvider.php - boots option registration
StaticOptionsRegistrar.php - example static options
DynamicOptionsRegistrar.php - example dynamic options

3. Register Options

Edit app/Providers/Optioner/OptionServiceProvider.php to wire up registrars (already done by default):

<?php

namespace App\Providers\Optioner;

use Illuminate\Support\ServiceProvider;
use App\Providers\Optioner\StaticOptionsRegistrar;
use App\Providers\Optioner\DynamicOptionsRegistrar;

class OptionServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        app(StaticOptionsRegistrar::class)->register();
        app(DynamicOptionsRegistrar::class)->register();
    }
}

4. Register Service Provider

Add the service provider to bootstrap/providers.php:

<?php

return [
    // ... other providers
    App\Providers\Optioner\OptionServiceProvider::class,
];

Usage

Using the Facade

use SgFlores\Optioner\Facades\Optioner;

// Get a single option list
$users = Optioner::get('users');

// Get multiple option lists
$data = Optioner::getMany(['users', 'categories', 'countries', 'genders']);

Using the API

The package automatically creates API routes:

# Get a single option list
GET /api/optioner?model=users

# Get multiple option lists
GET /api/optioner?models[]=users&models[]=categories&models[]=countries&models[]=genders

API Response

{
    "success": true,
    "data": {
        "users": {"1": "John Doe", "2": "Jane Smith"},
        "categories": {"1": "Electronics", "2": "Clothing", "3": "Books", "4": "Home & Garden"},
        "countries": {"1": "United States", "2": "Canada", "3": "United Kingdom", "4": "Germany"},
        "genders": {"M": "Male", "F": "Female", "O": "Other"}
    }
}

Option Registration

Basic Registration

// Static array
Optioner::register('statuses', [
    'active' => 'Active',
    'inactive' => 'Inactive'
]);

// Callable function - Categories
Optioner::register('categories', function () {
    return \App\Models\Category::where('is_active', true)
        ->orderBy('name')
        ->pluck('name', 'id')
        ->toArray();
});

// Callable function - Countries
Optioner::register('countries', function () {
    return \App\Models\Country::orderBy('name')
        ->pluck('name', 'id')
        ->toArray();
});

Advanced Registration

// With model for cache invalidation and custom TTL
Optioner::register('active_users', function () {
    return \App\Models\User::where('is_active', true)
        ->pluck('name', 'id')
        ->toArray();
}, \App\Models\User::class, 1800); // 30 minutes cache

Registration Parameters

Optioner::register(
    string $key,           // Option key
    array|callable $data,  // Static array or callable
    string|null $model,    // Model class for cache invalidation
    int|null $ttl          // Cache TTL in seconds
);

Developer Tools

Artisan Commands

# List all registered options
php artisan optioner:list

# Clear option caches
php artisan optioner:clear

# Warm up caches
php artisan optioner:warm

Cache Management

# Clear all caches
php artisan optioner:clear --force

# Clear specific options
php artisan optioner:clear --option=users,departments

# Dry run (see what would be cleared)
php artisan optioner:clear --dry-run

Configuration

Default Settings

// config/optioner.php
return [
    'defaults' => [
        'cache_enabled' => true,
        'cache_ttl' => 3600, // 1 hour
    ],
    'routes' => [
        'enabled' => true,
        'prefix' => 'api/optioner',
        'middleware' => ['api'],
    ],
];

Route Configuration

// Disable API routes
'routes' => [
    'enabled' => false,
],

// Use standard Laravel middleware
'routes' => [
    'middleware' => ['api', 'auth:sanctum'], // Requires login route
],

Troubleshooting

For detailed troubleshooting information, including solutions for common issues like "Route [login] not defined" errors, please refer to the High-Level Documentation.

Testing

Run the test suite:

composer test

Documentation

📖 High-Level Documentation - Complete guide to how Optioner works
🔧 Package Development Guide - For package developers
🧪 Test Documentation - Testing guide and coverage

License

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

Author

sgflores

Email: floresopic@gmail.com
GitHub: @sgflores

Made with ❤️ for the Laravel community

sgflores / optioner

Maintainers

Details