qcod / laravel-app-settings

一个带有UI的包，用于存储和管理您应用程序的所有设置

维护者

详细信息

github.com/qcod/laravel-app-settings

主页

源代码

问题

安装量: 76,383

依赖者: 0

建议者: 0

安全: 0

星星: 333

关注者: 13

分支: 53

开放问题: 17

1.7.0 2024-05-15 01:36 UTC

Requires

Requires (Dev)

MIT a99688a6cc7ae249eefbb41470d504163933b17c

  • Mohd Saqueib Ansari <saquibweb.woop@gmail.com>

bootstraplaraveleloquentqcoddatabase settingsdb settingsapp settingssetting ui

This package is auto-updated.

Last update: 2024-09-15 02:19:32 UTC

README

Latest Version on Packagist Software License Build Status Total Downloads

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

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

安装

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

$ composer require qcod/laravel-app-settings

2 - 如果您正在安装Laravel 5.4或更低版本，您需要手动注册服务提供程序，通过将其添加到config/app.php中的提供商数组以及别名数组中的外观。

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

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

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

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

php artisan vendor:publish --provider="QCod\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' => 'QCode', // 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。

Laravel App 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')和外观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();
    }

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

🔥您还可以使用app('app-settings')->setStorageGroup('my-storage-group')在运行时设置设置组。

不使用UI

如果您只想将键值对存储到数据库中，而不想使用UI来管理设置（例如，在API中），则应使用qcod/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 属性。

text、number、email

这些实际上只是类型改变，并为数字类型添加了 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' => 'QCode',
    '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。如果您需要其他类型，您始终可以使用 访问器 来实现。

textarea

textarea 字段与 text 相同，但它具有 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.'
],

select

可以使用选项定义下拉框

[
    '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()
    }
],

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

boolean

布尔值只是一个带有是或否选项的单选输入组，您也可以通过设置 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',
    ],
],

checkbox

添加复选框输入

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

checkbox_group

添加一组复选框

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

image、file

您可以使用 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="QCod\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 反馈文本的 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 QCod\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' => 'QCode', // 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' => '\QCod\AppSettings\Controllers\AppSettingController'
    
    // settings group
    'setting_group' => function() {
        // return 'user_'.auth()->id();
        return 'default';
    }
];

变更日志

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

测试

该包包含一些集成/冒烟测试，使用Orchestra设置，可以通过phpunit运行这些测试。

$ composer test

贡献

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

安全

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

鸣谢

关于QCode.in

QCode.in (https://www.qcode.in) 是由Saqueib编写的一个博客，涵盖关于全栈Web开发的方方面面。

许可

MIT许可（MIT）。有关更多信息，请参阅许可文件。