php annotations: they exist! - jetbrains webinar

Rafael�� Dohms

Annotations�� in�� PHP

@rdohmson�� twitter

They�� Exist!

Evangelist, Speaker and Contributor.

!Enabler at AmsterdamPHP.

Rafael Dohms@rdohms

drop�� by�� if�� you�� are�� in�� Amsterdam!

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

but�� its�� code,�� in�� comments!docblocks

harder

The downside or why not

but�� its�� code,�� in�� comments!docblocks

harder

docblocks�� are�� first�� class�� citizens.

Its�� impossible�� to�� debug/test!

harder

Its�� impossible�� to�� debug/test!

harder

Test/debug�� annotation�� “executor”

It�� does�� not�� perform!

Caching�� FTW!

Why I love Annotations

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

Easier�� to�� inject�� behavior�� without�� extendingDoctrine�� 1�� vs�� Doctrine�� 2

Contextualizes�� behavior/config�� in�� the�� object

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

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!

Ingredients:

-�� Filter�� Rules-�� Filter�� Executioners�� -�� Filter�� Service�� -�� Annotation�� Engine�� -�� Annotated�� Objects

the�� annotation�� /�� metadata,�� configuration

applies�� the�� rules

the�� middle-man

gets�� the�� rules�� out�� of�� the�� docblocks

defines�� the�� rules

Filter�� Service

Filter�� EnforcerFiltered�� values

annotated�� object@Filter\StripTags(‘’)

$executioner = new Filter\StripTags();!$executioner->filter($metadata, $value);

Hello�� World

Hello�� World

“Configured”�� Rulesnew Rules\StripTags(‘’);

Annotation�� Engine

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 “enforcer”

<?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

The�� Life�� of�� a�� Filter�� Service

09:00 - DIC wake-up call new FilterService($reader);

09:00 - DIC wake-up call

09:05 - Reply to emergency filter call

new FilterService($reader);

$service->filter($object);

09:06 - Get Annotations for properties

$reader->getPropertyAnnotations($p); $a = array(StripTags(), Alpha());

09:07 - Track down the Filters

new Filters\StripTags();

09:08 - Get values filtered

$filter->apply($rule, $value);

09:10 - Update the object with new data

$object->prop = $newValue;

09:11 - send the object on its way

return $object;

09:12 - DO IT ALL AGAIN!

return $object;

09:12 - DO IT ALL AGAIN!

//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?

http://plugins.jetbrains.com/plugin/7320?pr=phpStorm

PHP Annotations Pluginby Daniel Espendiller

Questions?

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

http://slides.doh.ms

http://doh.ms

@rdohms

php annotations: they exist! - jetbrains webinar

external configuration

extending

public class

love annotations

private integer

comment

public byte

class reward

Technology

exploring .net memory management - jetbrains webinar

newspaper annotations

sap - abap programming model for sap fiori ·...

service component architecture for php · • components...

ms coco image and annotations coco-text annotations

java at fujitsu - java community process · pdf filespecjbb...

annotations in php - confoo 2013

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

java annotations tutorial - it...

refactoring lightning-smart - jetbrains · lightning-smart...

«Отладка в python 3.6: Быстрее, Выше,...

c++ annotations

language workbench challenge 2016: the jetbrains meta...

kotlin: a pragmatic language by jetbrains

annotations · table of contents 1. annotations

jetbrains resharper

the most intelligent java ide - jetbrains :: world's leading

real world java 9 - jetbrains webinar

jetpoint meeting @jetbrains on bioinformatics

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