# 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.
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).
Also, this is not a dependency injection container. Stop using DI containers FFS.