jamin87/laravel-sitesettings

Persistent site settings for Laravel

Persistent CMS style site settings for Laravel

, _(*1)

Support

This version supports Laravel 5.5 - 6 / PHP 7.2 and above., _(*2)

Installation

Install using Composer by running:, _(*3)

composer require BWibrew/laravel-sitesettings

Publish the config file with:, _(*4)

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

Publish the migrations with:, _(*5)

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

Then run table migrations with:, _(*6)

php artisan migrate

Configuring your models

Add the following interface, trait and $fillable attribute to your Setting model:, _(*7)

<?php

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 = [
        'name',
        'value',
        'updated_by',
    ];

    //
}

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

<?php

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 = [
        'name',
    ];

    //
}

File Uploads

To support the ability to save uploaded files as settings you also need to install the spatie/laravel-medialibrary package., _(*9)

composer require spatie/laravel-medialibrary

Full installation instructions can be found here., _(*10)

Here is the minimum set-up needed:, _(*11)

Publish the migration with:, _(*12)

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

Then run table migrations with:, _(*13)

php artisan migrate

Add a disk to app/config/filesystems.php. e.g:, _(*14)

    ...
    '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., _(*15)

Usage

This package provides a convenient API for using the settings with an existing Eloquent Model., _(*16)

Registering a new setting

A setting is created like this:, _(*17)

Setting::register('homepage_title');

You can also assign a value when creating a setting:, _(*18)

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

You can then retrieve the value of the setting:, _(*19)

Setting::getValue($name);

Updating a setting

To update an existing setting:, _(*20)

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

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

// Update setting name
$setting->updateName('new_name');

You can also retrieve the ID of the user whom last updated the setting and when the update was made., _(*21)

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., _(*22)

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., _(*23)

There are also a number of extra methods used with scopes:, _(*24)

// Return an array of all values from a scope
Setting::getScopeValues();

// Return the user ID of the user which last updated a setting in a scope
Setting::getScopeUpdatedBy();

// Return when the most recent update was made in a scope
Setting::getScopeUpdatedAt();

To update or remove a scope:, _(*25)

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

$setting->updateScope('new_scope_name');

$setting->removeScope();

Usage with file uploads

This package can make use of the amazing Spatie/MediaLibrary to provide the ability to associate settings with uploaded media., _(*26)

To use a file upload as a setting simply set the file upload as the setting value., _(*27)

Example:, _(*28)

$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., _(*29)

Configuration

Set use_scopes to false to disable the use of scopes., _(*30)

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

Testing

Run tests with:, _(*32)

composer test