1. Annotations

2. in

3. PHP
Rafael

4. Dohms
@rdohms
They

5. Exist!
on

6. twitter

7. I’m a Brazilian, living in Amsterdam
which means I’m probably crazy,
and I speak with my hands

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

10. I’m a serial User Group creator
I can’t help it

11. I have absolutely no solid Laravel experience

12. I have absolutely no solid Laravel experience
I’m sorry.

13. I have absolutely no solid Laravel experience
I’m sorry.

14. I have absolutely no solid Laravel experience
I’m sorry.
Don’t throw tomatoes
photo by araswami

15. I have absolutely no solid Laravel experience
I’m sorry.
Don’t throw tomatoes
I’m allergic.
photo by araswami

16. existing

17. uses
What? Why? Where?
How?
a

18. little

19. history
Implementing

20. custom

21. annotations
based

22. on

23. DMSFilter
show

24. me

25. the

26. code!

27. what?
What

28. are

29. annotations?
http://ecdesignrebels.blogspot.com

30. -- In English --
An annotation is a note that is made while
reading any form of text.

31. something

32. that

33. describes

34. an

35. aspect

36. of

37. the

38. subject
-- In English --
An annotation is a note that is made while
reading any form of text.

39. -- In Code Speak --
“An annotation is metadata attached to your
code, that can be read at runtime.”
“Annotations do not directly affect program
semantics”

40. -- In Code Speak --
“An annotation is metadata attached to your
code, that can be read at runtime.”
effects

41. are

42. only

43. observed

44. at
“Annotations do not directly affect program
semantics”

45. -- In Code Speak --
“An annotation is metadata attached to your
code, that can be read at runtime.”
effects

46. are

47. only

48. observed

49. at
“Annotations do not directly affect program
semantics”
just

50. like

51. your

52. notes

53. Annotations in the wild
C#

54. Annotations in the wild
annotations
C#
attributes

55. Annotations in the wild
annotations
C#
attributes
@Entity!
@Table(name = people)!
class Person implements Serializable {!
@Id !
@GeneratedValue(strategy = GenerationType.AUTO) !
private Integer id;

56. 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; }

57. Annotations in the wild
annotations
after

58. v1.5
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; }

59. Annotations in the wild
annotations
after

60. v1.5
C#
attributes
since

61. first

62. 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; }

64. No

65. core

67.
annotation

68. support

69. Questions?

70. Questions?
I’m

71. kidding!

74. phpDoc
~2000

75. phpDoc
PHP

76. 5.1
Reflection

77. supports

78.
getDocComments()
~2000 2005

79. Reflection

80. supports

81.
getDocComments()
phpDoc
PHP

82. 5.1
~2000 2005
First

83.
Annotation

85. Engines

86. in

87. PHP

88. Reflection

89. supports

90.
getDocComments()
phpDoc
PHP

91. 5.1
~2000 2005 2008
First

92.
Annotation

94. Engines

95. in

96. PHP

97. Reflection

98. supports

99.
getDocComments()
phpDoc
PHP

100. 5.1
~2000 2005 2008
First

101.
Annotation

103. Engines

104. in

105. PHP
Doctrine

106. 2

107.
Annotation

108. Engine

109. Reflection

110. supports

111.
getDocComments()
phpDoc
PHP

112. 5.1
RFC:

113. Annotations

114.
in

115. core

116. w/

117. custom

118.
~2000 2005 2008
First

119.
Annotation

121. Engines

122. in

123. PHP
syntax
2010
Doctrine

124. 2

125.
Annotation

126. Engine

127. Reflection

128. supports

129.
getDocComments()
phpDoc
PHP

130. 5.1
syntax REJECTED
RFC:

131. Annotations

132.
in

133. core

134. w/

135. custom

136.
~2000 2005 2008
First

137.
Annotation

139. Engines

140. in

141. PHP
2010
Doctrine

142. 2

143.
Annotation

144. Engine

145. Reflection

146. supports

147.
getDocComments()
phpDoc
PHP

148. 5.1
RFC:

149. DocBlock

150.
Annotations

151.
“in

152. discussion”
REJECTED
RFC:

153. Annotations

154.
in

155. core

156. w/

157. custom

158.
~2000 2005 2008
First

159.
Annotation

161. Engines

162. in

163. PHP
syntax
2010
Doctrine

164. 2

165.
2011
Annotation

166. Engine

167. Reflection

168. supports

169.
getDocComments()
phpDoc
PHP

170. 5.1
RFC:

171. DocBlock

172.
Annotations

173.
“in

174. discussion”
REJECTED
RFC:

175. Annotations

176.
in

177. core

178. w/

179. custom

180.
~2000 2005 2008
First

181.
Annotation

183. Engines

184. in

185. PHP
syntax
2010
Doctrine

186. 2

187.
2011
Annotation

188. Engine
discussion

189.
sparks

190. up

191. again
2013

192. Reflection

193. supports

194.
getDocComments()
phpDoc
PHP

195. 5.1
RFC:

196. DocBlock

197.
Annotations

198.
“in

199. discussion”
REJECTED
RFC:

200. Annotations

201.
in

202. core

203. w/

204. custom

205.
~2000 2005 2008
First

206.
Annotation

208. Engines

209. in

210. PHP
syntax
2010
Doctrine

211. 2

212.
2011
Annotation

213. Engine
discussion

214.
sparks

215. up

216. again
? 2013

217. Current situation in php-internals

218. Current situation in php-internals

220. annotations

221. annotations
/** !
* EntityReward !
* !
* @ORMTable(reward) !
* @ORMEntity(repositoryClass=RewardRepository) !
*/ !
class Reward !
{ !
/** !
* @var integer $id !
* !
* @ORMColumn(name=id, type=integer) !
* @ORMId !
* @ORMGeneratedValue(strategy=AUTO) !
*/ !
protected $id; !
!
/** !
* @var string $title !
* !
* @ORMColumn(name=title, type=string, length=150, nullable=true) !
* !
* @AssertMaxLength(150) !
*/ !
protected $title;

222. annotations
re-use

223. of

224. docblocks
/** !
* EntityReward !
* !
* @ORMTable(reward) !
* @ORMEntity(repositoryClass=RewardRepository) !
*/ !
class Reward !
{ !
/** !
* @var integer $id !
* !
* @ORMColumn(name=id, type=integer) !
* @ORMId !
* @ORMGeneratedValue(strategy=AUTO) !
*/ !
protected $id; !
!
/** !
* @var string $title !
* !
* @ORMColumn(name=title, type=string, length=150, nullable=true) !
* !
* @AssertMaxLength(150) !
*/ !
protected $title;

225. On docblocks vs. comments

226. On docblocks vs. comments
// this is a comment
/* This is a multiline comment */
T_COMMENT

227. On docblocks vs. comments
// this is a comment
/* This is a multiline comment */
T_COMMENT
/** !
* this is a docblock!
*/
T_DOC_COMMENT

228. On docblocks vs. comments
ignored

229. by

230. opcode

231. cache
// this is a comment
/* This is a multiline comment */
T_COMMENT
/** !
* this is a docblock!
*/
T_DOC_COMMENT

232. On docblocks vs. comments
ignored

233. by

234. opcode

235. cache
// this is a comment
/* This is a multiline comment */
T_COMMENT
cached

236. by

237. opcode

238. cache
/** !
* this is a docblock!
*/
T_DOC_COMMENT

240. class Reward !
{ !
/** !
* @var integer $id !
* @deprecated!
* @ORMColumn(name=id, type=integer) !
* @ORMId !
*/ !
protected $id;
@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; }

241. class Reward !
{ !
/** !
* @var integer $id !
* @deprecated!
* @ORMColumn(name=id, type=integer) !
* @ORMId !
*/ !
protected $id;
@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; }
marker

242. class Reward !
{ !
/** !
* @var integer $id !
* @deprecated!
* @ORMColumn(name=id, type=integer) !
* @ORMId !
*/ !
protected $id;
@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; }
marker
parameterized

243. Why?
Why

244. should

245. I

246. use

247. annotations?
http://ecdesignrebels.blogspot.com
Are

248. annotations

249. for

250. you?

251. I don’t know.

253. hate

254.
annotations

255. hate

256.
annotations
love

257.
annotations

258. hate

259.
annotations
love

260.
annotations
never

261. used

262. annotations

263. Let’s have an argument
photo by Adam Arroyo

264. photo by Adam Arroyo

265. its code and its in my
comment blocks
photo by Adam Arroyo

266. its code and its in my
comment blocks
they are docblocks
photo by Adam Arroyo

267. its code and its in my
comment blocks
they are docblocks
docblocks are first-class
citizens
photo by Adam Arroyo

268. photo by Adam Arroyo

269. “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

270. photo by Adam Arroyo

271. its impossible to test
or debug
photo by Adam Arroyo

272. its impossible to test
or debug
annotations are
tags and config
photo by Adam Arroyo

273. its impossible to test
or debug
annotations are
tags and config
don’t test the
annotation, test the
object that uses it
photo by Adam Arroyo

274. photo by Adam Arroyo

275. all that parsing, it
can’t perform!
photo by Adam Arroyo

276. all that parsing, it
can’t perform!
caching!
photo by Adam Arroyo

277. I ❤️ Annotations

278. I ❤️ Annotations
Contextualizes

279. behavior/config

280. in

281. the

282. object

283. I ❤️ Annotations
Contextualizes

284. behavior/config

285. in

286. the

287. object
In

288. object

289. vs.

290. external

291. configuration

292. file

293. I ❤️ Annotations
Contextualizes

294. behavior/config

295. in

296. the

297. object
In

298. object

299. vs.

300. external

301. configuration

302. file
Its

303. documented/stored

304. by

305. phpDocumentor

306. I ❤️ Annotations
Contextualizes

307. behavior/config

308. in

309. the

310. object
In

311. object

312. vs.

313. external

314. configuration

315. file
Its

316. documented/stored

317. by

318. phpDocumentor
Its

319. in

320. docblocks,

321. so

322. its

323. parsed

326. ?php
class User!
{!
!!!!!!!
protected $name!
!!
...!
!!!!!!
}

327. ?php
class User!
{!
!!!!!!!
protected $name!
!!
...!
!!!!!!
}
-

328. persist

329. as

330. varchar

331.
-

332. length

333. should

334. not

335. be

337.
more

338. then

339. 255

340.
-

341. should

342. not

343. be

344. blank

345.
-

346. only

347. letters

348. ?php
class User!
{!
!!!!!!!
protected $name!
!!
...!
!!!!!!
}
-

349. persist

350. as

351. varchar

352.
-

353. length

354. should

355. not

356. be

358.
more

359. then

360. 255

361.
-

362. should

363. not

364. be

365. blank

366.
-

367. only

368. letters
persistence
MyProjectUser:!
type: entity!
table: users!
fields:!
name:!
type: string!
length: 255
Validation
MyProjectUser:!
properties:!
name:!
- NotBlank: ~!
- MaxLength: 255
filter
MyProjectUser:!
filters:!
name:!
- alpha

369. ?php
class User!
{!
!!!!!!!
protected $name!
!!
...!
!!!!!!
}
persistence
MyProjectUser:!
type: entity!
table: users!
fields:!
name:!
type: string!
length: 255
Validation
MyProjectUser:!
properties:!
name:!
- NotBlank: ~!
- MaxLength: 255
filter
MyProjectUser:!
filters:!
name:!
- alpha
/**!
* @ORMColumn(‘string’, length=255)!
* @AssertNotBlank()!
* @AssertMaxLength(255)!
* @FilterAlpha()!
*/

370. ?php
class User!
{!
!!!!!!!
protected $name!
!!
...!
!!!!!!
}
/**!
* @ORMColumn(‘string’, length=255)!
* @AssertNotBlank()!
* @AssertMaxLength(255)!
* @FilterAlpha()!
*/

371. Where?
Where

372. are

373. annotations

374. used?
http://ecdesignrebels.blogspot.com

375. Where?
Where

376. are

377. annotations

378. used?
http://ecdesignrebels.blogspot.com

379. 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), !
); !
} !
} !
repetition
expectations

380. /** !
* @ORMTable(myentity) !
* @ORMEntity(repositoryClass=MyEntityRepository) !
*/ !
class MyEntity !
{ !
/** !
* @var integer $id !
* !
* @ORMColumn(name=id, type=integer) !
* @ORMId !
* @ORMGeneratedValue(strategy=AUTO) !
*/ !
protected $id; !
!
/** !
* @var string $title !
* !
* @ORMColumn(name=title, type=string, length=255) !
* @AssertMaxLength(255) !
* @AssertNotBlank() !
*/ !
protected $title; !
!
/** !
* @var DoctrineCommonCollectionsArrayCollection $users !
* !
* @ORMOneToMany(targetEntity=OtherEntity, mappedBy=myEntity, cascade={persist,remove}) !
*/ !
protected $otherEntities; !
!
}
persistance
association

381. /** !
* @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 !
{ !
!
templating
/** !
* @var string $title !
* !
* @ORMColumn(name=title, type=string, length=255) !
* @AssertMaxLength(255) !
* @AssertNotBlank() !
*/ !
protected $title; !
!
}!
routing
Validation

382. /** !
* @FLOW3Aspect !
*/ !
class LoggingAspect { !
!
/** !
* @FLOW3Inject !
* @var ExamplesForumLoggerApplicationLoggerInterface !
*/ !
protected $applicationLogger; !
!
/** !
* Log a message if a post is deleted !
* !
* @param TYPO3FLOW3AOPJoinPointInterface $joinPoint !
* @FLOW3Before(method(ExamplesForumDomainModelForum-deletePost())) !
* @return void !
*/ !
public function logDeletePost(TYPO3FLOW3AOPJoinPointInterface $joinPoint) { !
$post = $joinPoint-getMethodArgument('post'); !
$this-applicationLogger-log('Removing post ' . $post-getTitle(), LOG_INFO); !
} !
!
}!
Dependency

383. Injection
AOP

384. How?
How

385. can

386. i

387. write

388. my

389. own

390.
annotations?
http://ecdesignrebels.blogspot.com

391. Annotations
My

392. Project

393. Annotations
My

394. Project
Annotation

396.
Engine

398. /**!
* @tag(parameters)!
*/!
public function method()
Code

399. /**!
* @tag(parameters)!
*/!
public function method()
Code
ReflectionClass-getDocComment()

400. /**!
* @tag(parameters)!
*/
DOCBlock
/**!
* @tag(parameters)!
*/!
public function method()
Code
ReflectionClass-getDocComment()

401. /**!
* @tag(parameters)!
*/
DOCBlock
/**!
* @tag(parameters)!
*/!
public function method()
Code
Tag() + parameters
Annotation

402. Instances
ReflectionClass-getDocComment()

403. Doctrine

404. Annotations
phpDocumentor

405. 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

406. Doctrine

407. Annotations
phpDocumentor

408. 2
Notoj
Annotation Engines
php-annotations

409. Doctrine

410. Annotations
phpDocumentor

411. 2
Notoj
Annotation Engines
php-annotations
1.1.2
2.0.2
1.1
0.16.1

412. Doctrine

413. Annotations
phpDocumentor

414. 2
Notoj
Annotation Engines
php-annotations
1.1.2
2.0.2
1.1
0.16.1

415. Doctrine

416. Annotations
phpDocumentor

417. 2
Notoj
Annotation Engines
php-annotations
1.1.2
doctrine/annotations
2.0.2
phpdocumentor/reflection-docblock
1.1
mindplay/annotations
0.16.1
crodas/notoj

418. Doctrine

419. Annotations
phpDocumentor

420. 2
Notoj
Annotation Engines
php-annotations
1.1.2
doctrine/annotations
2.0.2
phpdocumentor/reflection-docblock
1.1
mindplay/annotations
0.16.1
crodas/notoj

421. Doctrine

422. Annotations
phpDocumentor

423. 2
Notoj
Annotation Engines
php-annotations
1.1.2
2.0.2
1.1
0.16.1
full

424. support
only

425. string

426.
full

427. support
full

428. support
doctrine/annotations
phpdocumentor/reflection-docblock
mindplay/annotations
crodas/notoj

429. Doctrine

430. Annotations
phpDocumentor

431. 2
Notoj
Annotation Engines
php-annotations
1.1.2
2.0.2
1.1
0.16.1
full

432. support
only

433. string

434.
full

435. support
full

436. support
doctrine/annotations
phpdocumentor/reflection-docblock
mindplay/annotations
crodas/notoj

437. Doctrine

438. Annotations
phpDocumentor

439. 2
Notoj
Annotation Engines
php-annotations
1.1.2
2.0.2
1.1
0.16.1
full

440. support
only

441. string

442.
full

443. support
full

444. support
doctrine/annotations
phpdocumentor/reflection-docblock
mindplay/annotations
crodas/notoj

445. How

446. it

447. Works
?php
use DoctrineORMMapping as ORM;!
use SymfonyComponentValidator!
Constraints as Assert;
/**!
* @ORMColumn(‘string’)!
* @AssertNotBlank()!
*/

448. Declare

449. which

450. Annotations

451.
How

452. it

453. Works
?php
use DoctrineORMMapping as ORM;!
use SymfonyComponentValidator!
Constraints as Assert;
/**!
* @ORMColumn(‘string’)!
* @AssertNotBlank()!
*/
you

454. will

455. use

456. Declare

457. which

458.