Jasny Meta

The Jasny Meta library allows you to attach metadata to a class and class properties. The metadata is available at runtime and can be used to trigger particular behaviour.

Installation

The Jasny Meta package is available on packagist. Install it using composer:

composer require jasny/meta

Annotations

Metadata can be specified through annotations. In PHP annotations are written in the docblock and start with @. If you're familiar with writing docblocks, you probably recognize them.

The Jasny\Meta\Introspection\AnnotationsImplementation trait adds a static method meta() to your class, which returns the parsed annotations as metadata.

Implement the Jasny\Meta\Introspection interface to indicate that the class has accessable metadata through the meta() method.

use Jasny\Meta\Introspection;

/**
 * A system user
 *
 * @represents A person or organization
 * @softdelete
 */
class User implements Jasny\Meta\Introspection
{
    use Introspection\AnnotationsImplementation;

    /**
     * The user's e-mail address.
     *
     * @var string
     * @type url
     * @required
     */
    public $website;
    
    ..
}

echo User::meta()['represents'];                  // A person or organization
echo User::meta()['softdelete'] ? 'yes' : 'no';   // yes
echo User::meta()['lazy'] ? 'yes' : 'no';         // no

echo User::meta()->ofProperty('website')['var'];  // string

Meta class

The Jasny\Meta class extends ArrayObject. The metadata is accessable as associated array or through the get() method.

User::meta()['foo'];
User::meta()->get('foo');

Requesting non-existing keys will return null and won't trigger a notice.

You may also set or add metadata. Either using the Meta object as associated array or through the set() method.

User::meta()['foo'] = true;
User::meta()->set($key, $value);
User::meta()->set(array $values);

Class properties

metadata of class properties are available as properties of the of the Meta object or through the ofProperty() method. To get the meta of all properties use the ofProperties() method.

User::meta()->ofProperty('email')['required'];
User::meta()->ofProperty('email')->get('required');
User::meta()->ofProperties(); // Get metadata of all class properties

Custom metadata

You may wish to add metadata from another source. Instead of using the Jasny\Meta\Annotations trait, create your own implementation of the meta() method.

/**
 * A system user
 *
 * @softdelete
 */
class User implements Jasny\Meta\Introspection
{
    /**
     * Get class metadata
     *
     * @return Jasny\Meta
     */
    public static funciton meta()
    {
        return new Jasny\Meta(['abc' => 10, 'def' => 20]);
    }
}

Todo

• Support multiple annotations with the same key (eg @param)