Menu

Addendum 5.0.11

Documentation | API


  • Support project with your solutions
  • Let open source grow
  • Showcase your code
  • Protect your intelectual property
  • Influence project direction
  • Support project evolution
  • Ensure continuous development

Help me choose license

Dependencies:
Cache Easy to use, auto configurable, extensible cache provider
Cli Shared Shared CLI application components
Embedi Embedded DI container
Gazebo Plugin container
Hedron PHP source code class header applier
Signals Wireless Cross-Component Communication
Zamm Zamm is a documentation tool

Maslosoft Addendum Logo Maslosoft Addendum
Easy to use php annotations 

Annotations for PHP

Annotations are in fact a kind declarative language embedded in PHP code. It does not allow and flow control structures, loops, conditions. It allows us to describe what is required or what we expect from parf of code.

Where to use annotations

While (PHP) programming language itself is very flexible and allows us to describe complex bahaviors, there are some aspects where we want to only describe (or configure) such behaviors. And we want to keep our main code as is, while adding some additional behaviors, which might include:

  • Access control
  • Way to display data
  • Whether to store data
  • Where to store data
  • Should the data be searchable

And so on, with ever growing list of aspects and behaviors. While this could be made by implementing in our classe more and more interfaces, soon those would end up in hundreds of methods.

Another way could be some kind of extra meta-data configuration, let it be in XML, JSON or YAML files. This requires us to keep those too files in sync and also separates declarations from code. But we might need extra behaviors/aspects for many libraries - resulting in code being split into two or more files.

Embed behavior into code

So the idea is to embed those extra aspects of class into code. With annotations - special comment tags placed just above class/method/property declaration.

These annotations can be interpreted independently by different parts of program. These are extensible, so that adding more annotations does not influence existing code.

Different application parts might interpret just part of annotations while ignoring unknown ones.

In below example one part will react @Label and @Description declarations, other will perform some extra operations when will encouner @I18N annotation.

Example:

class Page implements AnnotatedInterface
{
    /**
     * Page URL
     * @Label('Page URL')
     * @Description('Relative URL, it should be simple lowercase string with words separated by hyphen')
     * @SearchBoost(3.5)
     * @I18N
     * @SafeValidator
     * @UrlValidator
     * @Decorator(Action, 'update')
     * @see Action
     * @var string
     */
    public $url = '';
}

All extra metadata is contained just where class property is declared. This is it. Annotations itself are not evaluated on each request. These are used to generate metadata, which is later available by using meta containers. Having any object implementing AnnotatedInterface, metadata can be obtained by passing either object or class name.

Example of getting meta data:

echo Meta::create(Page::class)->url->label;
// Will echo "Page URL"

This metadata is cached, so there is no overhead of parsing annotations.