README

Prosty pakiet do przechowywania ustawień key/value w bazie danych z obsługą per-user i opcache-friendly plikowym cache.

Instalacja

composer require stobys/laravel-settings

Opublikuj config i migrację:

php artisan vendor:publish --tag=settings-config
php artisan vendor:publish --tag=settings-migrations
php artisan migrate

Konfiguracja (config/settings.php)

return [
    'table'   => 'settings',           // nazwa tabeli w bazie
    'columns' => [
        'key'     => 'key',            // kolumna klucza
        'value'   => 'value',          // kolumna wartości
        'user_id' => 'user_id',        // kolumna user_id (null = globalne)
    ],

    // Czy pakiet ma przechowywać i przywracać oryginalny typ PHP?
    'cast_types'  => true,
    'columns_type' => 'type',          // kolumna przechowująca typ

    'cache' => [
        'enabled' => true,
        'path'    => storage_path('framework/settings.php'), // ścieżka pliku cache
    ],
];

Użycie

Facade

use stobys\LaravelSettings\Facades\Settings;

// --- Ustawienia globalne ---
Settings::set('app.name', 'HeRMeS');
Settings::set('maintenance', false);
Settings::set('max_participants', 30);
Settings::set('allowed_roles', ['admin', 'manager']);

$name = Settings::get('app.name');           // 'HeRMeS'
$flag = Settings::get('maintenance');        // false (bool, nie string '0')
$max  = Settings::get('max_participants');   // 30 (int)
$roles = Settings::get('allowed_roles');     // ['admin', 'manager'] (array)

Settings::has('app.name');       // true
Settings::forget('app.name');

// Wiele naraz
Settings::setMany([
    'theme'    => 'dark',
    'language' => 'pl',
]);

// Ustaw domyślną wartość (tylko jeśli klucz nie istnieje)
Settings::setDefault('theme', 'light');

// Wszystkie globalne ustawienia
$all = Settings::all(); // ['theme' => 'dark', 'language' => 'pl', ...]

Per-user

// Ustawienia dla konkretnego użytkownika
Settings::for(42)->set('theme', 'light');
Settings::for(42)->get('theme');             // 'light'

// Fallback: jeśli user nie ma własnego ustawienia, zwraca globalne
Settings::for(42)->get('language');          // zwróci globalne 'pl'

// Zalogowany użytkownik
Settings::forCurrentUser()->set('notifications', true);
$userSettings = Settings::forCurrentUser()->all();
// ['theme' => 'light', 'language' => 'pl', 'notifications' => true]
// ^-- globalne scalone z per-user; user nadpisuje globalne

// Usunięcie
Settings::for(42)->forget('theme');

Dependency Injection

use stobys\LaravelSettings\SettingsManager;

class TrainingController extends Controller
{
    public function __construct(private SettingsManager $settings) {}

    public function index()
    {
        $maxParticipants = $this->settings->get('training.max_participants', 20);
        $userTheme = $this->settings->for(auth()->id())->get('theme', 'light');
    }
}

Cache plikowy

Jak działa

Ustawienia są buforowane w pliku PHP (storage/framework/settings.php):

<?php
// Auto-generated by laravel-settings. DO NOT EDIT.
// Generated at: 2024-01-15 10:30:00

return [
    'global' => [
        'app.name' => 'HeRMeS',
        'theme'    => 'dark',
    ],
    'users' => [
        42 => ['theme' => 'light'],
        7  => ['language' => 'en'],
    ],
];

• Plik jest ładowany przez include – PHP kompiluje go i opcache trzyma w pamięci → zero zapytań do bazy przy każdym get().
• Przy każdym set() / forget() – plik jest atomowo nadpisywany (write do .tmp → rename).
• Przy pierwszym odczycie, jeśli plik nie istnieje, następuje automatyczny rebuild z bazy.

Zarządzanie cache

# Wyczyść cache (wymusi reload z bazy przy następnym odczycie)
php artisan settings:clear-cache

# Wyczyść i od razu przebuduj z bazy
php artisan settings:clear-cache --rebuild

// Z kodu
Settings::clearCache();

Ważne przy deploymencie: Dodaj php artisan settings:clear-cache do swojego pipeline'u (obok php artisan config:clear), aby po deploymencie cache nie zawierał starych wartości.

Typy wartości

Gdy cast_types = true (domyślnie), pakiet automatycznie serializuje i deserializuje typy PHP:

Struktura tabeli

CREATE TABLE settings (
    id         BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    `key`      VARCHAR(255) NOT NULL,
    `value`    TEXT,
    `type`     VARCHAR(10) DEFAULT 'string',
    user_id    BIGINT UNSIGNED NULL,
    created_at TIMESTAMP NULL,
    updated_at TIMESTAMP NULL,
    UNIQUE KEY settings_key_user_id_unique (`key`, user_id),
    INDEX settings_user_id_index (user_id)
);

Artisan

php artisan settings:clear-cache           # Wyczyść cache
php artisan settings:clear-cache --rebuild # Wyczyść i przebuduj z DB