Live properties

One of the underlying principals of the DOM is that properties of Nodes can be "live", meaning that their values change as the DOM changes. In PHP, this type of behaviour can be implemented by using getters - otherwise known as Magic Methods, but this project defines its own magic methods as described below.

Any class within this project that implements a getter or setter should use the LiveProperty trait, rather than utilising the getter or setter magic method directly. This is due to the fact that things become unpredictable or confusing if an object uses a trait or extends a class that already has a __get method defined (see the Traits conflict resolution documentation for an example).

prop_get_* and prop_set_*

As an example of how live properties are used, let's look at the ParentNode trait. On line 39, we can see the getter for the children property, called prop_get_children. To show this live property in action, look at the next method in the same trait, firstElementChild. The firstElementChild method calls the trait's own live property directly as $this->children.

Any properties that are exposed as a live property should document the property in the class's PHPDocumentor comment using the @property, @property-read or @property-write tags.