README

Settings Package

A comprehensive settings management system built on top of Spatie Laravel Settings with automatic discovery, fluent API, and RESTful API endpoints.

Features

✅ Automatic Discovery: Settings classes are automatically discovered via #[Setting] attribute
✅ Fluent API: Type-safe methods for accessing settings (string(), bool(), int(), float(), array())
✅ Helper Function: Convenient settings() helper for quick access
✅ RESTful API: Full CRUD API endpoints for managing settings
✅ Repository Pattern: Clean separation of concerns with Service/Repository layers
✅ Dependency Injection: Settings classes can be injected into constructors
✅ Locking: Lock settings to prevent accidental updates
✅ Spatie Integration: Full compatibility with Spatie Laravel Settings features

Installation

The package is already installed as part of the monorepo. If installing separately:

composer require pixielity/laravel-settings

Quick Start

1. Create a Settings Class

<?php

namespace App\Settings;

use Pixielity\Settings\Attributes\Setting;
use Spatie\LaravelSettings\Settings;

#[Setting(group: 'general', repository: 'database')]
class GeneralSettings extends Settings
{
    public string $site_name;
    public bool $site_active;

    public static function group(): string
    {
        return 'general';
    }
}

2. Create Migration

php artisan make:settings-migration CreateGeneralSettings

public function up(): void
{
    $this->migrator->add('general.site_name', 'My Site');
    $this->migrator->add('general.site_active', true);
}

3. Run Migration

php artisan migrate

4. Use Settings

// Via helper - fluent API
$siteName = settings('general')->string('site_name');
$isActive = settings('general')->bool('site_active');

// Via helper - direct access
$siteName = settings('general', 'site_name');
$siteName = settings('general', 'site_name', 'Default');

// Via dependency injection
public function __construct(GeneralSettings $settings) {
    echo $settings->site_name;
}

// Update settings
settings('general')
    ->set('site_name', 'New Name')
    ->set('site_active', true)
    ->save();

Usage

Fluent API

The fluent API provides type-safe methods for accessing settings:

$general = settings('general');

// Type-safe getters
$siteName = $general->string('site_name');
$isActive = $general->bool('site_active');
$maxUsers = $general->int('max_users');
$price = $general->float('price');
$tags = $general->array('tags');

// With defaults
$siteName = $general->string('site_name', 'Default Site');
$isActive = $general->bool('site_active', true);

// Direct property access
echo $general->site_name;
$general->site_name = 'New Name';

Updating Settings

// Single update
settings('general')->set('site_name', 'New Name')->save();

// Multiple updates
settings('general')
    ->set('site_name', 'New Name')
    ->set('site_active', true)
    ->save();

// Via service
$service = settings();
$service->set('general', 'site_name', 'New Name');
$service->save('general');

Locking Settings

// Lock a setting
settings('general')->lock('site_name');

// Unlock a setting
settings('general')->unlock('site_name');

// Check if locked
if (settings('general')->isLocked('site_name')) {
    // Setting is locked
}

Refreshing Settings

// Refresh from repository (discard unsaved changes)
settings('general')->refresh();

Getting All Settings

// Get all settings as array
$allSettings = settings('general')->toArray();

// Via service
$allSettings = settings()->all('general');

API Endpoints

The package provides RESTful API endpoints for managing settings:

List All Groups

GET /api/v1/settings

Get Settings for a Group

GET /api/v1/settings/{group}

Get Specific Setting

GET /api/v1/settings/{group}/{key}

Update Settings for a Group

PUT /api/v1/settings/{group}
Content-Type: application/json

{
  "settings": {
    "site_name": "New Name",
    "site_active": true
  }
}

Update Specific Setting

PUT /api/v1/settings/{group}/{key}
Content-Type: application/json

{
  "value": "New Value"
}

Lock a Setting

POST /api/v1/settings/{group}/{key}/lock

Unlock a Setting

DELETE /api/v1/settings/{group}/{key}/lock

Refresh Settings

POST /api/v1/settings/{group}/refresh

Architecture

Service Layer

SettingsService provides business logic and orchestrates operations:

use Pixielity\Settings\Contracts\SettingsServiceInterface;

public function __construct(SettingsServiceInterface $settings) {
    $this->settings = $settings;
}

Repository Layer

SettingsRepository handles data access and persistence:

use Pixielity\Settings\Contracts\SettingsRepositoryInterface;

public function __construct(SettingsRepositoryInterface $repository) {
    $this->repository = $repository;
}

Discovery

Settings classes are automatically discovered via the #[Setting] attribute:

#[Setting(group: 'general', repository: 'database')]
class GeneralSettings extends Settings { }

Advanced Usage

Custom Repository

#[Setting(group: 'cache', repository: 'redis')]
class CacheSettings extends Settings
{
    public string $driver;
    public int $ttl;

    public static function group(): string
    {
        return 'cache';
    }

    public static function repository(): string
    {
        return 'redis';
    }
}

Encrypted Settings

class ApiSettings extends Settings
{
    public string $api_key;
    public string $api_secret;

    public static function group(): string
    {
        return 'api';
    }

    public static function encrypted(): array
    {
        return ['api_key', 'api_secret'];
    }
}

Custom Casts

use Spatie\LaravelSettings\SettingsCasts\DateTimeInterfaceCast;

class DateSettings extends Settings
{
    public DateTime $created_at;

    public static function group(): string
    {
        return 'dates';
    }

    public static function casts(): array
    {
        return [
            'created_at' => DateTimeInterfaceCast::class,
        ];
    }
}

Testing

use Pixielity\Settings\Tests\Settings\GeneralSettings;

// Fake settings for testing
GeneralSettings::fake([
    'site_name' => 'Test Site',
    'site_active' => true,
]);

// Now all code using GeneralSettings will use these values

Configuration

Settings are configured via config/settings.php. The package automatically discovers settings classes, but you can also manually register them:

'settings' => [
    App\Settings\GeneralSettings::class,
    App\Settings\MailSettings::class,
],

Credits

Built on top of Spatie Laravel Settings.

License

MIT

pixielity / laravel-settings

Maintainers

Details