Download the PHP package decodelabs/veneer without Composer

Veneer

Create automated static frontages for your PHP objects.

Use Veneer to provide easy access to your most commonly used functionality without sacrificing testability.

Get news and updates on the DecodeLabs blog.

Install

Usage

Say you have a common library class you use regularly:

You can bind a static, automatically generated frontage by:

Plugins

Unfortunately PHP still doesn't have __getStatic() yet so we have to statically declare plugin names at binding time, but they're still useful for creating more expansive interfaces.

Define plugins as properties on your FacadeTarget with a Plugin attribute. By default, plugins require manual instantiation in the constructor, however you can flag it as auto to have it automatically built at bind time, or lazy if it doesn't need to be loaded straight away.

Note, if your target class has a constructor with required parameters, you will need to add decodelabs/slingshot to your project to allow Veneer to instantiate it.

Lazy instantiation uses the new ghost and proxy functionality in PHP8.4 and will only instantiate the plugin when it is first accessed. Due to the limitations of lazy objects in PHP, you cannot create a lazy proxy for internal classes so you may find that plugins are referenced with a transparent Plugin\Wrapper class which resolves to the actual plugin instance when accessed. This usually isn't an issue unless you try to pass a plugin instance to a function that expects a specific class type, directly from the proxy. In these cases you should return the plugin instance from a method on the target class.

Property Hooks

PHP 8.4 property hooks can be used in combination with Plugins, however be aware that they will conflict with auto and lazy instantiation. Hooks defined with the structure below will effectively act like a lazy loaded plugin, however with the additional benefits of being able to control how it is instantiated rather than relying on Slingshot.

Hooks can be virtual (ie, don't require a value backed property), however the proxy will reference the first instantation of a virtual hook and your plugin instances will likely go out of sync.

Note, the protected(set) visibility in the example; it is not a requirement, but it is recommended to prevent direct write access to the property. If you need to replace a plugin instance, you should do so via Veneer::replacePlugin(\$providerInstance, \'propertyName\', \$newPlugin). This allows Veneer to update the plugin in the static frontage proxy as well as the target instance.

Licensing

Veneer is licensed under the MIT License. See LICENSE for the full license text.