annotations in php, they exist

154
Rafael Dohms Annotations in PHP @rdohms on twitter They Exist!

Upload: rafael-dohms

Post on 15-Jan-2015

2.736 views

Category:

Technology


1 download

DESCRIPTION

Annotations are more than phpdoc comments, they're a fully-featured way of including additional information alongside your code. We might have rejected an RFC to add support into the PHP core, but the community has embraced this tool anyway! This session shows you who is doing what with annotations, and will give you some ideas on how to use the existing tools in your own projects to keep life simple. Developers, architects and anyone responsible for the technical direction of an application should attend this session.

TRANSCRIPT

Page 1: Annotations in PHP, They Exist

Rafael����������� ������������������  Dohms

Annotations����������� ������������������  in����������� ������������������  PHP

@rdohmson����������� ������������������  twitter

They����������� ������������������  Exist!

Page 2: Annotations in PHP, They Exist

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

and I speak with my hands

Page 3: Annotations in PHP, They Exist
Page 4: Annotations in PHP, They Exist

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

Page 5: Annotations in PHP, They Exist

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

Page 6: Annotations in PHP, They Exist

I have absolutely no solid Laravel experience

Page 7: Annotations in PHP, They Exist

I have absolutely no solid Laravel experienceI’m sorry.

Page 8: Annotations in PHP, They Exist

I have absolutely no solid Laravel experienceI’m sorry.

Page 9: Annotations in PHP, They Exist

I have absolutely no solid Laravel experienceI’m sorry.

Don’t throw tomatoes

photo by araswami

Page 10: Annotations in PHP, They Exist

I have absolutely no solid Laravel experienceI’m sorry.

Don’t throw tomatoes

I’m allergic.

photo by araswami

Page 11: Annotations in PHP, They Exist

What? Why? Where?

How?

a����������� ������������������  little����������� ������������������  history

show����������� ������������������  me����������� ������������������  the����������� ������������������  code!

existing����������� ������������������  uses

Implementing����������� ������������������  custom����������� ������������������  annotations

based����������� ������������������  on����������� ������������������  DMS\Filter

Page 12: Annotations in PHP, They Exist

what?What����������� ������������������  ar

e����������� ������������������  annotation

s?

http://ecdesignrebels.blogspot.com

Page 13: Annotations in PHP, They Exist

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

reading any form of text."

Page 14: Annotations in PHP, They Exist

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

reading any form of text."

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

Page 15: Annotations in PHP, They Exist

“Annotations do not directly affect program semantics”

-- In Code Speak --

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

Page 16: Annotations in PHP, They Exist

“Annotations do not directly affect program semantics”

-- In Code Speak --

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

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

Page 17: Annotations in PHP, They Exist

“Annotations do not directly affect program semantics”

-- In Code Speak --

just����������� ������������������  like����������� ������������������  your����������� ������������������  notes

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

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

Page 18: Annotations in PHP, They Exist

Annotations in the wild

C#

Page 19: Annotations in PHP, They Exist

Annotations in the wild

annotations

C#attributes

Page 20: Annotations in PHP, They Exist

Annotations in the wild

annotations

C#attributes

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

Page 21: Annotations in PHP, They Exist

Annotations in the wild

annotations

C#attributes

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

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

Page 22: Annotations in PHP, They Exist

Annotations in the wild

annotations

C#attributes

after����������� ������������������  v1.5

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

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

Page 23: Annotations in PHP, They Exist

Annotations in the wild

annotations

C#attributes

after����������� ������������������  v1.5

since����������� ������������������  first����������� ������������������  release

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

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

Page 24: Annotations in PHP, They Exist
Page 25: Annotations in PHP, They Exist

No����������� ������������������  core����������� ������������������  ����������� ������������������  annotation����������� ������������������  support

Page 26: Annotations in PHP, They Exist

Questions?

Page 27: Annotations in PHP, They Exist

Questions?

I’m����������� ������������������  kidding!

Page 28: Annotations in PHP, They Exist
Page 29: Annotations in PHP, They Exist
Page 30: Annotations in PHP, They Exist

phpDoc

~2000

Page 31: Annotations in PHP, They Exist

phpDoc

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

~2000 2005

Page 32: Annotations in PHP, They Exist

First����������� ������������������  Annotation����������� ������������������  

����������� ������������������  Engines����������� ������������������  in����������� ������������������  PHP

phpDoc

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

~2000 2005

Page 33: Annotations in PHP, They Exist

First����������� ������������������  Annotation����������� ������������������  

����������� ������������������  Engines����������� ������������������  in����������� ������������������  PHP

phpDoc

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

~2000 2005 2008

Page 34: Annotations in PHP, They Exist

First����������� ������������������  Annotation����������� ������������������  

����������� ������������������  Engines����������� ������������������  in����������� ������������������  PHP

phpDoc

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

~2000 2005 2008

Doctrine����������� ������������������  2����������� ������������������  Annotation����������� ������������������  Engine

Page 35: Annotations in PHP, They Exist

First����������� ������������������  Annotation����������� ������������������  

����������� ������������������  Engines����������� ������������������  in����������� ������������������  PHP

phpDoc

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

~2000 2005 2008

Doctrine����������� ������������������  2����������� ������������������  Annotation����������� ������������������  Engine

2010

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

syntax

Page 36: Annotations in PHP, They Exist

First����������� ������������������  Annotation����������� ������������������  

����������� ������������������  Engines����������� ������������������  in����������� ������������������  PHP

phpDoc

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

~2000 2005 2008

Doctrine����������� ������������������  2����������� ������������������  Annotation����������� ������������������  Engine

2010

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

syntaxREJECTED

Page 37: Annotations in PHP, They Exist

First����������� ������������������  Annotation����������� ������������������  

����������� ������������������  Engines����������� ������������������  in����������� ������������������  PHP

phpDoc

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

~2000 2005 2008

Doctrine����������� ������������������  2����������� ������������������  Annotation����������� ������������������  Engine

2010

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

syntax

2011

RFC:����������� ������������������  DocBlock����������� ������������������  Annotations����������� ������������������  

“in����������� ������������������  discussion”

REJECTED

Page 38: Annotations in PHP, They Exist

First����������� ������������������  Annotation����������� ������������������  

����������� ������������������  Engines����������� ������������������  in����������� ������������������  PHP

phpDoc

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

~2000 2005 2008

Doctrine����������� ������������������  2����������� ������������������  Annotation����������� ������������������  Engine

2010

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

syntax

2011

RFC:����������� ������������������  DocBlock����������� ������������������  Annotations����������� ������������������  

“in����������� ������������������  discussion”

REJECTED

2013

discussion����������� ������������������  sparks����������� ������������������  up����������� ������������������  again

Page 39: Annotations in PHP, They Exist

First����������� ������������������  Annotation����������� ������������������  

����������� ������������������  Engines����������� ������������������  in����������� ������������������  PHP

phpDoc

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

~2000 2005 2008

Doctrine����������� ������������������  2����������� ������������������  Annotation����������� ������������������  Engine

2010

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

syntax

2011

RFC:����������� ������������������  DocBlock����������� ������������������  Annotations����������� ������������������  

“in����������� ������������������  discussion”

REJECTED

?2013

discussion����������� ������������������  sparks����������� ������������������  up����������� ������������������  again

Page 40: Annotations in PHP, They Exist

Current situation in php-internals

Page 41: Annotations in PHP, They Exist

Current situation in php-internals

Page 42: Annotations in PHP, They Exist
Page 43: Annotations in PHP, They Exist

annotations

Page 44: Annotations in PHP, They Exist

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;

Page 45: Annotations in PHP, They Exist

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

Page 46: Annotations in PHP, They Exist

On docblocks vs. comments

Page 47: Annotations in PHP, They Exist

On docblocks vs. comments

T_COMMENT

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

Page 48: Annotations in PHP, They Exist

On docblocks vs. comments

T_COMMENT

T_DOC_COMMENT

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

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

Page 49: Annotations in PHP, They Exist

On docblocks vs. comments

T_COMMENT

T_DOC_COMMENT

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

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

ignored����������� ������������������  by����������� ������������������  opcode����������� ������������������  cache

Page 50: Annotations in PHP, They Exist

On docblocks vs. comments

T_COMMENT

T_DOC_COMMENT

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

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

ignored����������� ������������������  by����������� ������������������  opcode����������� ������������������  cache

cached����������� ������������������  by����������� ������������������  opcode����������� ������������������  cache

Page 51: Annotations in PHP, They Exist
Page 52: Annotations in PHP, They Exist

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

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

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

Page 53: Annotations in PHP, They Exist

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

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

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

marker

Page 54: Annotations in PHP, They Exist

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

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

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

marker

parameterized

Page 55: Annotations in PHP, They Exist

Why?Why����������� ������������������  sho

uld����������� ������������������  I����������� ������������������  use����������� ������������������  ann

otations?

http://ecdesignrebels.blogspot.com

Are����������� ������������������  annotations����������� ������������������  for����������� ������������������  you?

Page 56: Annotations in PHP, They Exist

I don’t know.

Page 57: Annotations in PHP, They Exist
Page 58: Annotations in PHP, They Exist

hate����������� ������������������  annotations

Page 59: Annotations in PHP, They Exist

hate����������� ������������������  annotations

love����������� ������������������  annotations

Page 60: Annotations in PHP, They Exist

hate����������� ������������������  annotations

love����������� ������������������  annotations

never����������� ������������������  used����������� ������������������  annotations

Page 61: Annotations in PHP, They Exist

Let’s have an argumentphoto by Adam Arroyo

Page 62: Annotations in PHP, They Exist

photo by Adam Arroyo

Page 63: Annotations in PHP, They Exist

its code and its in my comment blocks

photo by Adam Arroyo

Page 64: Annotations in PHP, They Exist

its code and its in my comment blocks

they are docblocks

photo by Adam Arroyo

Page 65: Annotations in PHP, They Exist

its code and its in my comment blocks

docblocks are first-class citizens

they are docblocks

photo by Adam Arroyo

Page 66: Annotations in PHP, They Exist

photo by Adam Arroyo

Page 67: Annotations in PHP, They Exist

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

not mean they mix”!

—- @rosstuck

photo by Adam Arroyo

Page 68: Annotations in PHP, They Exist

photo by Adam Arroyo

Page 69: Annotations in PHP, They Exist

its impossible to test or debug

photo by Adam Arroyo

Page 70: Annotations in PHP, They Exist

its impossible to test or debug

annotations are tags and config

photo by Adam Arroyo

Page 71: Annotations in PHP, They Exist

its impossible to test or debug

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

annotations are tags and config

photo by Adam Arroyo

Page 72: Annotations in PHP, They Exist

photo by Adam Arroyo

Page 73: Annotations in PHP, They Exist

all that parsing, it can’t perform!

photo by Adam Arroyo

Page 74: Annotations in PHP, They Exist

all that parsing, it can’t perform!

caching!

photo by Adam Arroyo

Page 75: Annotations in PHP, They Exist

I ❤️ Annotations

Page 76: Annotations in PHP, They Exist

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

Page 77: Annotations in PHP, They Exist

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

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

Page 78: Annotations in PHP, They Exist

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

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

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

Page 79: Annotations in PHP, They Exist

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

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

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

Page 80: Annotations in PHP, They Exist
Page 81: Annotations in PHP, They Exist
Page 82: Annotations in PHP, They Exist

<?php

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

}

Page 83: Annotations in PHP, They Exist

<?php

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

}

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

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

more����������� ������������������  then����������� ������������������  255����������� ������������������  

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

-����������� ������������������  only����������� ������������������  letters

Page 84: Annotations in PHP, They Exist

<?php

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

}

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

Page 85: Annotations in PHP, They Exist

<?php

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

}

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()! */

Page 86: Annotations in PHP, They Exist

<?php

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

}

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

Page 87: Annotations in PHP, They Exist

Where?Where����������� ������������������  a

re����������� ������������������  annotatio

ns����������� ������������������  used?

http://ecdesignrebels.blogspot.com

Page 88: Annotations in PHP, They Exist

Where?Where����������� ������������������  a

re����������� ������������������  annotatio

ns����������� ������������������  used?

http://ecdesignrebels.blogspot.com

Page 89: Annotations in PHP, They Exist

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

Page 90: Annotations in PHP, They Exist

/** ! * @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

Page 91: Annotations in PHP, They Exist

/** ! * @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

Page 92: Annotations in PHP, They Exist

/** ! * @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

Page 93: Annotations in PHP, They Exist

How?How����������� ������������������  can����������� ������������������  i����������� ������������������  

write����������� ������������������  my����������� ������������������  own����������� ������������������  

annotations?

http://ecdesignrebels.blogspot.com

Page 94: Annotations in PHP, They Exist

Annotations

My����������� ������������������  Project

Page 95: Annotations in PHP, They Exist

Annotations

My����������� ������������������  ProjectAnnotation����������� ������������������  ����������� ������������������  

Engine

Page 96: Annotations in PHP, They Exist
Page 97: Annotations in PHP, They Exist

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

Code

Page 98: Annotations in PHP, They Exist

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

Code

ReflectionClass->getDocComment()

Page 99: Annotations in PHP, They Exist

DOCBlock

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

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

Code

ReflectionClass->getDocComment()

Page 100: Annotations in PHP, They Exist

DOCBlock

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

Tag() + parameters

Annotation����������� ������������������  Instances

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

Code

ReflectionClass->getDocComment()

Page 101: Annotations in PHP, They Exist

Doctrine����������� ������������������  Annotations

phpDocumentor����������� ������������������  2

Notoj

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

Page 102: Annotations in PHP, They Exist

Doctrine����������� ������������������  Annotations

phpDocumentor����������� ������������������  2

Notoj

Annotation Engines

php-annotations

Page 103: Annotations in PHP, They Exist

Doctrine����������� ������������������  Annotations

phpDocumentor����������� ������������������  2

Notoj

Annotation Engines

php-annotations

1.1.2

2.0.2

1.1

0.16.1

Page 104: Annotations in PHP, They Exist

Doctrine����������� ������������������  Annotations

phpDocumentor����������� ������������������  2

Notoj

Annotation Engines

php-annotations

1.1.2

2.0.2

1.1

0.16.1

Page 105: Annotations in PHP, They Exist

Doctrine����������� ������������������  Annotations

phpDocumentor����������� ������������������  2

Notoj

Annotation Engines

php-annotations

1.1.2

2.0.2

1.1

0.16.1

doctrine/annotations

phpdocumentor/reflection-docblock

mindplay/annotations

crodas/notoj

Page 106: Annotations in PHP, They Exist

Doctrine����������� ������������������  Annotations

phpDocumentor����������� ������������������  2

Notoj

Annotation Engines

php-annotations

1.1.2

2.0.2

1.1

0.16.1

doctrine/annotations

phpdocumentor/reflection-docblock

mindplay/annotations

crodas/notoj

Page 107: Annotations in PHP, They Exist

Doctrine����������� ������������������  Annotations

phpDocumentor����������� ������������������  2

Notoj

Annotation Engines

php-annotations

1.1.2

2.0.2

1.1

0.16.1

full����������� ������������������  support

only����������� ������������������  string����������� ������������������  

full����������� ������������������  support

full����������� ������������������  support

doctrine/annotations

phpdocumentor/reflection-docblock

mindplay/annotations

crodas/notoj

Page 108: Annotations in PHP, They Exist

Doctrine����������� ������������������  Annotations

phpDocumentor����������� ������������������  2

Notoj

Annotation Engines

php-annotations

1.1.2

2.0.2

1.1

0.16.1

full����������� ������������������  support

only����������� ������������������  string����������� ������������������  

full����������� ������������������  support

full����������� ������������������  support

doctrine/annotations

phpdocumentor/reflection-docblock

mindplay/annotations

crodas/notoj

Page 109: Annotations in PHP, They Exist

Doctrine����������� ������������������  Annotations

phpDocumentor����������� ������������������  2

Notoj

Annotation Engines

php-annotations

1.1.2

2.0.2

1.1

0.16.1

full����������� ������������������  support

only����������� ������������������  string����������� ������������������  

full����������� ������������������  support

full����������� ������������������  support

doctrine/annotations

phpdocumentor/reflection-docblock

mindplay/annotations

crodas/notoj

Page 110: Annotations in PHP, They Exist

How����������� ������������������  it����������� ������������������  Works

<?php

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

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

Page 111: Annotations in PHP, They Exist

How����������� ������������������  it����������� ������������������  Works

<?php

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

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

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

Page 112: Annotations in PHP, They Exist

How����������� ������������������  it����������� ������������������  Works

AnnotationReader<?php

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

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

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

Page 113: Annotations in PHP, They Exist

How����������� ������������������  it����������� ������������������  Works

AnnotationReader<?php

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

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

“metadata”

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

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

Page 114: Annotations in PHP, They Exist

How����������� ������������������  it����������� ������������������  Works

AnnotationReader<?php

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

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

Cache

“metadata”

Walker����������� ������������������  /����������� ������������������  code

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

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

Page 115: Annotations in PHP, They Exist

Input Filtering

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

Page 116: Annotations in PHP, They Exist

Input Filtering

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

With����������� ������������������  Annotation����������� ������������������  Support!

Page 117: Annotations in PHP, They Exist

A short note on the word "filter"

Filters everywhere!

Page 118: Annotations in PHP, They Exist

AnnotatedObject

@Filter\StripTags(‘<b><i>’)

Page 119: Annotations in PHP, They Exist

Rules:Rules are objects that represent the annotationsnew Rules\StripTags(‘<b><i>’);

Page 120: Annotations in PHP, They Exist

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

Page 121: Annotations in PHP, They Exist

Filter Service

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

Page 122: Annotations in PHP, They Exist

Annotation Engine

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

Page 123: Annotations in PHP, They Exist

Filter Service

AnnotatedObject

Annotation Engine

Page 124: Annotations in PHP, They Exist

Filter Service

AnnotatedObject

Annotation Engine

<p>Hello <b>World</b></p> Hello <b>World</b>

Page 125: Annotations in PHP, They Exist

The “rule”

Page 126: Annotations in PHP, They Exist

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

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

Page 127: Annotations in PHP, They Exist

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

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

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

Page 128: Annotations in PHP, They Exist

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

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

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

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

Page 129: Annotations in PHP, They Exist

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

Page 130: Annotations in PHP, They Exist

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

defaultProperty

Page 131: Annotations in PHP, They Exist

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

new My\Annotation($options);

defaultProperty

Page 132: Annotations in PHP, They Exist

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

new My\Annotation($options);

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

string:����������� ������������������  value

defaultProperty

Page 133: Annotations in PHP, They Exist

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

new My\Annotation($options);

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

string:����������� ������������������  value

defaultProperty

or

Page 134: Annotations in PHP, They Exist

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

new My\Annotation($options);

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

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

string:����������� ������������������  value

defaultProperty

or

Page 135: Annotations in PHP, They Exist

The “filter” or "executioner"

Page 136: Annotations in PHP, They Exist

<?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); ! } !} !

Page 137: Annotations in PHP, They Exist

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

Page 138: Annotations in PHP, They Exist

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

Page 139: Annotations in PHP, They Exist

The Filter Service

Page 140: Annotations in PHP, They Exist
Page 141: Annotations in PHP, They Exist

$service = new FilterService($reader);

Instantiate the service (DIC)

Page 142: Annotations in PHP, They Exist

$service = new FilterService($reader);

$service->filter($object);

Instantiate the service (DIC)

Call for an object to be filtered

Page 143: Annotations in PHP, They Exist

$service = new FilterService($reader);

$service->filter($object);

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

Instantiate the service (DIC)

Call for an object to be filtered

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

Page 144: Annotations in PHP, They Exist

$service = new FilterService($reader);

$service->filter($object);

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

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

Instantiate the service (DIC)

Call for an object to be filtered

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();

Page 145: Annotations in PHP, They Exist

//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); ! !}

Page 146: Annotations in PHP, They Exist

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

Page 147: Annotations in PHP, They Exist

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

Page 148: Annotations in PHP, They Exist

//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); ! !}

glorified����������� ������������������  array

get����������� ������������������  all����������� ������������������  annotation����������� ������������������  objects

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

Page 149: Annotations in PHP, They Exist

Necessary Object Calisthenics Disclaimer

FilterService

MetadataFactory ObjectWalker

Loader Cache

Reader ReflectionPropertyCache

Page 150: Annotations in PHP, They Exist

//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]" !

Page 151: Annotations in PHP, They Exist

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

Page 152: Annotations in PHP, They Exist

//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]" !

Calling����������� ������������������  the����������� ������������������  Service

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

Page 153: Annotations in PHP, They Exist

What? Why? Where?

How?

Page 154: Annotations in PHP, They Exist

Questions?

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

http://slides.doh.ms

http://doh.ms

@rdohms

https://joind.in/11694