1. *

2. PHPBenelux

3. -

4. Antwerp/2013
Annotations

5. in

6. PHP
y

7. E xist!
T he
on

8. twitter Rafael

9. Dohms
@rdohms

10. Rafael Dohms
photo credit: Eli White
@rdohms
Evangelist, Speaker and
Contributor.
Developer at WEBclusive.
Enabler at AmsterdamPHP.
we

11. make

12. awesome

13. crowd-funding

14. software!

15. a

16. little

17. history existing

18. uses
What? Why? Where?
How?
ustom

19. ann otations
Impl ementing

20. c DMSFilter
based

21. on

22.
show

23. me

24. the

25. code!

26. http://ecdesignrebels.blogspot.com
w h a t? ta tio ns?
re

27. an no
W ha t

28. a

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

30. something

31. that

32. describes

33. an

34. aspect

35. of

36. the

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

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

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

40. are

41. only

42. observed

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

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

45. are

46. only

47. observed

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

49. like

50. your

51. notes

52. Annotations in the wild
C#

53. annotations
Annotations in the wild
C#
attributes

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

55. @Entity
@Table(name = people)
class Person implements Serializable {
@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Integer id;
annotations
Annotations in the wild
public class Customer
C#
{
[Required]
[StringLength(50)]
public string Prename { get; set; }
[Column(TypeName = image)]
public byte[] Image { get; set; }
attributes

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

57. v1.5
Annotations in the wild
public class Customer
C#
{
[Required]
[StringLength(50)]
public string Prename { get; set; }
[Column(TypeName = image)]
public byte[] Image { get; set; }
attributes

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

59. v1.5
Annotations in the wild
public class Customer
C#
{
[Required]
[StringLength(50)]
public string Prename { get; set; }
[Column(TypeName = image)]
public byte[] Image { get; set; }
attributes
since

60. first

61. release

63. No

64. core

65.
annotation

66. support

67. Questions?

68. Questions?
I’m

69. kidding!

72. phpDoc
~2000

73. PHP

74. 5.1
Reflection

75. supports

76.
getDocComments()
phpDoc
~2000 2005

77. PHP

78. 5.1
Reflection

79. supports

80.
getDocComments()
phpDoc
~2000 2005
First

81.
Annotation

82. Engines

83. in

84. PHP

85. PHP

86. 5.1
Reflection

87. supports

88.
getDocComments()
phpDoc
~2000 2005 2008
First

89.
Annotation

90. Engines

91. in

92. PHP

93. PHP

94. 5.1
Reflection

95. supports

96.
getDocComments()
phpDoc
~2000 2005 2008
First

97.
Doctrine

98. 2

99.
Annotation
Annotation

100. Engine

101. Engines

102. in

103. PHP

104. PHP

105. 5.1
Reflection

106. supports

107.
getDocComments()
RFC:

108. Annotations

109.
in

110. core

111. w/

112. custom

113.
phpDoc syntax
~2000 2005 2008 2010
First

114.
Doctrine

115. 2

116.
Annotation
Annotation

117. Engine

118. Engines

119. in

120. PHP

121. PHP

122. 5.1
Reflection

123. supports

124.
getDocComments()
RFC:

125. Annotations

126. ED
CTustom

127.
in

128. core

129. JE/

130. c
w
phpDoc E
Rsyntax
~2000 2005 2008 2010
First

131.
Doctrine

132. 2

133.
Annotation
Annotation

134. Engine

135. Engines

136. in

137. PHP

138. PHP

139. 5.1
RFC:

140. DocBlock

141.
Reflection

142. supports

143.
Annotations
getDocComments()
“in

144. discussion”
RFC:

145. Annotations

146. ED
CTustom

147.
in

148. core

149. JE/

150. c
w
phpDoc E
Rsyntax
~2000 2005 2008 2010 2011
First

151.
Doctrine

152. 2

153.
Annotation
Annotation

154. Engine

155. Engines

156. in

157. PHP

158. PHP

159. 5.1
RFC:

160. DocBlock

161.
Reflection

162. supports

163.
Annotations
getDocComments()
“in

164. discussion”
RFC:

165. Annotations

166. ED
Tustom

167. discussion

168.
wC
in

169. core

170. JE/

171. c sparks

172. up

173. again
phpDoc E
Rsyntax
~2000 2005 2008 2010 2011 2013
First

174.
Doctrine

175. 2

176.
Annotation
Annotation

177. Engine

178. Engines

179. in

180. PHP

181. PHP

182. 5.1
RFC:

183. DocBlock

184.
Reflection

185. supports

186.
Annotations
getDocComments()
“in

187. discussion”
RFC:

188. Annotations

189. ED
Tustom

190. discussion

191.
wC
in

192. core

193. JE/

194. c sparks

195. up

196. again
phpDoc E
Rsyntax
~2000 2005 2008 2010 2011 2013 ?
First

197.
Doctrine

198. 2

199.
Annotation
Annotation

200. Engine

201. Engines

202. in

203. PHP

204. Current situation in php-internals

206. annotations

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

208. re-use

209. of

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

211. On docblocks vs. comments

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

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

214. On docblocks vs. comments
ignored

215. by

216. opcode

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

218. On docblocks vs. comments
ignored

219. by

220. opcode

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

222. by

223. opcode

224. cache
/**
* this is a docblock
*/
T_DOC_COMMENT

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

227. class Reward
{
/**
* @var integer $id
marker
* @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; }

228. class Reward
{
/**
* @var integer $id
marker
* @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;
parameterized
public class Customer
{
[Required]
[StringLength(50)]
public string Prename { get; set; }
[Column(TypeName = image)]
public byte[] Image { get; set; }

229. http://ecdesignrebels.blogspot.com
Wh y ?

230. an no tatio ns?
ld

231. I

232. use
hy

233. shou
W
Are

234. annotations

235. for

236. you?

237. I don’t know.

239. hate

240.
annotations

241. hate

242. love

243.
annotations annotations

244. hate

245. love

246.
annotations annotations
never

247. used

248. annotations

249. The downside or why not
but

250. its

251. code,

252. in

253. comments!
docblocks
harder

254. The downside or why not
but

255. its

256. code,

257. in

258. comments!
docblocks
harder
docblocks

259. are

260. first

261. class

262. citizens.

263. The downside or why not
harder
Its

264. impossible

265.
to

266. debug/test!

267. The downside or why not
harder Test/debug

268.
Its

269. impossible

270.
annotation

271.
to

272. debug/test!
“executor”

273. The downside or why not
It

274. does

275. not

276.
perform!

277. The downside or why not
It

278. does

279. not

280.
Caching

281. FTW!
perform!

282. Why I love Annotations

283. Why I love Annotations
Easier

284. to

285. inject

286. behavior

287. without

288. extending

289. Why I love Annotations
Easier

290. to

291. inject

292. behavior

293. without

294. extending
Doctrine

295. 1

296. vs

297. Doctrine

298. 2

299. Why I love Annotations
Easier

300. to

301. inject

302. behavior

303. without

304. extending
Doctrine

305. 1

306. vs

307. Doctrine

308. 2
Contextualizes

309. behavior/config

310. in

311. the

312. object

313. Why I love Annotations
Easier

314. to

315. inject

316. behavior

317. without

318. extending
Doctrine

319. 1

320. vs

321. Doctrine

322. 2
Contextualizes

323. behavior/config

324. in

325. the

326. object
In

327. object

328. vs.

329. external

330. configuration

331. file

332. Why I love Annotations
Easier

333. to

334. inject

335. behavior

336. without

337. extending
Doctrine

338. 1

339. vs

340. Doctrine

341. 2
Contextualizes

342. behavior/config

343. in

344. the

345. object
In

346. object

347. vs.

348. external

349. configuration

350. file
Its

351. documented/stored

352. by

353. phpDocumentor

354. Why I love Annotations
Easier

355. to

356. inject

357. behavior

358. without

359. extending
Doctrine

360. 1

361. vs

362. Doctrine

363. 2
Contextualizes

364. behavior/config

365. in

366. the

367. object
In

368. object

369. vs.

370. external

371. configuration

372. file
Its

373. documented/stored

374. by

375. phpDocumentor
Its

376. in

377. docblocks,

378. so

379. its

380. parsed

383. ?php
class User
{
protected $name
...
}

384. ?php
class User -

385. persist

386. as

387. varchar
e

388.
{ -

389. length

390. should

391. not

392. b
more

393. then

394. 255
-

395. should

396. not

397. be

398. blank
-

399. only

400. letters
protected $name
...
}

401. ?php persistence
-

402. persist

403. as

404. varchar
MyProjectUser:
class User type: entity
e

405.
-

406. length

407. should

408. not

409. b
table: users
{ fields:
more

410. then

411. 255 name:
-

412. should

413. not

414. be

415. blank
type: string
length: 255
-

416. only

417. letters
protected $name
Validation
MyProjectUser:
properties:
name:
- NotBlank: ~
... - MaxLength: 255
filter
MyProjectUser:
filters:
} name:
- alpha

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

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

420. ?
http://ecdesignrebels.blogspot.com
W h e r e tions

421. used?

422. ann ota
er e

423. are
Wh

424. ?
http://ecdesignrebels.blogspot.com
W h e r e tions

425. used?

426. ann ota
er e

427. are
Wh

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

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

430. /**
* @Route(/myaction/{id}, name=myaction)
* @Method(POST)
*
* @Template(MyBundle:MyController:my.html.twig)
*
* @param int $id
* @return array routing
*/
public function myAction($id)
{
/* Controller Logic */
templating
return array('data' = $data);
}
class MyEntity
{
/**
* @var string $title
*
* @ORMColumn(name=title, type=string, length=255)
* @AssertMaxLength(255)
* @AssertNotBlank()
*/
protected $title;
}
Validation

431. /**
Dependency

432. Injection
* @FLOW3Aspect
*/
class LoggingAspect {
/**
* @FLOW3Inject
* @var ExamplesForumLoggerApplicationLoggerInterface
AOP
*/
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);
}
}

433. http://ecdesignrebels.blogspot.com
H o w ? e

434. my

435. ow n

436.
rit

437. i

438. w ns?
How

439. can tio
a nno ta

440. My

441. Project
Annotations

442. My

443. Project
Annotation

444.
Engine
Annotations

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

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

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

449. /**
* @tag(parameters)
ReflectionClass-getDocComment() */
public function method()
Code
/**
* @tag(parameters)
*/
DOCBlock
Tag() + parameters
Annotation

450. Instances

451. Annotation Engines
Doctrine

452. Commons https://github.com/doctrine/common
phpDocumentor

453. 2 https://github.com/phpDocumentor/phpDocumentor2
php-annotations https://github.com/mindplay-dk/php-annotations
Notoj https://github.com/crodas/Notoj

454. Annotation Engines
Doctrine

455. Commons
phpDocumentor

456. 2
php-annotations
Notoj

457. Annotation Engines
Doctrine

458. Commons 2.3
phpDocumentor

459. 2 2.0
php-annotations 1.1
Notoj -

460. Annotation Engines
Doctrine

461. Commons 2.3
phpDocumentor

462. 2 2.0
php-annotations 1.1
Notoj -

463. Annotation Engines
Doctrine

464. Commons 2.3
phpDocumentor

465. 2 2.0
php-annotations 1.1
Notoj -

466. Annotation Engines
Doctrine

467. Commons 2.3 full

468. support
phpDocumentor

469. 2 2.0 only

470. string

471.
php-annotations 1.1 full

472. support
Notoj - full

473. support

474. Annotation Engines
Doctrine

475. Commons 2.3 full

476. support
phpDocumentor

477. 2 2.0 only

478. string

479.
php-annotations 1.1 full

480. support
Notoj - full

481. support

482. Annotation Engines
Doctrine

483. Commons 2.3 full

484. support
phpDocumentor

485. 2 2.0 only

486. string

487.
php-annotations 1.1 full

488. support
Notoj - full

489. support

490. Annotation Engines
Doctrine

491. Commons 2.3 full

492. support
phpDocumentor

493. 2 2.0 only

494. string

495.
php-annotations 1.1 full

496. support
Notoj - full

497. support

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

499. it

500. Works

501. Declare

502. which

503. Annotations

504.
?php
you

505. will

506. use
use DoctrineORMMapping as ORM;
use SymfonyComponentValidator
Constraints as Assert;
/**
* @ORMColumn(‘string’)
* @AssertNotBlank()
*/
How

507. it

508. Works

509. AnnotationReader Declare

510. which

511. Annotations

512.
?php
you

513. will

514. use
use DoctrineORMMapping as ORM;
use SymfonyComponentValidator
Constraints as Assert;
/**
* @ORMColumn(‘string’)
* @AssertNotBlank()
*/
How

515. it

516. Works

517. AnnotationReader Declare

518. which

519. Annotations

520.
?php
you

521. will

522. use
use DoctrineORMMapping as ORM;
use SymfonyComponentValidator
Constraints as Assert;
/**
* @ORMColumn(‘string’)
* @AssertNotBlank()
“metadata” */
new ORMColumn(‘string’)
new AssertNotBlank()
How

523. it

524. Works

525. AnnotationReader Declare

526. which

527. Annotations

528.
?php
you

529. will

530. use
use DoctrineORMMapping as ORM;
use SymfonyComponentValidator
Constraints as Assert;
/**
* @ORMColumn(‘string’)
* @AssertNotBlank()
“metadata” */
new ORMColumn(‘string’)
new AssertNotBlank()
Walker

531. /

532. code
Cache How

533. it

534. Works

535. Input Filtering
DMSFilter: https://github.com/rdohms/DMS

536. Input Filtering
With

537. Annotation

538. Support!
DMSFilter: https://github.com/rdohms/DMS

539. Ingredients:
-

540. Filter

541. Rules the

542. annotation

543. /

544. metadata,

545. configuration
-

546. Filter

547. Executioners applies

548. the

549. rules
-

550. Filter

551. Service the

552. middle-man
-

553. Annotation

554. Engine gets

555. the

556. rules

557. out

558. of

559. the

560. docblocks
-

561. Annotated

562. Objects defines

563. the

564. rules

565. annotated

566. object “Configured”

567. Rules
@FilterStripTags(‘bi’) new RulesStripTags(‘bi’);
pHello

568. bWorld/b/p
Filter

569. Service
Annotation

570. Engine
Filtered

571. values Filter

572. Enforcer
Hello

573. bWorld/b
$executioner = new FilterStripTags();
$executioner-filter($metadata, $value);

574. The “rule”

575. ?php Usage:

576.
namespace DMSFilterRules; use DMSFilterRules as Filter;
/** @FilterStripTags(‘bi’)
* StripTags Rule
*
* @Annotation
*/
class StripTags extends Rule
{
/**
* String of allowed tags. Ex: bia
*
* @var string
*/
public $allowed = null;
/**
* {@inheritDoc}
*/
public function getDefaultOption()
{
return 'allowed';
}
}

577. ?php Usage:

578.
namespace DMSFilterRules; use DMSFilterRules as Filter;
/** @FilterStripTags(‘bi’)
* StripTags Rule
*
* @Annotation
*/
class StripTags extends Rule
{
/**
* String of allowed tags. Ex: bia
*
* @var string
tell

579. doctrine

580. this

581.
*/
public $allowed = null; is

582. an

583. annotation
/**
* {@inheritDoc}
*/
public function getDefaultOption()
{
return 'allowed';
}
}

584. ?php Usage:

585.
namespace DMSFilterRules; use DMSFilterRules as Filter;
/** @FilterStripTags(‘bi’)
* StripTags Rule
*
* @Annotation
*/
class StripTags extends Rule
{
/**
* String of allowed tags. Ex: bia
*
* @var string
tell

586. doctrine

587. this

588.
*/
public $allowed = null; is

589. an

590. annotation
/**
* {@inheritDoc}
*/
public function getDefaultOption()
{
return 'allowed';
}
}
DMSFilterRulesRule:
public function __construct($options = null)

591. /**
* @MyAnnotation(“name”, nullable=true)
*/

592. defaultProperty
/**
* @MyAnnotation(“name”, nullable=true)
*/

593. defaultProperty
/**
* @MyAnnotation(“name”, nullable=true)
*/
new MyAnnotation($options);

594. defaultProperty
/**
* @MyAnnotation(“name”, nullable=true)
*/
array:

595. key

596. =