phpgt/propfunc

Property accessor and mutator functions.

Fund package maintenance!
PhpGt

v1.0.1 2021-03-23 12:46 UTC

This package is auto-updated.

Last update: 2021-12-23 14:24:15 UTC


README

Property accessors and mutators are commonly referred to as "getter" and "setter" functions. This library uses PHP's Magic Methods to easily hook up getter and setter functions that are exposed externally as normal properties, via the MagicProp trait.

Why? This kind of functionality can certainly be seen as a hack, but sometimes hacks are necessary. Specifically PHP.Gt is implementing the DOM standard in PHP which requires certain properties to have "live" or "readonly" functionality, which is only possible using magic __get and __set functions. This library simply holds the reusable behaviour for other repositories that require it.

Build status Code quality Code coverage Current version PHP.Gt/PropFunc documentation

Example usage: Read-only properties that are calculated upon access

See the class Day below, which represents a day in time:

use Gt\PropFunc\MagicProp;

/**
 * @property-read bool $future True if the day is in the future
 * @property-read int $daysApart Days between now and this day
 */
class Day {
	use MagicProp;
	
	public function __construct(
		private DateTimeInterface $dateTime
	) {}
	
// Expose the "dateTime" private property with read-only access:
	private function __prop_get_dateTime():DateTimeInterface {
		return $this->dateTime;
	}
	
// Expose the "future" calculated property with read-only access:
	private function __prop_get_future():bool {
		$now = new DateTime();
		return $now < $this->dateTime;
	}
	
// Expose the "daysApart" calculated property with read-only access:
	private function __prop_get_daysApart():int {
		$now = new DateTime();
		$diff = $now->diff($this->dateTime);
		return $diff->days;
	}
}

See the code below which uses the Day class. It can access the properties, but not mutate them.

$day = new Day($dateTime);
echo "Day is $day->diff days in the ";
echo $day->future ? "future" : "past";
echo PHP_EOL;
$day->diff = 10;
echo "Exception thrown on line above!";

Usages

  • Read only properties - as with the above example, properties can be made read-only. This feature is coming to the PHP language, but without the ability to define the accessor logic.
  • Live properties - if a property's value is required to update depending on certain conditions, a getter function is required.
  • Property validation - if a property's value can't simply be validated by its type alone, the setter function can be used to ensure the value meets validation criteria.