Package: settings

Source: api/packages/settings · imported version 0.2.6. The sections after the README are extracted from the code on every docs build.

README

Configuration management package

Purpose

This package can be used to register application config keys which can be then modified through API and/or Admin Panel.

Installation

• composer require ulams/settings
• php artisan migrate
• php artisan db:seed --class="Ulams\Settings\Database\Seeders\PermissionTableSeeder"
• optional: php artisan vendor:publish --tag=ulams_settings.config to publish config file

Dependencies

Usage

Configuration

Config file contains use_database option, which determines if Config should be written and loaded to database (if true), or config files should be overwritten (if false);

Registering config keys

Every package can register config keys by calling registerConfig static method from AdministrableConfig Facade in its own Package Service Provider register method.

use Ulams\Settings\Facades\AdministrableConfig;

public function register(){

    //...

    AdministrableConfig::registerConfig($key = 'config_file.config_key', $rules = ['required', 'string'], $public = true, $readonly = false);

}

When registering a configuration key you can:

• specify validation rules for values that can be stored (using any of rules available for Laravel validator)
• specify if key is public (so anonymous users can retrieve the value)
• specify if key is readonly (so it is returned by API but can not be changed using API)

Loading config

Config will be automatically loaded from database (if use_database config options is true). Otherwise, if overwriting config files is chosen, normal Laravel config loading mechanism is used.

Changing config

Ulams\Settings\Facades\AdministrableConfig facade can also be used to modify and retrieve values for registered config keys.

AdministrableConfig::setConfig(array $config); // sets config values for any registered config key in $config array, running validation rules
AdministrableConfig::getConfig(); // returns values for all registered config keys
AdministrableConfig::getPublicConfig(); // returns values for config keys registered with public: true

These methods are utilised by web API of this package.

Config Repository Extension & Config Rewriter

This package extends basic config Facade of Laravel Framework wrapping it in Ulams\Settings\ConfigRewriter\ConfigRepositoryExtension decorator. This extended Config repository has a write method that can be called to store all in-memory changes to configuration values straight into config files. Writing operation tries to preserve structure of original config files (order of keys, comments, etc.) but it’s not always possible (parses this package uses is WIP) and sometimes everything other than keys and values can be removed from config file. Using Database to store modified config values is a safer (non-destructive) option.

Endpoints

All the endpoints are defined in .

Events

• Ulams\Settings\Events\SettingPackageConfigUpdated emitted when settings are changed using web API.

Listeners

No Listeners are defined in this package.

How to use this package on Frontend

Admin Panel

Left menu

List of registered Settings for single package (Ulams\Auth package used in screenshot)

Editing registered Setting

Tests

Run ./vendor/bin/phpunit --filter 'Ulams\\Settings\\Tests' to run tests. See tests folder as it’s quite good staring point as documentation appendix.

Test details:

Permissions

Permissions are defined in Enum and seeded in Seeder.

Roadmap. Todo. Troubleshooting

• Describe what “Settings” part of this package does (as only “Config” was described, and this package has/had second purpose)

More documentation in the package

• api/packages/settings/ADMIN.md
• api/packages/settings/docs/edit.png
• api/packages/settings/docs/list.png
• api/packages/settings/docs/menu.png
• api/packages/settings/docs/settings

API endpoints

Method	Path	Auth	Action
GET	/api/settings		SettingsController@index
GET	/api/settings/{group}/{key}		SettingsController@show
GET	/api/config		ConfigController@list
GET	/api/admin/settings/groups	yes	AdminSettingsController@groups
GET	/api/admin/settings	yes	AdminSettingsController@index
GET	/api/admin/settings/create	yes	AdminSettingsController@create
POST	/api/admin/settings	yes	AdminSettingsController@store
GET	/api/admin/settings/{id}	yes	AdminSettingsController@show
GET	/api/admin/settings/{id}/edit	yes	AdminSettingsController@edit
PUT|PATCH	/api/admin/settings/{id}	yes	AdminSettingsController@update
DELETE	/api/admin/settings/{id}	yes	AdminSettingsController@destroy
GET	/api/admin/config	yes	AdminConfigController@list
POST	/api/admin/config	yes	AdminConfigController@update

Permissions

Permission	Seeded for roles	Constant
settings_manage	admin	SettingsPermissionsEnum::SETTINGS_MANAGE
settings_create	admin	SettingsPermissionsEnum::SETTINGS_CREATE
settings_delete	admin	SettingsPermissionsEnum::SETTINGS_DELETE
settings_update	admin	SettingsPermissionsEnum::SETTINGS_UPDATE
settings_read	admin	SettingsPermissionsEnum::SETTINGS_READ
settings_list	admin	SettingsPermissionsEnum::SETTINGS_LIST
settings_list_readonly	tutor	SettingsPermissionsEnum::SETTINGS_LIST_READONLY
settings_config_list	admin	SettingsPermissionsEnum::CONFIG_LIST
settings_config_update	admin	SettingsPermissionsEnum::CONFIG_UPDATE

Settings

Registered with AdministrableConfig::registerConfig (editable in the admin panel under Configuration → Settings).

None.

Events

Event	Description	Notification templates
SettingPackageConfigUpdated

Artisan commands

None.

Scheduled jobs

None.

Environment variables read

CONFIG_USE_DATABASE