PHPackages                             litepie/settings - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. litepie/settings

ActiveLibrary[Utility & Helpers](/categories/utility)

litepie/settings
================

A comprehensive multi-level settings management package for Laravel

v1.0.2(8mo ago)0143MITJavaScriptPHP ^8.2

Since Aug 21Pushed 8mo agoCompare

[ Source](https://github.com/Litepie/Settings)[ Packagist](https://packagist.org/packages/litepie/settings)[ Docs](https://github.com/litepie/settings)[ RSS](/packages/litepie-settings/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (4)Versions (4)Used By (0)

Litepie Settings Package
========================

[](#litepie-settings-package)

A comprehensive, enterprise-grade multi-level settings management package for Laravel applications. This package provides a robust and flexible solution for managing application, user, company, and global settings with advanced features like encryption, caching, audit trails, and permissions.

✅ Laravel 12 Ready
------------------

[](#-laravel-12-ready)

This package is fully compatible with **Laravel 12** and includes:

- **PHP 8.2+ Support** with modern type declarations
- **Updated Dependencies** for Laravel 12 compatibility
- **Enhanced Type Safety** with proper return types and parameter hints
- **Modern Laravel Features** including constructor property promotion

Requirements
------------

[](#requirements)

- **PHP**: ^8.2
- **Laravel**: ^10.0|^11.0|^12.0
- **spatie/laravel-permission**: ^6.0

✨ Features
----------

[](#-features)

### Core Features

[](#core-features)

- **🏗️ Multi-level Settings Hierarchy**: Global, company, team, role, and user-specific settings with inheritance
- **🔧 8 Built-in Data Types**: String, integer, float, boolean, array, JSON, encrypted, and file types
- **⚡ Performance Optimized**: Built-in Redis/Memcached caching with configurable TTL
- **🔐 Security First**: Encrypted settings support with Laravel's encryption
- **👥 Multi-tenant Ready**: Polymorphic owner relationships for any model
- **📊 Audit Trail**: Complete history tracking of all setting changes
- **🎯 Grouped Settings**: Organize settings into logical groups (appearance, notifications, etc.)
- **🔒 Permission System**: Granular access control for setting management

### Advanced Features

[](#advanced-features)

- **📤 Import/Export**: JSON backup and restore with selective group support
- **🌐 RESTful API**: Complete REST API with authentication and rate limiting
- **📱 Frontend Ready**: API resources and validation for frontend integration
- **🎭 Dependency System**: Settings that depend on other settings
- **🔍 Validation**: Custom validation rules per setting
- **📄 Templates**: Pre-defined setting templates for quick setup
- **🔄 Real-time Events**: Laravel events for setting CRUD operations
- **🏷️ Metadata Support**: Additional data storage for settings
- **🌍 Public/Private**: Control visibility of settings

📦 Installation
--------------

[](#-installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require litepie/settings
```

### Step 2: Install and Setup

[](#step-2-install-and-setup)

```
# Install the package (publishes config, runs migrations, seeds default groups)
php artisan settings:install

# Or run steps manually:
php artisan vendor:publish --provider="Litepie\Settings\Providers\SettingsServiceProvider"
php artisan migrate
php artisan settings:seed
```

### Step 3: Configure (Optional)

[](#step-3-configure-optional)

The package works out of the box, but you can customize behavior by publishing the config:

```
php artisan vendor:publish --provider="Litepie\Settings\Providers\SettingsServiceProvider" --tag="settings-config"
```

🎨 Frontend UI Components
------------------------

[](#-frontend-ui-components)

Ready-to-use UI components for managing settings in your frontend applications:

📋 **[UI Components Documentation](UI_COMPONENTS_README.md)** - Complete frontend implementation guide

Available for multiple frameworks:

- **Vue.js 3** (Composition API) - Modern reactive components
- **React 18** (Hooks) - Latest React patterns with custom hooks
- **Flutter** (Material Design) - Native mobile apps with Material Design
- **React Native** (Cross-platform) - Mobile apps for iOS and Android

Features include real-time search, group filtering, validation, import/export, and responsive design across all platforms.

🚀 Quick Start
-------------

[](#-quick-start)

### Using the Facade

[](#using-the-facade)

```
use Litepie\Settings\Facades\Settings;

// Set a global setting
Settings::set('app_name', 'My Application');

// Get a setting with default value
$appName = Settings::get('app_name', 'Default App');

// Set user-specific setting
Settings::set('theme', 'dark', $user);

// Get user setting with fallback to global
$theme = Settings::get('theme', 'light', $user);

// Check if setting exists
if (Settings::has('maintenance_mode')) {
    // Setting exists
}

// Delete a setting
Settings::forget('old_setting');
```

### Using the Helper Function

[](#using-the-helper-function)

```
// Get setting with default
$value = settings('app_name', 'Default App');

// Get setting for specific owner
$userTheme = settings('theme', 'light', $user);

// Get the settings service instance
$settingsService = settings();

// Set setting using service
settings()->set('new_setting', 'value');
```

### Using the HasSettings Trait

[](#using-the-hassettings-trait)

Add the `HasSettings` trait to any Eloquent model:

```
use Litepie\Settings\Traits\HasSettings;

class User extends Model
{
    use HasSettings;
}

class Company extends Model
{
    use HasSettings;
}

// Now you can use these methods:
$user->setSetting('preference', 'value');
$preference = $user->getSetting('preference', 'default');
$user->forgetSetting('old_preference');

// Get all settings for the user
$allSettings = $user->getAllSettings();

// Get settings by group
$notifications = $user->getSettingsByGroup('notifications');

// Set multiple settings at once
$user->setMultipleSettings([
    'theme' => 'dark',
    'language' => 'en',
    'timezone' => 'UTC'
]);
```

🔧 Advanced Usage
----------------

[](#-advanced-usage)

### Setting Types and Validation

[](#setting-types-and-validation)

The package supports 8 built-in data types with automatic casting:

```
// String (default)
Settings::set('app_name', 'My App');

// Integer
Settings::set('max_users', 100, null, ['type' => 'integer']);

// Float/Decimal
Settings::set('tax_rate', 7.25, null, ['type' => 'float']);

// Boolean
Settings::set('maintenance_mode', false, null, ['type' => 'boolean']);

// Array
Settings::set('allowed_domains', ['example.com', 'test.com'], null, ['type' => 'array']);

// JSON (for complex objects)
Settings::set('api_config', ['key' => 'value', 'timeout' => 30], null, ['type' => 'json']);

// Encrypted (automatically encrypted/decrypted)
Settings::set('api_secret', 'secret-key', null, ['type' => 'encrypted']);

// File paths
Settings::set('logo_path', '/uploads/logo.png', null, ['type' => 'file']);
```

### Groups and Organization

[](#groups-and-organization)

Organize settings into logical groups for better management:

```
// Set setting with group and metadata
Settings::set('logo', 'logo.png', $company, [
    'group_id' => 1, // appearance group
    'description' => 'Company logo displayed in header',
    'type' => 'file',
    'is_public' => true,
    'validation_rules' => ['required', 'string'],
    'default_value' => 'default-logo.png',
    'order' => 1,
    'metadata' => ['max_size' => '2MB', 'formats' => ['jpg', 'png']]
]);

// Get settings by group
$appearanceSettings = Settings::getByGroup('appearance', $company);

// Get all available groups
$groups = app(\Litepie\Settings\Models\SettingGroup::class)->active()->get();
```

### Bulk Operations

[](#bulk-operations)

Efficiently handle multiple settings:

```
// Set multiple settings at once
Settings::setMultiple([
    'site_name' => 'My Website',
    'site_description' => 'A great website',
    'contact_email' => 'contact@example.com',
    'max_upload_size' => 10485760, // 10MB
], $user);

// Get multiple settings with defaults
$settings = Settings::getMultiple([
    'site_name' => 'Default Site',
    'contact_email' => 'admin@example.com',
    'theme' => 'light'
], $user);

// Get all settings for an owner
$allUserSettings = Settings::all($user);
$allGlobalSettings = Settings::all(); // null = global
```

### Setting Dependencies

[](#setting-dependencies)

Create settings that depend on other settings:

```
Settings::set('email_notifications', true, $user, [
    'type' => 'boolean',
    'depends_on' => ['notifications_enabled' => true]
]);

// This setting will only be available if notifications_enabled is true
```

### Caching Control

[](#caching-control)

The package automatically caches settings, but you can control caching behavior:

```
// Clear specific setting cache
Settings::clearCache('app_name', $user);

// Clear all cache
Settings::clearCache();

// Temporarily disable caching
config(['settings.cache.enabled' => false]);
Settings::set('temp_setting', 'value');
config(['settings.cache.enabled' => true]);
```

🌐 RESTful API
-------------

[](#-restful-api)

The package provides a complete REST API for managing settings:

### API Endpoints

[](#api-endpoints)

```
GET    /api/settings                    # List all settings
GET    /api/settings?group=appearance   # Filter by group
GET    /api/settings?owner_type=App\Models\User&owner_id=1  # Filter by owner
POST   /api/settings                    # Create new setting
GET    /api/settings/{key}              # Get specific setting
PUT    /api/settings/{key}              # Update setting
DELETE /api/settings/{key}              # Delete setting
POST   /api/settings/bulk               # Bulk update settings

```

### API Usage Examples

[](#api-usage-examples)

```
# Get all settings
curl -H "Authorization: Bearer {token}" \
     http://your-app.com/api/settings

# Get specific setting
curl -H "Authorization: Bearer {token}" \
     http://your-app.com/api/settings/app_name

# Create setting
curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{"key":"new_setting","value":"new_value","type":"string"}' \
     http://your-app.com/api/settings

# Update setting
curl -X PUT \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{"value":"updated_value"}' \
     http://your-app.com/api/settings/app_name

# Bulk update
curl -X POST \
     -H "Authorization: Bearer {token}" \
     -H "Content-Type: application/json" \
     -d '{"settings":{"setting1":"value1","setting2":"value2"}}' \
     http://your-app.com/api/settings/bulk
```

### API Configuration

[](#api-configuration)

Customize API behavior in config:

```
'api' => [
    'prefix' => 'api/settings',
    'middleware' => ['auth:sanctum', 'throttle:60,1'],
    'rate_limit' => '60:1',
],
```

⚡ Artisan Commands
------------------

[](#-artisan-commands)

The package includes powerful CLI commands for managing settings:

### Installation and Setup

[](#installation-and-setup)

```
# Complete package installation (recommended)
php artisan settings:install

# Seed default setting groups
php artisan settings:seed
```

### Import/Export Operations

[](#importexport-operations)

```
# Export all settings to JSON
php artisan settings:export --file=backup.json

# Export specific owner's settings
php artisan settings:export --file=user-settings.json \
    --owner-type="App\Models\User" --owner-id=1

# Export specific groups only
php artisan settings:export --file=appearance.json \
    --groups=appearance --groups=notifications

# Import settings from file
php artisan settings:import backup.json

# Import with overwrite existing settings
php artisan settings:import backup.json --overwrite

# Import for specific owner
php artisan settings:import user-settings.json \
    --owner-type="App\Models\User" --owner-id=1
```

### Cache Management

[](#cache-management)

```
# Clear settings cache
php artisan settings:cache:clear

# You can also use Laravel's cache commands
php artisan cache:forget settings:*
```

### Command Options

[](#command-options)

CommandOptionDescription`export``--file`Output file path (default: settings.json)`export``--owner-type`Class name of owner model`export``--owner-id`ID of owner instance`export``--groups`Array of group keys to export`import``--overwrite`Overwrite existing settings`import``--owner-type`Import for specific owner type`import``--owner-id`Import for specific owner ID⚙️ Configuration
----------------

[](#️-configuration)

### Complete Configuration Reference

[](#complete-configuration-reference)

Publish the config file for full customization:

```
php artisan vendor:publish --provider="Litepie\Settings\Providers\SettingsServiceProvider" --tag="settings-config"
```

### Key Configuration Options

[](#key-configuration-options)

```