Download the PHP package caseyamcl/settings-manager without Composer
On this page you can find all versions of the php package caseyamcl/settings-manager. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download caseyamcl/settings-manager
More information about caseyamcl/settings-manager
Files in caseyamcl/settings-manager
Package settings-manager
Short Description Settings Manager
License MIT
Homepage https://github.com/caseyamcl/settings-manager
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package settings-manager
Settings Manager
This is a framework-agnostic library that provides an abstraction for managing and storing user-changeable settings. Settings can be stored in a configuration file, database, external API or anywhere else. The defining characteristic of this library is designed around the assumption that settings will be modified during runtime, which makes it particularly useful for increasingly popular architectures such as Swoole, React, etc.
It provides the following features:
- Class-based setting definitions
- Ability to define multiple providers for settings and load them in a cascading manner
- Ability to validate and prepare/transform setting values
- PSR-4 and PSR-12 compliance; 100% unit test coverage
What is a setting?
This library is useful for projects that make a clear distinction between configuration values (set by administrators) and settings (available in the app; changeable by users during runtime):
| Configuration Value | Setting |
|---|---|
| Set on the command line in a YAML/JSON/INI file or environment variable during application setup | Set in the application's API or web interface |
| Managed by system administrator or developer | Managed by application user |
| Not likely to ever change | Mutable and able to change during runtime |
| Should be set before application can be executed | Not necessary during app bootstrap |
Concepts
A Setting Definition is simply a PHP class that implements the
SettingDefinition interface. A setting definition has the following attributes:
- A name (e.g. a machine name/slug)
- A display name
- Internal notes
- An optional default value
- Optional validation/transform logic for processing incoming values
- Whether or not this value is sensitive (e.g. should be treated securely)
Setting definitions are added to an instance of the SettingDefinitionRegistry.
A Setting Provider is a service class that loads setting values from a source. Sources can be configuration files, databases, or really anything. See the usage section below for a list of bundled providers.
Multiple providers can be chained together so that setting values are loaded in a cascading way. Several providers have been bundled (see below), but you can feel free to add
your own by implementing the SettingProvider interface. Providers have similar attributes to definitions:
- A name (e.g. a machine name/slug)
- A display name
A Setting Value is an object that stores the value of the setting, along with a few additional bits of information:
- The setting name
- The provider name that this setting came was defined by
- Mutability - whether this setting can be overridden after this provider (e.g. an administrator may want to lock a setting in-place in a configuration file and not allow a downstream provider to change it)
Install
Via Composer
Usage
Basic Usage
Basic usage of this library consists of two steps:
- Defining setting definitions
- Loading setting values from providers
Defining setting definitions
The recommended way to create settings is for each setting definition to be its own class. While this isn't strictly necessary
(you can create any class that implements SettingDefinition), it does keep things clean and simple.
For convenience, this library includes the AbstractSettingDefinition class, which includes constants
for common attributes. See the following example:
Loading setting values from providers
Setting values are loaded from setting providers. There are a few bundled providers
included in this library, and you can create your own by implementing the SettingsManager\Contract\SettingProvider interface.
In this example, we use the CascadingSettingProvider to combine the functionality of
the DefaultValuesProvider and the ArrayValuesProvider:
Bundled providers
Basic setting providers are bundled with this library in the SettingsManager\Provider namespace:
| Provider | What it does |
|---|---|
ArrayValuesProvider |
Loads values from an array |
DefaultValuesProvider |
Loads default values |
CascadingSettingProvider |
Loads from multiple providers |
SettingRepositoryProvider |
Loads values from a database or repository (see below) |
Setting mutability
Sometimes you want settings to be "locked" by a certain provider. For example, if you want a setting to be unchangeable after a certain provider has loaded it (say, a configuration file), you can use the following syntax:
Creating your own provider implementation using the SettingRepositoryProvider
Chances are, you'll want to store values in a database. For convenience, a SettingRepository interface
has been bundled as part of this package, along with a SettingRepositoryProvider.
Handling Exceptions
Exceptions all implement the SettingException interface:
| Exception | What causes it |
|---|---|
ImmutableSettingOverrideException |
If a provider has defined a setting as immutable, and a subsequent provider attempts to override it |
InvalidSettingValueException |
This should be thrown in the case of validation errors |
UndefinedSettingException |
This is thrown from a provider when attempting when attempting to load a setting that hasn't been added to the registry |
SettingNameCollissionException |
This is thrown when attempting to add two definitions to the registry with the same name |
SettingValueNotFoundException |
This is thrown when calling getValue() or getValueInstance() from a provider on a non-existent setting |
Considerations for runtime environments
This library facilitates environments such as those provided by Swoole or React in which setting values are updated at runtime.
If you want to enable this functionality, be sure to always inject whatever setting provider you are using in your service classes, and lookup settings during runtime.
Change log
Please see CHANGELOG for more information on what has changed recently.
Testing
Contributing
Please see CODE_OF_CONDUCT for details.
Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
Credits
- Casey McLaughlin
- All Contributors
License
The MIT License (MIT). Please see License File for more information.
