Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 1m14s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 1m12s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 1m7s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 1m19s
CI / PHP 8.3 / mysql:8.0 (pull_request) Successful in 1m32s
CI / PHP 8.4 / mysql:8.0 (pull_request) Successful in 1m22s
CI / PHP 8.4 / mysql:8.4 (pull_request) Successful in 1m32s
CI / PHP 8.3 / mysql:8.4 (pull_request) Successful in 1m35s
CI / Build-Artefakte aktuell (pull_request) Failing after 1m7s
- Laravel 13 mit Filament 5 (Admin), Inertia 3 + Vue 3 + Vuetify 4 (Material 3) - Anmeldung über Fortify (Login, Passwort vergessen/ändern), keine Selbstregistrierung - Profil mit Profilbild (WebP in festen Größen), Personenseiten, Header mit Avatar-Menü - Material-3-Farbschema aus der Primärfarbe, hell/dunkel/System pro Person - Basis-Branding (Portalname, Logo, Primärfarbe) im Admin unter „Erscheinungsbild“ - Benutzerverwaltung im Admin, Zugang vorläufig über is_admin - vendor/ (ohne Dev-Pakete) und Frontend-Build mitversioniert, Dev-Pakete in vendor-dev/ - PHPUnit-Tests gegen MySQL/MariaDB, Forgejo-CI-Matrix, Docker-Entwicklungsumgebung - VERSION, CHANGELOG.md und CONTRIBUTING.md mit Release-Ablauf Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
231 lines
11 KiB
Markdown
231 lines
11 KiB
Markdown
# chillerlan/php-settings-container
|
|
|
|
A container class for settings objects - decouple configuration logic from your application! Not a DI container.
|
|
- [`SettingsContainerInterface`](https://github.com/chillerlan/php-settings-container/blob/main/src/SettingsContainerInterface.php) provides fancy [property hooks](https://wiki.php.net/rfc/property-hooks) for PHP < 8.4.
|
|
|
|
[![PHP Version Support][php-badge]][php]
|
|
[![version][packagist-badge]][packagist]
|
|
[![license][license-badge]][license]
|
|
[![Continuous Integration][gh-action-badge]][gh-action]
|
|
[![Coverage][coverage-badge]][coverage]
|
|
[![Codacy][codacy-badge]][codacy]
|
|
[![Packagist downloads][downloads-badge]][downloads]
|
|
|
|
[php-badge]: https://img.shields.io/packagist/php-v/chillerlan/php-settings-container?logo=php&color=8892BF
|
|
[php]: https://www.php.net/supported-versions.php
|
|
[packagist-badge]: https://img.shields.io/packagist/v/chillerlan/php-settings-container.svg?logo=packagist
|
|
[packagist]: https://packagist.org/packages/chillerlan/php-settings-container
|
|
[license-badge]: https://img.shields.io/github/license/chillerlan/php-settings-container.svg
|
|
[license]: https://github.com/chillerlan/php-settings-container/blob/main/LICENSE
|
|
[coverage-badge]: https://img.shields.io/codecov/c/github/chillerlan/php-settings-container.svg?logo=codecov
|
|
[coverage]: https://codecov.io/github/chillerlan/php-settings-container
|
|
[codacy-badge]: https://img.shields.io/codacy/grade/bd2467799e2943d2853ce3ebad5af490/main?logo=codacy
|
|
[codacy]: https://app.codacy.com/gh/chillerlan/php-settings-container/dashboard?branch=main
|
|
[downloads-badge]: https://img.shields.io/packagist/dt/chillerlan/php-settings-container.svg?logo=packagist
|
|
[downloads]: https://packagist.org/packages/chillerlan/php-settings-container/stats
|
|
[gh-action-badge]: https://img.shields.io/github/actions/workflow/status/chillerlan/php-settings-container/ci.yml?branch=main&logo=github
|
|
[gh-action]: https://github.com/chillerlan/php-settings-container/actions/workflows/ci.yml?query=branch%3Amain
|
|
|
|
## Documentation
|
|
|
|
### Installation
|
|
**requires [composer](https://getcomposer.org)**
|
|
|
|
*composer.json* (note: replace `dev-main` with a [version constraint](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints), e.g. `^3.0` - see [releases](https://github.com/chillerlan/php-settings-container/releases) for valid versions)
|
|
```json
|
|
{
|
|
"require": {
|
|
"php": "^8.1",
|
|
"chillerlan/php-settings-container": "dev-main"
|
|
}
|
|
}
|
|
```
|
|
|
|
Profit!
|
|
|
|
## Usage
|
|
|
|
The `SettingsContainerInterface` (wrapped in`SettingsContainerAbstract`) provides plug-in functionality for immutable object properties and adds some fancy, like loading/saving JSON, arrays etc.
|
|
It takes an `iterable` as the only constructor argument and calls a method with the trait's name on invocation (`MyTrait::MyTrait()`) for each used trait.
|
|
|
|
A PHPStan ruleset to exclude errors generated by accessing magic properties on `SettingsContainerInterface` can be found in `rules-magic-access.neon`.
|
|
|
|
|
|
### Simple usage
|
|
```php
|
|
class MyContainer extends SettingsContainerAbstract{
|
|
protected string $foo;
|
|
protected string $bar;
|
|
}
|
|
```
|
|
|
|
```php
|
|
// use it just like a \stdClass (except the properties are fixed)
|
|
$container = new MyContainer;
|
|
$container->foo = 'what';
|
|
$container->bar = 'foo';
|
|
|
|
// which is equivalent to
|
|
$container = new MyContainer(['bar' => 'foo', 'foo' => 'what']);
|
|
// ...or try
|
|
$container->fromJSON('{"foo": "what", "bar": "foo"}');
|
|
|
|
|
|
// fetch all properties as array
|
|
$container->toArray(); // -> ['foo' => 'what', 'bar' => 'foo']
|
|
// or JSON
|
|
$container->toJSON(); // -> {"foo": "what", "bar": "foo"}
|
|
// JSON via JsonSerializable
|
|
$json = json_encode($container); // -> {"foo": "what", "bar": "foo"}
|
|
```
|
|
|
|
By default, non-existing properties will be ignored and return `null`:
|
|
|
|
```php
|
|
$container->nope = 'what';
|
|
|
|
var_dump($container->nope); // -> null
|
|
```
|
|
|
|
You can change this behaviour by adding the attribute `ThrowOnInvalidProperty` to your container class:
|
|
|
|
```php
|
|
#[ThrowOnInvalidProperty(true)]
|
|
class MyContainer extends SettingsContainerAbstract{
|
|
// ...
|
|
}
|
|
|
|
$container->nope = 'what'; // -> throws: attempt to write invalid property: "$nope"
|
|
```
|
|
|
|
|
|
### Advanced usage
|
|
|
|
Suppose the following trait from library 1:
|
|
|
|
```php
|
|
trait SomeOptions{
|
|
protected string $foo;
|
|
protected string $what;
|
|
|
|
// this method will be called in SettingsContainerAbstract::construct()
|
|
// after the properties have been set
|
|
protected function SomeOptions():void{
|
|
// just some constructor stuff...
|
|
$this->foo = strtoupper($this->foo);
|
|
}
|
|
|
|
/*
|
|
* special prefixed magic setters & getters ("set_"/"get_" + property name)
|
|
*/
|
|
|
|
// this method will be called from __set() when property $what is set
|
|
protected function set_what(string $value):void{
|
|
$this->what = md5($value);
|
|
}
|
|
|
|
// this method is called on __get() for the property $what
|
|
protected function get_what():string{
|
|
return 'hash: '.$this->what;
|
|
}
|
|
}
|
|
```
|
|
|
|
And another trait from library 2:
|
|
|
|
```php
|
|
trait MoreOptions{
|
|
protected string $bar = 'whatever'; // provide default values
|
|
}
|
|
```
|
|
|
|
We can now plug the several library options together to a single class/object:
|
|
|
|
```php
|
|
$commonOptions = [
|
|
// SomeOptions
|
|
'foo' => 'whatever',
|
|
// MoreOptions
|
|
'bar' => 'nothing',
|
|
];
|
|
|
|
$container = new class ($commonOptions) extends SettingsContainerAbstract{
|
|
use SomeOptions, MoreOptions;
|
|
};
|
|
|
|
var_dump($container->foo); // -> WHATEVER (constructor ran strtoupper on the value)
|
|
var_dump($container->bar); // -> nothing
|
|
|
|
$container->what = 'some value';
|
|
var_dump($container->what); // -> hash: 5946210c9e93ae37891dfe96c3e39614 (custom getter added "hash: ")
|
|
```
|
|
|
|
### A note on property hooks (PHP 8.4+)
|
|
|
|
Property hooks are called whenever a property is accessed (except from within the hook itself of course), which means that the custom get/set methods this library allows would conflict when a custom method is defined for a property that also has a hook defined.
|
|
To prevent double method calls, the internal methods `hasSetHook()` and `hasGetHook()` have been introduced, and are called whenever the magic get/set methods are called: when both, a custom method and a property hook exist, only the property hook will be called.
|
|
<br/>Public properties will never call the magic get/set, however, their hooks *will* be called. (un)serializing a `SettingsContainerInterface` instance will bypass magic get/set and existing property hooks, while JSON de/encode as will call magic get/set or existing hooks explicitly via the `toArray()` and `fromIterable()` methods.
|
|
|
|
```php
|
|
class PropertyHooksContainer extends SettingsContainerAbstract{
|
|
|
|
protected string $someValue{
|
|
set => doStuff($value);
|
|
}
|
|
|
|
// this method will be ignored in magic calls as a "set" hook on the property exists
|
|
protected function set_someValue(string $value):void{
|
|
$this->someValue = doOtherStuff($value);
|
|
}
|
|
|
|
// this custom method will be called as the property has no "get" hook
|
|
protected function get_someValue():string{
|
|
return doWhatever($this->someValue);
|
|
}
|
|
|
|
// this property will never trigger the magic get/set and associated methods
|
|
public string $otherValue{
|
|
set => doStuff($value);
|
|
get => $this->otherValue;
|
|
}
|
|
|
|
}
|
|
```
|
|
|
|
|
|
### API
|
|
|
|
#### [`SettingsContainerAbstract`](https://github.com/chillerlan/php-settings-container/blob/main/src/SettingsContainerAbstract.php)
|
|
|
|
| method | return | info |
|
|
|--------------------------------------------|------------------------------|---------------------------------------------------------------------------------------------------------------------|
|
|
| `__construct(iterable $properties = null)` | - | calls `construct()` internally after the properties have been set |
|
|
| `__get(string $property)` | mixed | calls `$this->{'get_'.$property}()` if such a method exists |
|
|
| `__set(string $property, $value)` | void | calls `$this->{'set_'.$property}($value)` if such a method exists |
|
|
| `__isset(string $property)` | bool | |
|
|
| `__unset(string $property)` | void | |
|
|
| `__toString()` | string | a JSON string |
|
|
| `toArray()` | array | |
|
|
| `fromIterable(iterable $properties)` | `SettingsContainerInterface` | |
|
|
| `toJSON(int $jsonOptions = null)` | string | accepts [JSON options constants](http://php.net/manual/json.constants.php) |
|
|
| `fromJSON(string $json)` | `SettingsContainerInterface` | |
|
|
| `jsonSerialize()` | mixed | implements the [`JsonSerializable`](https://www.php.net/manual/en/jsonserializable.jsonserialize.php) interface |
|
|
| `serialize()` | string | implements the [`Serializable`](https://www.php.net/manual/en/serializable.serialize.php) interface |
|
|
| `unserialize(string $data)` | void | implements the [`Serializable`](https://www.php.net/manual/en/serializable.unserialize.php) interface |
|
|
| `__serialize()` | array | implements the [`Serializable`](https://www.php.net/manual/en/language.oop5.magic.php#object.serialize) interface |
|
|
| `__unserialize(array $data)` | void | implements the [`Serializable`](https://www.php.net/manual/en/language.oop5.magic.php#object.unserialize) interface |
|
|
|
|
|
|
#### Internal (protected) methods
|
|
|
|
| method | return | info |
|
|
|--------------------------------------|--------|-------------------------------------------------------------------------------|
|
|
| `construct()` | void | calls a method with trait name as replacement constructor for each used trait |
|
|
| `isPrivate(string $property)` | bool | private properties are excluded from magic calls |
|
|
| `hasSetHook(string $property)` | bool | |
|
|
| `hasGetHook(string $property)` | bool | |
|
|
|
|
|
|
## Disclaimer
|
|
This might be either an absolutely brilliant or completely stupid idea - you decide (in hindsight it was a great idea I guess - property hooks made their way into PHP 8.4).
|
|
<br/>Also, this is not a dependency injection container. Stop using DI containers FFS.
|