Download pdf - Annotating with Annotations - PHPBenelux June/2012

A�� look�� into�� Annotations�� in�� PHP

Rafael�� Dohms

*�� PHPBenelux�� -�� June�� Meeting

Annotating�� with�� Annotations

@rdohmson�� twitter

A�� look�� into�� Annotations�� in�� PHP

Rafael�� Dohms

*�� PHPBenelux�� -�� June�� Meeting

Annotating�� with�� Annotations

@rdohmson�� twitter

phot

o cr

edit:

Eli W

hite

Evangelist, Speaker and Contributor.

Developer at WEBclusive.

Enabler at AmsterdamPHP.

Rafael Dohms@rdohms

What? Why? Where?

How?

a�� little�� history

show�� me�� the�� code!

existing�� uses

Implementing�� custom�� annotations

based�� on�� DMS\Filter

what?What�� ar

e�� annotation

s?

http://ecdesignrebels.blogspot.com

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

“An annotation describes behavior of code and affects your application in runtime.”

“Annotations do not directly affect program semantics”

-- In Code Speak --

“An annotation describes behavior of code and affects your application in runtime.”

“Annotations do not directly affect program semantics”

-- In Code Speak --

just�� like�� your�� notes

In�� 2004:�� Metadata�� or�� “General�� purpose�� Annotations”


available�� at�� Runtime�� using�� Reflection



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



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

specific�� syntax

No�� core�� annotation�� support

Questions?

Questions?

I’m�� kidding!

phpDoc

~2000

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


2010

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

syntax



phpDoc


~2000 2005 2008


2010


syntaxREJECTED



phpDoc


~2000 2005 2008


2010


syntax

2011

RFC:�� DocBlock�� Annotations

“in�� discussion”

REJECTED



phpDoc


~2000 2005 2008


2010


syntax

2011



REJECTED

?



phpDoc


~2000 2005 2008


2010


syntax

2011



REJECTED

?

/** * Caas\Bundle\FundingBundle\Entity\Reward * * @ORM\Table("reward") * @ORM\Entity(repositoryClass="Caas\Bundle\FundingBundle\Entity\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;

Note:

Note:

//�� This�� is�� a�� comment

/*�� This�� is�� a�� multiline�� comment�� */T_COMMENT

Note:

//�� This�� is�� a�� comment

/*�� This�� is�� a�� multiline�� comment�� */

/**�� *�� This�� is�� a�� doc�� block�� */

T_COMMENT

T_DOC_COMMENT

/** * @deprecated * * @ORM\Column(‘string’, length=255) */public function method()


marker


markerparameterized

Why?Why�� sho

uld�� I�� use�� ann

otations?


what�� are�� the��

pros/cons?



-

Harder�� to�� debug�� (dynamic�� code)

-


- Performance�� hit�� (non-native�� code)


Its�� implemented�� in�� comments�� docblocks!

- Performance�� hit�� (non-native�� code)

+

Easier�� to�� inject�� behavior�� without�� extending

+


+

Doctrine�� 1�� vs�� Doctrine�� 2


Contextualizes�� 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

<?php

class User{

protected $name

...

}

<?php

class User{

protected $name

...

}

-�� persist�� as�� varchar

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

more�� then�� 255

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

-�� only�� letters

<?php

class User{

protected $name

...

}

-�� persist�� as�� varchar

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

more�� then�� 255

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

-�� only�� letters

Acme\BlogBundle\Entity\Author: properties: name: - NotBlank: ~ - MaxLength: 255

Doctrine\Tests\ORM\Mapping\User: type: entity table: cms_users id: id: type: integer generator: strategy: AUTO fields: name: type: string length: 255

Acme\BlogBundle\Entity\Author: filters: name: - alpha

Validation

filter

persistence

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

class User{

protected $name

...

}

<?phpValidation

persistence

filter

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

AOP

How?How�� can�� i��

write�� my�� own��

annotations?




Annotations

My�� Project

Annotations

My�� Project

Annotation�� Engine

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

Code


Code

ReflectionClass->getDocComment()

DOCBlock

/** * @tag parameters */


Code


DOCBlock



Code


DOCBlock


Tag() + parameters

Annotation�� Instances


Code


Doctrine�� Commons

ZF2�� Annotations

phpDocumentor�� 2

php-annotationsaddendumStubble

abandoned?

Notoj

Annotation Engines

Annotation Engines

Notoj

2.3 2.0�� -�� alpha ?

Parameterized marker parameterized

very�� mature maturing new

Annotation Engines

Notoj

2.3 2.0�� -�� alpha ?

Parameterized marker parameterized

very�� mature maturing new

How�� it�� Works

<?php

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

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


<?php



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


AnnotationReader<?php







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

“metadata”






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

Cache

“metadata”

Walker�� /�� code



DMS\Filterhttps://github.com/rdohms/DMS

The�� Gears

The�� Gears

Doctrine\CommonsYourApp

The�� Gears

Reader


The�� Gears

Parsing

Reader


The�� Gears

Parsing

ReaderFilter


The�� Gears

Parsing“Enforcing”

ReaderFilter


The�� Gears


Reader

AnnotatedObject

Filter


The�� Gears


Reader

AnnotatedObject

Filter


MyAnnotation

The�� Gears


Reader

AnnotatedObject

Filter

filter()


MyAnnotation

The�� Gears


Reader

AnnotatedObject

Filter

getMethodAnnotation()filter()


MyAnnotation

The�� Gears


Reader

AnnotatedObject

Filter



MyAnnotation

The�� Gears


Reader

AnnotatedObject

Filter


filtered value


MyAnnotation

namespace Filter\Rule; /** * @Annotation */ class NoDogs { public function __construct($options) { /* no options */ } public function filter($value) { return str_replace("dogs", "", (string) $value); } }

Usage:�� @Filter\NoDogs()


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





array�� of�� the�� parameters




array�� of�� the�� parameters

this�� is�� the�� effect�� of�� our�� annotation

namespace Filter; class Filter { private $reader; public function __construct(Doctrine\Common\Annotations\Reader $reader) { $this->reader = $reader; } public function filter($object) { $reflectionObject = new \ReflectionObject($object); foreach ($reflectionObject->getProperties() as $reflectionProperty) { $this->filterProperty($object, $reflectionProperty); } } public function filterProperty($object, $reflectionProperty) { // fetch the @NoDog annotation from the annotation reader $annotation = $this->reader->getMethodAnnotation(

$reflectionProperty, 'Filter\Rule\NoDog'); if (null !== $annotation) { return; } $reflectionProperty->setAccessible(true); $value = $reflectionProperty->getValue($object); $filteredValue = $annotation->filter($value); $reflectionProperty->setValue( $filteredValue ); } }



Get�� only�� our�� annotation



Get�� only�� our�� annotation

Make�� Annotation�� affect�� application

Taking�� it�� up�� a�� notch


Reader

Filter


Reader

Loader

Walker

Filter


Parsing

Loading

Using/Walking

Reader

Loader

Walker

Filter


Parsing

Loading

Using/Walking

Reader

Loader

Walker

Filters�� Annotations

Filter


Parsing

Loading

Using/Walking

Reader

Loader

Walker

Filters�� Annotationsnavigates�� object,��

reflects�� and�� filters

Filter


Parsing

Loading

Using/Walking

Reader

Loader

Walker



Filter


Parsing

Loading

Using/Walking

Reader

Loader

Walker

annotations



Filter


Parsing

Loading

Using/Walking

Reader

Loader

Walker

annotations metadata



Filter

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


defaultProperty


new My\Annotation($options);

defaultProperty



array:�� key�� =>�� valueor

string:�� value

defaultProperty




string:�� value

defaultProperty

or



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


string:�� value

defaultProperty

or

//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 <b>name</b>"; $user->email = " [email protected]"; //Filter you entity $filter->filter($user); echo $user->name; //"My name" echo $user->email; //"[email protected]"


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


Calling�� the�� Enforcer

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

What? Why? Where?

How?

Questions?

http://doh.mshttp://slides.doh.ms

@rdohms

Rate�� this�� talk�� on�� Joind.in!

https://joind.in/6696

on�� twitter these�� slides�� will�� be�� here

please!

http://doh.ms

http://doh.ms

http://doh.ms

http://doh.ms

http://doh.ms

http://doh.ms