Yii Addendum ¶
- Project on github - Check for latest version
- Addendum Documentation
Quick Install ¶
composer require maslosoft/addendum
Goal of this extension is to provide additional metadata for any class, their properties or methods. It's based on annotations, so adding this metadata is as easy as adding doc comments. This extension is rebuild addendum php library
Background ¶
I created this extension, because I wanted to see all attribute properties of my models in one place and also needed more than Yii built in. I mean like validators, labels. This way i have property of model, and just above it i have all what it defines. Some models even does not require any methods, plain attributes with annotations.
Key features ¶
- Easy add metadata
- Lightweight container
- Extendable
- Netbeans completition support
Setup ¶
As with most extensions add this to components
'components' => [
'addendum' => [
'class' => Maslosoft\Addendum\Addendum::class,
],
Basic usage ¶
This extension is production ready. For downloads see project page
use composer to install:
composer require maslosoft/addendum
What are annotations ¶
If you are familiar with annotations, skip this chapter.
Annotations are special type of comments, which are parsed and evaluated by annotaion engine. They are similar to php doc tag, but to distinguish they starts with capital letter. They also can have optional params or even can be nested. Simple example:
/**
* @Label('First name')
* @Persistent
* @RequiredValidator
* @var string
*/
$name = '';
@var
is well known doc tag, while @Label
defines label for this attribute. @Persistent
indicates that attribute is persistent and @RequiredValidator
might add built in required
validator. Notice the word might, as annotations are not classes, what they do can be defined elsewhere. For detailed annotations syntax see annotations data types.
Using annotations in your application ¶
First of all, if you want your class to be used by addendum engine, you have to "implement" AnnotatedInterface
interface. Implement is a big word here, as it is just empty interface, used only to allow annotating class.
Now you can add annotations like in example below:
/**
* @Label('My application user')
*/
class User extends CActiveRecord implements Maslosoft\Addendum\Interfaces\AnnotatedInterface
{
/**
* @Label('First name')
* @RequiredValidator
* @var string
*/
$name = '';
}
Now you have some annotation added. Each annotation defines some metadata for it's entity - using entity i will refer to one of class, property or method container.
Next we can scrap that metadata from class definition, and put it to lightweight container.
// Use statements omitted
// You can also create container directly
// $meta = Meta::create(User::class);
echo $meta->type()->label;
echo $meta->name->label;
This will output My application user
First name
.
$meta->type()
gets class (type) metadata, while class properties are available as fields, and methods with $meta->method('methodName')
function.
NOTE: setting @Label
does not mean that label
field will be set in container - it is annotation responsibility of what to do with it's data.
Defining annotation ¶
Creating your own annotation is very easy. Ill demonstrate it on @Label
. Just create class with Annotation
suffix, and make sure it is imported.
<?php
// use statements omitted
/**
* Label
* Set translated entity 'label' field
* @template Label('${text}')
*/
class LabelAnnotation extends MetaAnnotation
{
public $value = '';
public function init()
{
$this->value = Yii::t('', $this->value);
$this->getEntity()->label = $this->value;
}
public function __toString()
{
return $this->value;
}
}
Method getEntity
will return is container object for class (type), field or method, depending on context. Then we have set label
field of this object.
NOTE: @template
is special docblock used to generate NetBeans completion files (currently separate project).
Requirements ¶
- PHP 5.6, 7.*
- Any Yii, tested on 1.1.17
Known bugs ¶
Resources ¶
Big thanks goes to ¶
- Jan Suchal for creating php addendum
- be next here:)
A screenshot would be nice
Hello, nice work.
A screen shot would be nice
A screenshot would be nice
There is nothing to make screenshot of. Eventually screenshot of netbeans code completition working with annotations.
Why PHP 5.4?
I'm wondering, why such simple (and for some: pretty useless! :]) extension sets its requirements as high as PHP 5.4?
First, I noticed your examples using square brackets array syntax, introduced in PHP 5.4, but then I saw your strict requirement, that PHP 5.4 is required. And I'm wondering, what did you used in your code (except
[]
brackets, which can be converted toarray()
approach with a snap), that can't be compiled under PHP 5.3?Re: Why PHP 5.4?
My eyes twinkle of all that
array
words:)This useless extension also use one array dereference (not really nessesary).
Next version will require at least php 5.5 because of cool ::class constant for which i will find plenty uses:)
Re: Why PHP 5.4?
I'm seriously convinced, that even PHP 5.6 boundaries are limiting you! :] I strongly suggests, that you start coding PHP 6.0 on your own, so you can use all its new cool features in your amazing extension! :] :] :]
If you have any questions, please ask in the forum instead.
Signup or Login in order to comment.