Persistent site settings for Laravel

1.1.1 2019-11-24 19:55 UTC


Latest Version on Packagist CircleCI StyleCI Codacy grade Codacy coverage


This version supports Laravel 5.5 - 6 / PHP 7.2 and above.


Install using Composer by running:

composer require BWibrew/laravel-sitesettings

Publish the config file with:

php artisan vendor:publish --provider="BWibrew\SiteSettings\SiteSettingsServiceProvider" --tag="config"

Publish the migrations with:

php artisan vendor:publish --provider="BWibrew\SiteSettings\SiteSettingsServiceProvider" --tag="migrations"

Then run table migrations with:

php artisan migrate

Configuring your models

Add the following interface, trait and $fillable attribute to your Setting model:


namespace App;

use Illuminate\Database\Eloquent\Model;
use BWibrew\SiteSettings\Traits\ManagesSettings;
use BWibrew\SiteSettings\Interfaces\SettingInterface;

class Setting extends Model implements SettingInterface
    use ManagesSettings;
    protected $fillable = [

If using scopes then also add the following interface, trait and $fillable attribute to your Scope model:


namespace App;

use Illuminate\Database\Eloquent\Model;
use BWibrew\SiteSettings\Interfaces\ScopeInterface;
use BWibrew\SiteSettings\Traits\ManagesSettingScopes;

class Scope extends Model implements ScopeInterface
    use ManagesSettingScopes;
    protected $fillable = [

File Uploads

To support the ability to save uploaded files as settings you also need to install the spatie/laravel-medialibrary package.

composer require spatie/laravel-medialibrary

Full installation instructions can be found here.

Here is the minimum set-up needed:

Publish the migration with:

php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="migrations"

Then run table migrations with:

php artisan migrate

Add a disk to app/config/filesystems.php. e.g:

    'disks' => [

        'media' => [
            'driver' => 'local',
            'root'   => public_path().'/media',

Lastly, you will need to use SettingWithMediaInterface and ManagesSettingsWithMedia instead of SettingInterface and ManagesSettings on your Setting model.


This package provides a convenient API for using the settings with an existing Eloquent Model.

Registering a new setting

A setting is created like this:


You can also assign a value when creating a setting:

Setting::register('homepage_title', 'Laravel Site Settings');

You can then retrieve the value of the setting:


Updating a setting

To update an existing setting:

$setting = Setting::where('name', 'setting_name')->first();

// Update setting value
$setting->updateValue('A new title');

// Update setting name

You can also retrieve the ID of the user whom last updated the setting and when the update was made.

Setting::getUpdatedBy($name); // Returns user ID

Setting::getUpdatedAt($name); // Returns Carbon date object

Using scopes

You can categories your settings into 'scopes'. Scopes use a simple dot syntax on the setting name.

To assign or retrieve a setting in a scope, place the scope name in front of the setting name and separate them with a dot: scope_name.setting_name. This works the same way with all methods which take a setting name as a parameter.

There are also a number of extra methods used with scopes:

// Return an array of all values from a scope

// Return the user ID of the user which last updated a setting in a scope

// Return when the most recent update was made in a scope

To update or remove a scope:

$setting = Setting::where('name', 'setting_name')->first();



Usage with file uploads

This package can make use of the amazing Spatie/MediaLibrary to provide the ability to associate settings with uploaded media.

To use a file upload as a setting simply set the file upload as the setting value.


$file = $request->file('avatar');

$setting = Setting::register('avatar', $file);

The value returned on a file upload setting is a string controlled by the file_value_type config value.


Set use_scopes to false to disable the use of scopes.

The file_value_type setting controls the value stored in the settings table. This can be set to 'file_name', 'path' or 'url'.


Run tests with:

composer test