annotations in php, they exist

Rafael�� Dohms

Annotations�� in�� PHP

@rdohmson�� twitter

They�� Exist!

I’m a Brazilian, living in Amsterdamwhich means I’m probably crazy,

and I speak with my hands

I’m a developer and speaker for… ever.ok its something like 14 years

I’m a serial User Group creatorI can’t help it

I have absolutely no solid Laravel experience

I have absolutely no solid Laravel experienceI’m sorry.

Don’t throw tomatoes

photo by araswami

I have absolutely no solid Laravel experienceI’m sorry.

Don’t throw tomatoes

I’m allergic.

photo by araswami

What? Why? Where?

a�� little�� history

show�� me�� the�� code!

existing�� uses

Implementing�� custom�� annotations

based�� on�� DMS\Filter

what?What�� ar

e�� annotation

http://ecdesignrebels.blogspot.com

-- In English -- "An annotation is a note that is made while

reading any form of text."

-- In English -- "An annotation is a note that is made while

reading any form of text."

something�� that�� describes�� an�� aspect�� of�� the�� subject

“Annotations do not directly affect program semantics”

-- In Code Speak --

“An annotation is metadata attached to your code, that can be read at runtime.”

-- In Code Speak --

effects�� are�� only�� observed�� at

-- In Code Speak --

just�� like�� your�� notes

effects�� are�� only�� observed�� at

Annotations in the wild

annotations

C#attributes

annotations

C#attributes

@Entity! @Table(name = "people")! class Person implements Serializable {! @Id ! @GeneratedValue(strategy = GenerationType.AUTO) ! private Integer id;

annotations

C#attributes

public class Customer!{! [Required]! [StringLength(50)]! public string Prename { get; set; }! ! [Column(TypeName = "image")]! public byte[] Image { get; set; }

annotations

C#attributes

after�� v1.5

annotations

C#attributes

after�� v1.5

since�� first�� release

No�� core�� annotation�� support

Questions?

I’m�� kidding!

phpDoc

PHP�� 5.1Reflection�� supports�� getDocComments()

~2000 2005

First�� Annotation��

�� Engines�� in�� PHP

phpDoc

~2000 2005

phpDoc

~2000 2005 2008

phpDoc

~2000 2005 2008

Doctrine�� 2�� Annotation�� Engine

phpDoc

~2000 2005 2008

RFC:�� Annotations�� in�� core�� w/�� custom��

syntax

phpDoc

~2000 2005 2008

syntaxREJECTED

phpDoc

~2000 2005 2008

syntax

RFC:�� DocBlock�� Annotations��

“in�� discussion”

REJECTED

phpDoc

~2000 2005 2008

syntax

REJECTED

discussion�� sparks�� up�� again

phpDoc

~2000 2005 2008

syntax

REJECTED

discussion�� sparks�� up�� again

Current situation in php-internals

annotations

/** ! * Entity\Reward ! * ! * @ORM\Table("reward") ! * @ORM\Entity(repositoryClass="RewardRepository") ! */ !class Reward !{ ! /** ! * @var integer $id ! * ! * @ORM\Column(name="id", type="integer") ! * @ORM\Id ! * @ORM\GeneratedValue(strategy="AUTO") ! */ ! protected $id; ! ! /** ! * @var string $title ! * ! * @ORM\Column(name="title", type="string", length=150, nullable=true) ! * ! * @Assert\MaxLength(150) ! */ ! protected $title;

annotations

/** ! * Entity\Reward ! * ! * @ORM\Table("reward") ! * @ORM\Entity(repositoryClass="RewardRepository") ! */ !class Reward !{ ! /** ! * @var integer $id ! * ! * @ORM\Column(name="id", type="integer") ! * @ORM\Id ! * @ORM\GeneratedValue(strategy="AUTO") ! */ ! protected $id; ! ! /** ! * @var string $title ! * ! * @ORM\Column(name="title", type="string", length=150, nullable=true) ! * ! * @Assert\MaxLength(150) ! */ ! protected $title;

re-use�� of�� docblocks

On docblocks vs. comments

T_COMMENT

// this is a comment /* This is a multiline comment */

T_COMMENT

T_DOC_COMMENT

/** ! * this is a docblock! */

T_COMMENT

T_DOC_COMMENT

ignored�� by�� opcode�� cache

T_COMMENT

T_DOC_COMMENT

ignored�� by�� opcode�� cache

cached�� by�� opcode�� cache

class Reward !{ ! /** ! * @var integer $id ! * @deprecated! * @ORM\Column(name="id", type="integer") ! * @ORM\Id ! */ ! protected $id;

marker

parameterized

Why?Why�� sho

uld�� I�� use�� ann

otations?

Are�� annotations�� for�� you?

I don’t know.

hate�� annotations

love�� annotations

hate�� annotations

love�� annotations

never�� used�� annotations

Let’s have an argumentphoto by Adam Arroyo

photo by Adam Arroyo

its code and its in my comment blocks

they are docblocks

docblocks are first-class citizens

they are docblocks

“Annotations and comments are like water and oil, just because they are in the same container, does

not mean they mix”!

—- @rosstuck

its impossible to test or debug

annotations are tags and config

don’t test the annotation, test the object that uses it

annotations are tags and config

all that parsing, it can’t perform!

caching!

I ❤️ Annotations

I ❤️ AnnotationsContextualizes�� behavior/config�� in�� the�� object

In�� object�� vs.�� external�� configuration�� file

Its�� documented/stored�� by�� phpDocumentor

Its�� documented/stored�� by�� phpDocumentorIts�� in�� docblocks,�� so�� its�� parsed

class User!{!!!!!!!!protected $name!!!...!!!!!!!

-�� persist�� as�� varchar��

-�� length�� should�� not�� be��

more�� then�� 255��

-�� should�� not�� be�� blank��

-�� only�� letters

-�� persist�� as�� varchar��

-�� length�� should�� not�� be��

more�� then�� 255��

-�� should�� not�� be�� blank��

-�� only�� letters

MyProject\User:! properties:! name:! - NotBlank: ~! - MaxLength: 255

Validation

MyProject\User:! filters:! name:! - alpha

filter

MyProject\User:! type: entity! table: users! fields:! name:! type: string! length: 255

persistence

MyProject\User:! properties:! name:! - NotBlank: ~! - MaxLength: 255

Validation

MyProject\User:! filters:! name:! - alpha

filter

MyProject\User:! type: entity! table: users! fields:! name:! type: string! length: 255

persistence

/**! * @ORM\Column(‘string’, length=255)! * @Assert\NotBlank()! * @Assert\MaxLength(255)! * @Filter\Alpha()! */

Where?Where�� a

re�� annotatio

ns�� used?

Where?Where�� a

re�� annotatio

ns�� used?

class DataTest extends PHPUnit_Framework_TestCase !{ ! /** ! * @dataProvider provider ! * ! * @expectedException InvalidArgumentException ! * @expectedExceptionMessage Right Message ! */ ! public function testAdd($a, $b, $c) ! { ! /* Test code */ ! } ! ! public function provider() ! { ! return array( ! array(0, 0, 0), ! ); ! } !} !

expectations

repetition

/** ! * @ORM\Table("myentity") ! * @ORM\Entity(repositoryClass="MyEntityRepository") ! */ !class MyEntity !{ ! /** ! * @var integer $id ! * ! * @ORM\Column(name="id", type="integer") ! * @ORM\Id ! * @ORM\GeneratedValue(strategy="AUTO") ! */ ! protected $id; ! ! /** ! * @var string $title ! * ! * @ORM\Column(name="title", type="string", length=255) ! * @Assert\MaxLength(255) ! * @Assert\NotBlank() ! */ ! protected $title; ! ! /** ! * @var \Doctrine\Common\Collections\ArrayCollection $users ! * ! * @ORM\OneToMany(targetEntity="OtherEntity", mappedBy="myEntity", cascade={"persist","remove"}) ! */ ! protected $otherEntities; ! !}

persistance

association

/** ! * @Route("/myaction/{id}", name="myaction") ! * @Method("POST") ! * ! * @Template("MyBundle:MyController:my.html.twig") ! * ! * @param int $id ! * @return array ! */ !public function myAction($id) !{ ! ! /* Controller Logic */ ! ! return array('data' => $data); ! !} ! !!!class MyEntity !{ ! ! /** ! * @var string $title ! * ! * @ORM\Column(name="title", type="string", length=255) ! * @Assert\MaxLength(255) ! * @Assert\NotBlank() ! */ ! protected $title; ! !}!

routing

Validation

templating

/** ! * @FLOW3\Aspect ! */ !class LoggingAspect { ! ! /** ! * @FLOW3\Inject ! * @var \Examples\Forum\Logger\ApplicationLoggerInterface ! */ ! protected $applicationLogger; ! ! /** ! * Log a message if a post is deleted ! * ! * @param \TYPO3\FLOW3\AOP\JoinPointInterface $joinPoint ! * @FLOW3\Before("method(Examples\Forum\Domain\Model\Forum->deletePost())") ! * @return void ! */ ! public function logDeletePost(\TYPO3\FLOW3\AOP\JoinPointInterface $joinPoint) { ! $post = $joinPoint->getMethodArgument('post'); ! $this->applicationLogger->log('Removing post ' . $post->getTitle(), LOG_INFO); ! } ! !}!

Dependency�� Injection

How?How�� can�� i��

write�� my�� own��

annotations?

Annotations

My�� Project

Annotations

My�� ProjectAnnotation��

Engine

/**! * @tag(parameters)! */!public function method()

ReflectionClass->getDocComment()

DOCBlock

/**! * @tag(parameters)! */

DOCBlock

/**! * @tag(parameters)! */

Tag() + parameters

Annotation�� Instances

Doctrine�� Annotations

phpDocumentor�� 2

Annotation Engines

php-annotations

https://github.com/doctrine/annotations

https://github.com/phpDocumentor/phpDocumentor2

https://github.com/mindplay-dk/php-annotations

https://github.com/crodas/Notoj

Annotation Engines

php-annotations

Annotation Engines

php-annotations

0.16.1

Annotation Engines

php-annotations

0.16.1

Annotation Engines

php-annotations

0.16.1

doctrine/annotations

phpdocumentor/reflection-docblock

mindplay/annotations

crodas/notoj

Annotation Engines

php-annotations

0.16.1

crodas/notoj

Annotation Engines

php-annotations

0.16.1

full�� support

only�� string��

full�� support

crodas/notoj

Annotation Engines

php-annotations

0.16.1

full�� support

crodas/notoj

Annotation Engines

php-annotations

0.16.1

full�� support

crodas/notoj

How�� it�� Works

/**! * @ORM\Column(‘string’)! * @Assert\NotBlank()! */

use Doctrine\ORM\Mapping as ORM;!use Symfony\Component\Validator\! Constraints as Assert;

Declare�� which�� Annotations�� you�� will�� use

AnnotationReader<?php

new ORM\Column(‘string’)!new Assert\NotBlank()

“metadata”

new ORM\Column(‘string’)!new Assert\NotBlank()

“metadata”

Walker�� /�� code

Input Filtering

DMS\Filter: https://github.com/rdohms/DMS

Input Filtering

DMS\Filter: https://github.com/rdohms/DMS

With�� Annotation�� Support!

A short note on the word "filter"

Filters everywhere!

AnnotatedObject

@Filter\StripTags(‘’)

Rules:Rules are objects that represent the annotationsnew Rules\StripTags(‘’);

Filters:Filters are the executioners, they apply the effect of a rule$executioner = new Filter\StripTags();!$executioner->filter($metadata, $value);

Filter Service

Filter Service:Orchestrates the process of extracting values, filtering and replacing original values

Annotation Engine

Annotation Engine:Extracts string values into instances of rules for the Filter Service to parse

Filter Service

AnnotatedObject

Annotation Engine

Filter Service

AnnotatedObject

Annotation Engine

Hello World Hello World

The “rule”

<?php ! !namespace DMS\Filter\Rules; ! !/** ! * StripTags Rule ! * ! * @Annotation ! */ !class StripTags extends Rule !{ ! /** ! * String of allowed tags. Ex: <a> ! * ! * @var string ! */ ! public $allowed = null; ! ! /** ! * {@inheritDoc} ! */ ! public function getDefaultOption() ! { ! return 'allowed'; ! } !}

Usage:�� use DMS\Filter\Rules as Filter;!!@Filter\StripTags(‘’)

tell�� doctrine�� this�� is�� an�� annotation

DMS\Filter\Rules\Rule: !public function __construct($options = null)

/**! * @My\Annotation(“name”, nullable=true)! */

defaultProperty

new My\Annotation($options);

defaultProperty

array:�� key�� =>�� value�� or��

string:�� value

defaultProperty

string:�� value

defaultProperty

$a = new My\Annotation();!$a->nullable = true;!$a->{$a->getDefaultProperty()} = “name”;

string:�� value

defaultProperty

The “filter” or "executioner"

<?php ! !namespace DMS\Filter\Filters; ! !use DMS\Filter\Rules\Rule; ! !/** ! * StripTags Rule ! * ! * @package DMS ! * @subpackage Filter ! * ! * @Annotation ! */ !class StripTags extends BaseFilter !{ ! ! /** ! * {@inheritDoc} ! * ! * @param \DMS\Filter\Rules\StripTags $filter ! * @param mixed $filter ! */ ! public function apply( Rule $filter, $value) ! { ! return strip_tags($value, $filter->allowed); ! } !} !

Does�� the�� filtering

<?php ! !namespace DMS\Filter\Filters; ! !use DMS\Filter\Rules\Rule; ! !/** ! * StripTags Rule ! * ! * @package DMS ! * @subpackage Filter ! * ! * @Annotation ! */ !class StripTags extends BaseFilter !{ ! ! /** ! * {@inheritDoc} ! * ! * @param \DMS\Filter\Rules\StripTags $filter ! * @param mixed $filter ! */ ! public function apply( Rule $filter, $value) ! { ! return strip_tags($value, $filter->allowed); ! } !} !

Does�� the�� filtering

Rule�� has�� the�� configuration.Ex:�� allowed�� tags

The Filter Service

$service = new FilterService($reader);

Instantiate the service (DIC)

$service->filter($object);

Call for an object to be filtered

$reader->getPropertyAnnotations($object); //$a = array(Rule\StripTags(), Rule\Alpha());

The service uses the reader to read annotations and get the rule objects

$reader->getPropertyAnnotations($object); //$a = array(Rule\StripTags(), Rule\Alpha());

$object->prop = $filter->apply($rule, $object->prop);

The service uses the reader to read annotations and get the rule objects

Service resolves Rules into Filter objects, applies and overrides object

//new Filters\StripTags();

//Iterate over all annotations !foreach($this->reader->getPropertyAnnotations($property) as $rule) { ! ! //Skip is its not a rule ! if ( ! $rule instanceof Rules\Rule ) continue; ! ! //Add Rule ! $metadata->addPropertyRule($property->getName(), $rule); ! !}

get�� all�� annotation�� objects

filter�� out�� “our”�� annotations

glorified�� array

filter�� out�� “our”�� annotations

Necessary Object Calisthenics Disclaimer

FilterService

MetadataFactory ObjectWalker

Loader Cache

Reader ReflectionPropertyCache

//Get Doctrine Reader ! $reader = new Annotations\AnnotationReader(); ! $reader->setEnableParsePhpImports(true); ! ! //Load AnnotationLoader ! $loader = new Mapping\Loader\AnnotationLoader($reader); ! $this->loader = $loader; ! ! //Get a MetadataFactory ! $metadataFactory = new Mapping\ClassMetadataFactory($loader); ! ! //Get a Filter ! $filter = new DMS\Filter\Filter($metadataFactory); ! ! //Get your Entity ! $user = new App\Entity\User(); ! $user->name = "My name"; ! $user->email = " email@mail.com"; ! ! //Filter you entity ! $filter->filter($user); ! ! echo $user->name; //"My name" ! echo $user->email; //"email@mail.com" !

put�� this�� in�� your�� DIC

//Get Doctrine Reader ! $reader = new Annotations\AnnotationReader(); ! $reader->setEnableParsePhpImports(true); ! ! //Load AnnotationLoader ! $loader = new Mapping\Loader\AnnotationLoader($reader); ! $this->loader = $loader; ! ! //Get a MetadataFactory ! $metadataFactory = new Mapping\ClassMetadataFactory($loader); ! ! //Get a Filter ! $filter = new DMS\Filter\Filter($metadataFactory); ! ! //Get your Entity ! $user = new App\Entity\User(); ! $user->name = "My name"; ! $user->email = " email@mail.com"; ! ! //Filter you entity ! $filter->filter($user); ! ! echo $user->name; //"My name" ! echo $user->email; //"email@mail.com" !

Calling�� the�� Service

put�� this�� in�� your�� DIC

What? Why? Where?

Questions?

on�� twitterthese�� slides�� will�� be�� here

http://slides.doh.ms

http://doh.ms

@rdohms

https://joind.in/11694

annotations in php, they exist

class person

public byte image

public string prename

form of text

tomatoesim allergic

serial user group creatori

syntax rejectedrfc

Technology

book annotations

ms coco image and annotations coco-text annotations

please, feel free to interrupt me at any time. · use case...

dps annotations

making annotations

user manual - baum-software.ch · 12.1 insert annotations...

annotations - isis.apache.org · table of contents 1....

beam1 annotations

powerpoint annotations

@:annotations · annotations java, scala, kotlin, groovy...

php annotations: they exist! - jetbrains webinar

zak's annotations

h annotations

service component architecture for php · • components...

photograph annotations

lyrics & annotations

c++ annotations

jsr 308: type annotations making java annotations more...

annotations page

annotations bertrete