Download the PHP package axebear/php-magic without Composer

PHP Magic

This PHP package provides utilities for adding magic properties and methods to your classes using custom attributes and docblocks. Highlights include:

• Automagic properties, created with the @property tag.
• Automagic cached, calculated properties using the @property-read tag and a method with the same name.
• Automagic fluent methods the @method tag.
• Easier overloaded methods. Use @method and the #[Overloaded] attribute to split out the logic for overloaded methods into separate functions. This package will call the correct one based on the arguments.
• Transformed properties, on set or get, with the #[MagicProperty] attribute.
• Full access to add more custom handlers using the Magic trait.

Motivation

I have a love-hate relationship with magic methods in PHP. You can build some impressive things using dynamically handled properties and methods, but it can also be opaque and hard to debug without being disciplined about adding documentation. This package aims to make magic methods more transparent and easier by using PHP's built-in reflection capabilities and docblocks to define class behaviors.

A Simple Example

But wait. There's more.

Installation

Scripts

• composer test: Test with Pest
• composer cli: Open a Pysch shell with the package loaded

Getting Started

MagicProperties

The MagicProperties trait inspects your class documentation for @property, @property-read, and @property-write tags and adds the corresponding magic methods to your class so that those properties work. You can optionally add configuration to any of the properties with the #[MagicProperty] attribute.

Calculated Properties You may provide a backing protected or private method for a @property-read property. If you do, that method will be used as the getter for the property. This allows you to create calculated properties. Named parameters for this method are mapped to properties of the class, and the output is cached.

Type Coercion Simple type coercion is applied based on the type hint in the property tag. Most PHPDoc Types that PHPStan supports are automatically cast for you. If a type isn't supported, you can add custom type coercion by adding a #[MagicProperty] attribute to the property and defining onSet and onGet methods.

Fluent Getters and Setters In addition to mapping properties, you can also create magic getter and setter methods using the @method tag in your class documentation. This allows you to provide a fluent interface for your class so that you can chain multiple setter calls together.

Digging Deeper

AxeBear\Magic\Traits\Magic

This base trait is a registry for all of the handlers to call when a magic method is needed. The other traits in this package use this one at their core to provide the magic functionality, but it's also available for you to use directly.

Important Hints

The visibility of the properties and methods that you use with the Magic trait is important. The class members being overloaded should be inaccessible, either protected or private, so that the magic methods can be called.

Events

When a magic method is called, the Magic trait will generate a MagicEvent instance and pass it to any registered handlers that match the event name (using fnmatch).

The base MagicEvent instanced includes the following properties:

• name: The name of the class member being called.
• stopped: A boolean value that can be set to true to stop the event from being processed by any further handlers.

This class also provides the ability to set an output value that will be returned by the magic method. The Magic trait will return this value when processing the magic method. The output can be manipulated by any of the handlers that are registered for the event in turn, which means you can pipe the output value through multiple functions.

• setOutput(mixed $value): static Sets the output value for the event.
• hasOutput(): bool Checks if the event has an output value set. (This is important because null is a valid output value.)
• getOutput(?Closure $defaultValue = null): mixed Gets the output value for the event.

__get

• Listener: onMagicGet(string $name, Closure ...$handlers): static
• Event: MagicGetEvent

To hook into this event, register one or more handlers using the $this->onMagicGet($pattern, Closure ...$handlers) method. The closure should expect a MagicGetEvent instance as its parameter.

__set

• Listener: onMagicSet(string $name, Closure ...$handlers): static
• Event: MagicSetEvent

To hook into this event, register one or more handlers using the $this->onMagicSet($pattern, Closure ...$handlers) method. The closure should expect a MagicSetEvent instance as its parameter. This event includes an additional value property that contains the value being set.

__call

• Listener: onMagicCall(string $name, Closure ...$handlers): static
• Event: MagicCallEvent

To hook into this event, register one or more handlers using the $this->onMagicSet($pattern, Closure ...$handlers) method. The closure should expect a MagicCallEvent instance as its parameter. This event includes an additional arguments property that contains the arguments being passed to the method.

MagicProperties

This trait inspects your class documentation for @property, @property-read, and @property-write tags and adds the corresponding magic methods to your class so that those properties work. You can optionally add configuration to any of the properties with the #[MagicProperty] attribute.

Basic Usage

At its simplest when you include @property tags in your class documentation, the MagicProperties trait will add a getter and setter for the property.

If there the class includes a protected or private property of the same name, it will be used as the backing storage for the property. If there is not property with the name, the values will be stored in an unboundProperties array defined in the trait.

In either case, you can use the getRawValue method to get the raw value of the property, bypassing any transformations that may be applied. (See the section on transforming values for more information.)

Read-Only and Write-Only Properties

You can also define read-only and write-only properties with the @property-read and @property-write tags. These can't be unbound. They'll need a backing property in your class. Otherwise a readonly property won't have an initial value, and a write-only property won't have a place to store the value.

Calculated Properties

You can also define calculated properties by adding a @property-read tag to your class documentation and defining a protected or private method with the same name as the property.

If the calculation has any dependencies on other class values, you should add those as parameters to the method. Use the same name as the class members. Output of calculated properties are cached, and any parameters included in the method signature will be used to calculate the cache.

Transforming Values

You can also customize how a property is set or retrieved by adding a #[MagicProperty] attribute to the property. The #[MagicProperty] attribute accepts onGet and onSet parameters that allow modifying the value before setting it.

Both onSet and onGet accept an array of callables that will be called in the order they are defined. The callables should accept the value as the first parameter and return the modified value. You may use either built-in PHP functions or custom class methods that are defined on the class.

Fluent Getters and Setters

In addition to mapping properties, you can also create magic getter and setter methods using the @method tag in your class documentation. This is useful when you want to provide a fluent interface for your class. The MagicProperties trait will automatically add the magic methods to your class when it sees the @method tag with either zero or one parameters.

If the @method tag includes one parameter, the MagicProperties trait will add a setter method. If the @method tag includes zero parameters, the MagicProperties trait will add a getter method.

Overloaded Methods

PHP doesn't yet offer clean syntax for overloading methods. With the #[Overloaded] attribute and the OverloadedMethods trait, you can split out the logic for overloaded methods into separate methods that are called based on the type of the arguments passed to the method.

Instead of:

You can do this: