README

使用 turkialawlqy/laravel-app-settings 在您的 Laravel 应用程序中添加具有用户界面的设置管理器。它将设置存储在数据库中，默认使用 Bootstrap 4 进行样式化，但您可以配置它以与任何 CSS 系统一起使用。

所有保存在数据库中的设置都通过将 SQL 查询减少到零来提高性能进行缓存。

安装

1 - 您可以通过 composer 安装此包

$ composer require turkialawlqy/laravel-app-settings

2 - 如果您正在安装 Laravel 5.4 或更低版本，您需要手动通过在 config/app.php 提供商数组中添加它来注册 Service Provider，并在别名数组中添加 Facade。

'providers' => [
    //...
    turkialawlqy\AppSettings\AppSettingsServiceProvider::class,
]

'aliases' => [
    //...
    "AppSettings" => turkialawlqy\AppSettings\Facade::class
]

在 Laravel 5.5 或更高版本中，服务提供程序会自动注册，并将提供 AppSettings::get('app_name') 的 facade。

3 - 现在，您应该使用以下命令发布配置文件：

php artisan vendor:publish --provider="turkialawlqy\AppSettings\AppSettingsServiceProvider" --tag="config"

它将创建 config/app_settings.php，其中包含所有配置选项和定义您的设置输入的方法，分为几个部分。

4 - 现在，通过运行 php artisan migrate 来运行迁移以创建设置表。

入门

首先，您需要定义您在设置页面上想要的所有设置。例如，我们将需要这些设置 app_name、from_email 和 from_name。让我们在配置中定义它

config/app_settings.php

<?php

[
    //...
    // All the sections for the settings page
    'sections' => [

        'app' => [
            'title' => 'General Settings',
            'descriptions' => 'Application general settings.', // (optional)
            'icon' => 'fa fa-cog', // (optional)

            'inputs' => [
                [
                    'name' => 'app_name', // unique key for setting
                    'type' => 'text', // type of input can be text, number, textarea, select, boolean, checkbox etc.
                    'label' => 'App Name', // label for input
                    // optional properties
                    'placeholder' => 'Application Name', // placeholder for input
                    'class' => 'form-control', // override global input_class
                    'style' => '', // any inline styles
                    'rules' => 'required|min:2|max:20', // validation rules for this input
                    'value' => 'turkie', // any default value
                    'hint' => 'You can set the app name here' // help block text for input
                ]
            ]
        ],
        'email' => [
            'title' => 'Email Settings',
            'descriptions' => 'How app email will be sent.',
            'icon' => 'fa fa-email',

            'inputs' => [
                [
                    'name' => 'from_email',
                    'type' => 'email',
                    'label' => 'From Email',
                    'placeholder' => 'Application from email',
                    'rules' => 'required|email',
                ],
                [
                 'name' => 'from_name',
                 'type' => 'text',
                 'label' => 'Email from Name',
                 'placeholder' => 'Email from Name',
                ]
            ]
        ]
    ]
];

现在，如果您访问 http://yourapp.com/settings 路由，您将获得包含您定义的所有设置的 UI。

您可以通过更改 app_settings 配置来更改布局以适应您的应用程序设计。

// View settings
'setting_page_view' => 'your_setting', // blade view path

接下来，打开 resources/views/your_setting.blade.php 并将设置部分包含到您想要显示设置的地方。

@extends('layout')

@section('content')
    @include('app_settings::_settings')
@endsection

现在，您应该看到设置页面作为您应用程序的一部分，并且与您的布局一起😎。

访问已保存的设置

您有 setting('app_name', 'default value') 和 Facade AppSettings::get('app_name', 'default value')，您可以使用它们来获取存储的设置。

更改设置 URL

如果您的应用程序需要不同的 URL 来访问设置页面，您可以在配置中更改它

// Setting page url, will be used for get and post request
'url' => 'app-settings',
// http://yourapp.com/app-settings

使用组设置

很多时候，您希望将设置存储在组中。从版本 1.1 开始，您可以从 config/app_settings.php 中定义一个组名称。您有一个更接近返回字符串的组名称的方法

return [

    // All the sections for the settings page
    'sections' => [...]
    
    ...
    // settings group
    'setting_group' => function() {
        return 'user_'.auth()->id();
    }

在这种情况下，您可以针对每个用户有不同的设置。

不使用 UI

如果您只想将键值对存储到数据库中，并且不想使用 UI 来管理设置（例如，在 API 中），那么您应该使用 turkialawlqy/laravel-settings 包。此包在下面使用它来持久化设置。

如果您想同时使用 UI 和将设置作为键值对存储在数据库中，请简单地使用辅助函数 setting() 或 AppSetting::get('app_name') 来存储和检索数据库中的设置。为此，您不需要在 app_settings.php 配置中定义任何部分和输入。

当同时使用 UI 和将设置作为键值对时，请确保在 config/app_settings.php 中设置 'remove_abandoned_settings' => false，否则，在从 UI 保存设置时，任何未定义的输入字段将被删除。

以下是可用方法列表

setting()->all($fresh = false);
setting()->get($key, $defautl = null);
setting()->set($key, $value);
setting()->has($key);
setting()->remove($key);

在 JavaScript 中访问设置

很多时候，这些设置需要从您的 JavaScript 中访问。一种方法是只需将其放在您的布局 blade 模板中作为全局变量即可。

// layout.blade.php
<head>
<title>@yield('title', 'Settings')</title>
<script>
    window.App = {!! json_encode([
            'settings' => \setting()->all(),
            'anyOtherThings' => []
    ]); !!}
</script>
</head>

使用此功能，您将能够访问Vue组件或任何JavaScript代码中定义的设置。

App.settings.app_name;

// or define a computed property on Component root level
const app = new Vue({
  el: "#app",
  computed: {
    myApp() {
      return window.App;
    }
  }
});

// access it like this
myApp.settings.app_name;

输入类型

以下是您可以定义的所有输入类型及其属性，但如果有需要，您也可以添加自己的自定义输入类型。

每个输入都必须至少包含name、type和label属性。

文本、数字、电子邮件

这些类型在本质上相同，只是类型有所改变，并且数字类型有min和max属性。

// text
[
    'name' => 'app_name',
    'type' => 'text',
    'label' => 'App Name',
    // optional fields
    'data_type' => 'string',
    'rules' => 'required|min:2|max:20',
    'placeholder' => 'Application Name',
    'class' => 'form-control',
    'style' => 'color:red',
    'value' => 'turkie',
    'hint' => 'You can set the app name here'
],

// number
[
    'name' => 'users_allowed',
    'type' => 'number',
    'label' => 'Number of users allowed',
    // optional fields
    'data_type' => 'int',
    'min' => 5,
    'max' => 100,
    'rules' => 'required|min:5|max:100',
    'placeholder' => 'Number of users allowed',
    'class' => 'form-control',
    'style' => 'color:red',
    'value' => 5,
    'hint' => 'You can set the number of users allowed to be added.'
]

// email
[
    'name' => 'from_email',
    'type' => 'email',
    'label' => 'From Email',
    // optional fields
    'rules' => 'required|email',
    'placeholder' => 'Emails will be sent from this address',
    'class' => 'form-control',
    'style' => 'color:red',
    'value' => 'noreply@example.com',
    'hint' => 'All the system generated email will be sent from this address.'
]

'data_type'可以用于转换输入数据，可以是array、int|integer|number、boolean|bool和string。如果您需要其他类型，您始终可以使用访问器来实现。

文本区域

文本区域字段与文本相同，但它有rows和cols属性。

[
    'type' => 'textarea',
    'name' => 'maintenance_note',
    'label' => 'Maintenance note',
    'rows' => 4,
    'cols' => 10,
    'placeholder' => 'What you want user to show when app is in maintenance mode.'
],

选择框

可以使用选项定义选择框

[
    'type' => 'select',
    'name' => 'date_format',
    'label' => 'Date format',
    'rules' => 'required',
    'options' => [
        'm/d/Y' => date('m/d/Y'),
        'm.d.y' => date("m.d.y"),
        'j, n, Y' => date("j, n, Y"),
        'M j, Y' => date("M j, Y"),
        'D, M j, Y' => date('D, M j, Y')
    ]
],

从数据库中选择选项

您还可以动态地填充选择框选项。在大多数情况下，这些选项将来自数据库，只需使用闭包（匿名函数）即可。

[
    'type' => 'select',
    'name' => 'city',
    'label' => 'City',
    'rules' => 'required',
    'options' => function() {
        return App\City::pluck('name', 'id')->toArray()
    }
],

注意：如果您需要动态解析字段值，则可以在输入的大部分字段上使用闭包（匿名函数）。

布尔值

布尔值只是一个带有是或否选项的无线电输入组，您也可以通过设置options数组将其更改为选择框。

// as radio inputs
[
    'name' => 'maintenance_mode',
    'type' => 'boolean',
    'label' => 'Maintenance',
    'value' => false,
    'class' => 'w-auto',
    // optional fields
    'true_value' => 'on',
    'false_value' => 'off',
],
// as select options
[
    'name' => 'maintenance_mode',
    'type' => 'boolean',
    'label' => 'Maintenance',
    'value' => false,
    'class' => 'w-auto',
    // optional fields
    'options' => [
        '1' => 'Yes',
        '0' => 'No',
    ],
],

复选框

添加复选框输入

[
    'type' => 'checkbox',
    'label' => 'Try Guessing user locals',
    'name' => 'guess_local',
    'value' => '1'
]

复选框组

添加一组复选框

[
    'type' => 'checkbox_group',
    'label' => 'Days to run scheduler',
    'name' => 'scheduler_days',
    'data_type' => 'array', // required
    'options' => [
        'Sunday', 'Monday', 'Tuesday'
    ]
]

图片、文件

您可以使用image和file输入来上传文件。文件上传将被自动处理，旧文件将被新文件替换。

如果您在输入上定义了mutator，那么上传处理将由您来处理，您必须从mutator返回上传文件的路径以存储在设置中并处理旧文件。

您在大多数情况下不需要使用mutator。

您可以为传入的文件定义rules以进行验证，它可以是图片或任何文档。

[
    'name' => 'logo',
    'type' => 'image',
    'label' => 'Upload logo',
    'hint' => 'Must be an image and cropped in desired size',
    'rules' => 'image|max:500',
    'disk' => 'public', // which disk you want to upload, default to 'public'
    'path' => 'app', // path on the disk, default to '/',
    'preview_class' => 'thumbnail', // class for preview of uploaded image
    'preview_style' => 'height:40px' // style for preview
]

// handle uploads by yourself using `mutator`
[
    'name' => 'logo',
    'type' => 'image',
    'label' => 'Upload logo',
    'hint' => 'Must be an image and cropped in desired size',
    'rules' => 'image|max:500',

    // a simple mutator
    'mutator' => function($value, $key) {
        // handle image do some reszing etc
        $image = Intervention\Image::make(request()->file($key));

        $path = Storage::disk('public')->put(
            $imagePath,
            (string) $image->encode(null, $imageQuality),
            'public'
        );

        // delete old image etc
        Storage::disk('public')->delete(\setting($key));

        // finally return new path to be stored in db
        return $path;
    }
]

不使用Bootstrap 4

如果您应用不使用Twitter Bootstrap 4，您可以通过在app_settings.php中进行自定义来轻松地遵循您的CSS库，如Bulma、Foundatio CSS或其他任何自定义解决方案。

// Setting section class setting
'section_class' => 'card mb-3',
'section_heading_class' => 'card-header',
'section_body_class' => 'card-body',

// Input wrapper and group class setting
'input_wrapper_class' => 'form-group',
'input_class' => 'form-control',
'input_error_class' => 'has-error',
'input_invalid_class' => 'is-invalid',
'input_hint_class' => 'form-text text-muted',
'input_error_feedback_class' => 'text-danger',

// Submit button
'submit_btn_text' => 'Save Settings',
'submit_success_message' => 'Settings has been saved.',

自定义应用设置视图

在某些情况下，如果您的应用需要自定义视图，您可以将应用设置视图发布出来，然后您就可以自定义设置字段的所有部分。

php artisan vendor:publish --provider="turkialawlqy\AppSettings\AppSettingsServiceProvider" --tag="views"

自定义输入类型

尽管此包包含您需要的所有输入，但如果您需要包含在此包之外的某些功能，您只需在应用设置部分中定义一个输入并给它一个自定义类型即可，例如type="daterange"日期范围字段。接下来，您需要发布视图，并在resources/views/vendor/app_settings/fields/文件夹中添加一个blade视图，并确保其名称与字段名称匹配，如daterange.blade.php。

@component('app_settings::input_group', compact('field'))
<div class="row">
    <div class="col-md-6">
        <label>
            From
            <input
                type="date"
                name="from_{{ $field['name'] }}"
                class="{{ array_get( $field, 'class', config('app_settings.input_class', 'form-control')) }}"
                value="{{ old('from_'.$field['name'], array_get(\setting('from_'.$field['name']), 'from')) }}"
            >
        </label>
    </div>
    <div class="col-md-6">
        <label>
            To
            <input
                type="date"
                name="to_{{ $field['name'] }}"
                class="{{ array_get( $field, 'class', config('app_settings.input_class', 'form-control')) }}"
                value="{{ old('to_'.$field['name'], array_get(\setting($field['name']), 'to')) }}"
            >
        </label>
    </div>
</div>
@endcomponent

@component('app_settings::input_group', compact('field'))将添加label和hint以及error反馈文本。

要使用此自定义输入，您应该在app_settings.php中定义它，如下所示

<?php
[
    'name' => 'registration_allowed',
    'type' => 'daterange',
    'label' => 'Registration Allowed',
    'hint' => 'A date range when registration is allowed',
    'mutator' => function($value, $key) {
        // combine both from_registration_allowed and to_registration_allowed
        $rangeValues = [
            'from' => request('from_registration_allowed'),
            'to' => request('to_registration_allowed'),
        ];

        return json_encode($rangeValues);
    },
    'accessor' => function($value, $key) {
        return is_null($value) ? ['from' => '', 'to' => ''] : json_decode($value, true);
    },
]

这将渲染日期范围字段。您可以使用此方法创建任何类型的字段。

访问器和修改器

就像Eloquent模型一样，它允许您在输入上定义访问器和修改器，这在创建自定义输入时非常有用。

访问器

访问器可以在访问时更改设置值，它可以是一个Closer或具有handle($value, $key)方法的类。

<?php
// app settings input
[
    'name' => 'app_name',
    'type' => 'text',
    'accessor' => '\App\Accessors\AppNameAccessor'
];

// use a class
class AppNameAccessor {
    public function handle($value, $key) {
        return ucfirst($value);
    }
}

// or you can use Closer
[
    'name' => 'app_name',
    'type' => 'text',
    'accessor' => function($value, $key) {
        return ucfirst($value);
    }
];

修改器

修改器可以在存储到数据库之前更改设置值，与访问器类似，它也可以是一个Closer或具有handle($value, $key)方法的类。

<?php
// app settings input
[
    'name' => 'app_name',
    'type' => 'text',
    'mutator' => '\App\Mutators\AppNameMutator'
];

// use a class
class AppNameMutator {
    public function handle($value, $key) {
        return ucfirst($value). ' Inc.';
    }
}

// or you can use Closer
[
    'name' => 'app_name',
    'type' => 'text',
    'mutator' => function($value, $key) {
        return ucfirst($value). ' Inc.';
    }
];

使用不同的控制器

为了使用您的控制器来显示和存储设置，您可以更改app_settings.controller。

// change the controller in config/app_settings.php at the bottom

// Controller to show and handle save setting
'controller' => '\App\Http\Controllers\SettingsController',

确保您的控制器中包含index()和store(Request $request)方法。

// Controller
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use turkialawlqy\AppSettings\SavesSettings;
use App\Http\Controllers\Controller;

class SettingsController extends Controller 
{ 
    use SavesSettings;
    
    // you can override following methods from trait
    
    // to display the settings view
    public function index()
    {
       return 'I am settings page'.
    }
    
    // to store settings changes
    public function store(Request $request)
    {
       return $request->all().
    }
}

配置文件

<?php
return [

    // All the sections for the settings page
    'sections' => [
        'app' => [
            'title' => 'General Settings',
            'descriptions' => 'Application general settings.', // (optional)
            'icon' => 'fa fa-cog', // (optional)

            'inputs' => [
                [
                    'name' => 'app_name', // unique key for setting
                    'type' => 'text', // type of input can be text, number, textarea, select, boolean, checkbox etc.
                    'label' => 'App Name', // label for input
                    // optional properties
                    'placeholder' => 'Application Name', // placeholder for input
                    'class' => 'form-control', // override global input_class
                    'style' => '', // any inline styles
                    'rules' => 'required|min:2|max:20', // validation rules for this input
                    'value' => 'turkie', // any default value
                    'hint' => 'You can set the app name here' // help block text for input
                ]
            ]
        ],
        'email' => [
            'title' => 'Email Settings',
            'descriptions' => 'How app email will be sent.',
            'icon' => 'fa fa-envelope',

            'inputs' => [
                [
                    'name' => 'from_email',
                    'type' => 'email',
                    'label' => 'From Email',
                    'placeholder' => 'Application from email',
                    'rules' => 'required|email',
                ],
                [
                    'name' => 'from_name',
                    'type' => 'text',
                    'label' => 'Email from Name',
                    'placeholder' => 'Email from Name',
                ]
            ]
        ]
    ],

    // Setting page url, will be used for get and post request
    'url' => 'settings',

    // Any middleware you want to run on above route
    'middleware' => [],

    // View settings
    'setting_page_view' => 'app_settings::settings_page',
    'flash_partial' => 'app_settings::_flash',

    // Setting section class setting
    'section_class' => 'card mb-3',
    'section_heading_class' => 'card-header',
    'section_body_class' => 'card-body',

    // Input wrapper and group class setting
    'input_wrapper_class' => 'form-group',
    'input_class' => 'form-control',
    'input_error_class' => 'has-error',
    'input_invalid_class' => 'is-invalid',
    'input_hint_class' => 'form-text text-muted',
    'input_error_feedback_class' => 'text-danger',

    // Submit button
    'submit_btn_text' => 'Save Settings',
    'submit_success_message' => 'Settings has been saved.',

    // Remove any setting which declaration removed later from sections
    'remove_abandoned_settings' => false,

    // Controller to show and handle save setting
    'controller' => '\turkialawlqy\AppSettings\Controllers\AppSettingController'
    
    // settings group
    'setting_group' => function() {
        // return 'user_'.auth()->id();
        return 'default';
    }
];

变更日志

请参阅变更日志以获取最近更改的更多信息。

测试

该包包含一些与Orchestra集成的/冒烟测试，可以通过phpunit运行这些测试。

$ composer test

贡献

请参阅贡献指南获取详细信息。

安全

如果您发现任何与安全相关的问题，请通过电子邮件saquibweb@gmail.com联系，而不是使用问题跟踪器。

鸣谢

Mohd turkialawlqy/ Ansari

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。

turkialawlqy / laravel-app-settings

维护者

详细信息