property hooks support (PHP 8.4+)

Author: codemasher

README.md

@@ -139,14 +139,46 @@ $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                                                   |
-| (protected) `construct()`                  | void                         | calls a method with trait name as replacement constructor for each used trait                                       |
 | `__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                         |                                                                                                                     |
@@ -162,6 +194,17 @@ var_dump($container->what); // -> hash: 5946210c9e93ae37891dfe96c3e39614 (custom
 | `__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.

phpstan-baseline.neon

@@ -1,55 +1,31 @@
 parameters:
 	ignoreErrors:
 		-
-			rawMessage: Access to an undefined property chillerlan\SettingsTest\TestContainer::$foo.
-			identifier: property.notFound
+			rawMessage: Access to constant Get on an unknown class PropertyHookType.
+			identifier: class.notFound
 			count: 1
-			path: tests/ContainerTest.php
+			path: src/SettingsContainerAbstract.php
 
 		-
-			rawMessage: Access to private property chillerlan\SettingsTest\TestContainer::$test3.
-			identifier: property.private
-			count: 5
-			path: tests/ContainerTest.php
-
-		-
-			rawMessage: 'Call to static method PHPUnit\Framework\Assert::assertFalse() with true will always evaluate to false.'
-			identifier: staticMethod.impossibleType
-			count: 1
-			path: tests/ContainerTest.php
-
-		-
-			rawMessage: 'Call to static method PHPUnit\Framework\Assert::assertFalse() with true will always evaluate to true.'
-			identifier: staticMethod.alreadyNarrowedType
+			rawMessage: Access to constant Set on an unknown class PropertyHookType.
+			identifier: class.notFound
 			count: 1
-			path: tests/ContainerTest.php
+			path: src/SettingsContainerAbstract.php
 
 		-
-			rawMessage: 'Call to static method PHPUnit\Framework\Assert::assertNull() with string will always evaluate to false.'
-			identifier: staticMethod.impossibleType
+			rawMessage: 'Call to an undefined method ReflectionProperty::getRawValue().'
+			identifier: method.notFound
 			count: 2
-			path: tests/ContainerTest.php
+			path: src/SettingsContainerAbstract.php
 
 		-
-			rawMessage: 'Call to static method PHPUnit\Framework\Assert::assertTrue() with true will always evaluate to true.'
-			identifier: staticMethod.alreadyNarrowedType
-			count: 1
-			path: tests/ContainerTest.php
-
-		-
-			rawMessage: 'Property chillerlan\SettingsTest\TestContainer::$test1 (string) in isset() is not nullable.'
-			identifier: isset.property
+			rawMessage: 'Call to an undefined method ReflectionProperty::hasHook().'
+			identifier: method.notFound
 			count: 2
-			path: tests/ContainerTest.php
-
-		-
-			rawMessage: 'Property chillerlan\SettingsTest\TestContainer::$test3 (string) in isset() is not nullable.'
-			identifier: isset.property
-			count: 1
-			path: tests/ContainerTest.php
+			path: src/SettingsContainerAbstract.php
 
 		-
-			rawMessage: 'Property chillerlan\SettingsTest\TestContainer::$test3 is never read, only written.'
-			identifier: property.onlyWritten
+			rawMessage: 'Call to an undefined method ReflectionProperty::setRawValue().'
+			identifier: method.notFound
 			count: 1
-			path: tests/TestContainer.php
+			path: src/SettingsContainerAbstract.php

src/SettingsContainerAbstract.php

@@ -11,10 +11,10 @@
 
 namespace chillerlan\Settings;
 
-use InvalidArgumentException, JsonException, ReflectionClass, ReflectionProperty;
-use function array_keys, get_object_vars, is_object, json_decode, json_encode,
-	json_last_error_msg, method_exists, property_exists, serialize, unserialize;
+use InvalidArgumentException, JsonException, ReflectionException, ReflectionObject, ReflectionProperty;
+use function is_object, json_decode, json_encode, json_last_error_msg, method_exists, property_exists, serialize, unserialize;
 use const JSON_THROW_ON_ERROR;
+use const PHP_VERSION_ID;
 
 abstract class SettingsContainerAbstract implements SettingsContainerInterface{
 
@@ -40,7 +40,7 @@ public function __construct(iterable|null $properties = null){
 	 * (remember pre-php5 classname constructors? yeah, basically this.)
 	 */
 	protected function construct():void{
-		$traits = (new ReflectionClass($this))->getTraits();
+		$traits = (new ReflectionObject($this))->getTraits();
 
 		foreach($traits as $trait){
 			$method = $trait->getShortName();
@@ -53,15 +53,15 @@ protected function construct():void{
 	}
 
 	public function __get(string $property):mixed{
-
+		// back out if the property is inaccessible
 		if(!property_exists($this, $property) || $this->isPrivate($property)){
 			return null;
 		}
-
-		if(method_exists($this, static::GET_PREFIX.$property)){
+		// call an existing custom method, skip if the property has a hook
+		if(method_exists($this, static::GET_PREFIX.$property) && !$this->hasGetHook($property)){
 			return $this->{static::GET_PREFIX.$property}();
 		}
-
+		// retrieve the value (triggers an existing property hook)
 		return $this->{$property};
 	}
 
@@ -71,7 +71,7 @@ public function __set(string $property, mixed $value):void{
 			return;
 		}
 
-		if(method_exists($this, static::SET_PREFIX.$property)){
+		if(method_exists($this, static::SET_PREFIX.$property) && !$this->hasSetHook($property)){
 			$this->{static::SET_PREFIX.$property}($value);
 
 			return;
@@ -91,6 +91,30 @@ protected function isPrivate(string $property):bool{
 		return (new ReflectionProperty($this, $property))->isPrivate();
 	}
 
+	/**
+	 * @internal Checks if a property has a "set" hook
+	 */
+	protected function hasSetHook(string $property):bool{
+
+		if(PHP_VERSION_ID < 80400){
+			return false;
+		}
+		/** @phan-suppress-next-line PhanUndeclaredMethod, PhanUndeclaredClassConstant */
+		return (new ReflectionProperty($this, $property))->hasHook(\PropertyHookType::Set);
+	}
+
+	/**
+	 * @internal Checks if a property has a "get" hook
+	 */
+	protected function hasGetHook(string $property):bool{
+
+		if(PHP_VERSION_ID < 80400){
+			return false;
+		}
+		/** @phan-suppress-next-line PhanUndeclaredMethod, PhanUndeclaredClassConstant */
+		return (new ReflectionProperty($this, $property))->hasHook(\PropertyHookType::Get);
+	}
+
 	public function __unset(string $property):void{
 
 		if($this->__isset($property)){
@@ -104,13 +128,19 @@ public function __toString():string{
 	}
 
 	public function toArray():array{
-		$properties = [];
 
-		foreach(array_keys(get_object_vars($this)) as $key){
-			$properties[$key] = $this->__get($key);
+		$properties = (new ReflectionObject($this))
+			->getProperties(~(ReflectionProperty::IS_STATIC | ReflectionProperty::IS_READONLY | ReflectionProperty::IS_PRIVATE))
+		;
+
+		$data = [];
+
+		foreach($properties as $reflectionProperty){
+			// the magic getter is called intentionally here, so that any existing hook methods are called on export
+			$data[$reflectionProperty->name] = $this->__get($reflectionProperty->name);
 		}
 
-		return $properties;
+		return $data;
 	}
 
 	/**
@@ -129,7 +159,7 @@ public function toJSON(int|null $jsonOptions = null):string{
 		$json = json_encode($this, ($jsonOptions ?? 0));
 
 		if($json === false){
-			throw new JsonException(json_last_error_msg());
+			throw new JsonException(json_last_error_msg()); // @codeCoverageIgnore
 		}
 
 		return $json;
@@ -151,8 +181,6 @@ public function jsonSerialize():array{
 
 	/**
 	 * Returns a serialized string representation of the object in its current state (except static/readonly properties)
-	 *
-	 * @see \chillerlan\Settings\SettingsContainerInterface::toArray()
 	 */
 	public function serialize():string{
 		return serialize($this);
@@ -161,62 +189,88 @@ public function serialize():string{
 	/**
 	 * Restores the data (except static/readonly properties) from the given serialized object to the current instance
 	 *
-	 * @see \chillerlan\Settings\SettingsContainerInterface::fromIterable()
-	 *
 	 * @throws \InvalidArgumentException
 	 */
 	public function unserialize(string $data):void{
 		$obj = unserialize($data);
 
-		if($obj === false || !is_object($obj)){
+		if(!is_object($obj)){
 			throw new InvalidArgumentException('The given serialized string is invalid');
 		}
 
-		$reflection = new ReflectionClass($obj);
+		$reflection = new ReflectionObject($obj);
 
 		if(!$reflection->isInstance($this)){
 			throw new InvalidArgumentException('The unserialized object does not match the class of this container');
 		}
 
 		$properties = $reflection->getProperties(~(ReflectionProperty::IS_STATIC | ReflectionProperty::IS_READONLY));
+		$data       = [];
 
 		foreach($properties as $reflectionProperty){
-			$this->{$reflectionProperty->name} = $reflectionProperty->getValue($obj);
+			$data[$reflectionProperty->name] = (PHP_VERSION_ID < 80400)
+				? $reflectionProperty->getValue($obj)
+				/** @phan-suppress-next-line PhanUndeclaredMethod */
+				: $reflectionProperty->getRawValue($obj);
 		}
 
+		$this->__unserialize($data);
 	}
 
 	/**
-	 * Returns a serialized string representation of the object in its current state (except static/readonly properties)
+	 * Returns a serialized array representation of the object in its current state (except static/readonly properties),
+	 * bypassing custom getters and property hooks
 	 *
-	 * @see \chillerlan\Settings\SettingsContainerInterface::toArray()
+	 * @return array<string, mixed>
 	 */
 	public function __serialize():array{
 
-		$properties = (new ReflectionClass($this))
+		$properties = (new ReflectionObject($this))
 			->getProperties(~(ReflectionProperty::IS_STATIC | ReflectionProperty::IS_READONLY))
 		;
 
 		$data = [];
 
 		foreach($properties as $reflectionProperty){
-			$data[$reflectionProperty->name] = $reflectionProperty->getValue($this);
+			// bypass existing property hooks for PHP >= 8.4
+			$data[$reflectionProperty->name] = (PHP_VERSION_ID < 80400)
+				? $reflectionProperty->getValue($this)
+				/** @phan-suppress-next-line PhanUndeclaredMethod */
+				: $reflectionProperty->getRawValue($this);
 		}
 
 		return $data;
 	}
 
 	/**
-	 * Restores the data from the given array to the current instance
-	 *
-	 * @see \chillerlan\Settings\SettingsContainerInterface::fromIterable()
+	 * Restores the data from the given array to the current instance,
+	 * bypassing custom setters and property hooks
 	 *
 	 * @param array<string, mixed> $data
 	 */
 	public function __unserialize(array $data):void{
+		$reflection = new ReflectionObject($this);
 
 		foreach($data as $key => $value){
-			$this->{$key} = $value;
+			try{
+				$reflectionProperty = $reflection->getProperty($key);
+
+				if($reflectionProperty->isStatic() || $reflectionProperty->isReadOnly()){
+					continue; // @codeCoverageIgnore
+				}
+
+				(PHP_VERSION_ID < 80400)
+					? $reflectionProperty->setValue($this, $value)
+					/** @phan-suppress-next-line PhanUndeclaredMethod */
+					: $reflectionProperty->setRawValue($this, $value);
+
+			}
+			// @codeCoverageIgnoreStart
+			catch(ReflectionException){
+				// attempt to assign a non-existent property, skip
+				continue;
+			}
+			// @codeCoverageIgnoreEnd
 		}
 
 	}

tests/ContainerTest.php

@@ -130,18 +130,25 @@ public function testSerializable():void{
 			'testConstruct' => 'success',
 		]);
 
-		/** @var \chillerlan\SettingsTest\TestContainer $container */
-		$container = unserialize(serialize($container)); // object should remain in the same state
-
 		// serialize will return the object in its current state including private properties
 		$expected = 'O:37:"chillerlan\SettingsTest\TestContainer":7:{s:5:"test3";s:4:"what";s:5:"test1";s:2:"no";'.
 		            's:5:"test2";b:1;s:13:"testConstruct";s:7:"success";s:5:"test4";N;s:5:"test5";s:0:"";s:5:"test6";N;}';
 
+		$serialized = serialize($container);
+
+		$this::assertSame($expected, $serialized);
+
+		/** @var \chillerlan\SettingsTest\TestContainer $container */
+		$container = unserialize($serialized); // object should remain in the same state
+
 		$this::assertSame($expected, $container->serialize());
-		$this::assertSame($expected, serialize($container));
 
+		$container = (new TestContainer);
 		$container->unserialize($expected);
 
+		$this::assertSame('no', $container->test1);
+		$this::assertSame(true, $container->test2);
+		$this::assertNull($container->test3);
 		$this::assertSame('', $container->test5);
 	}