1. *

2. ConFoo

3. -

4. Montreal/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

205. Current situation in php-internals

207. annotations

208. /**
* 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;

209. re-use

210. of

211. 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;

212. On docblocks vs. comments

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

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

215. On docblocks vs. comments
ignored

216. by

217. opcode

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

219. On docblocks vs. comments
ignored

220. by

221. opcode

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

223. by

224. opcode

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

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

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;
public class Customer
{
[Required]
[StringLength(50)]
public string Prename { get; set; }
[Column(TypeName = image)]
public byte[] Image { get; set; }

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

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

231. an no tatio ns?
ld

232. I

233. use
hy

234. shou
W
Are

235. annotations

236. for

237. you?

238. I don’t know.

240. hate

241.
annotations

242. hate

243. love

244.
annotations annotations

245. hate

246. love

247.
annotations annotations
never

248. used

249. annotations

250. The downside or why not
but

251. its

252. code,

253. in

254. comments!
docblocks
harder

255. The downside or why not
but

256. its

257. code,

258. in

259. comments!
docblocks
harder
docblocks

260. are

261. first

262. class

263. citizens.

264. The downside or why not
harder
Its

265. impossible

266.
to

267. debug/test!

268. The downside or why not
harder Test/debug

269.
Its

270. impossible

271.
annotation

272.
to

273. debug/test!
“executor”

274. The downside or why not
It

275. does

276. not

277.
perform!

278. The downside or why not
It

279. does

280. not

281.
Caching

282. FTW!
perform!

283. Why I love Annotations

284. Why I love Annotations
Easier

285. to

286. inject

287. behavior

288. without

289. extending

290. Why I love Annotations
Easier

291. to

292. inject

293. behavior

294. without

295. extending
Doctrine

296. 1

297. vs

298. Doctrine

299. 2

300. Why I love Annotations
Easier

301. to

302. inject

303. behavior

304. without

305. extending
Doctrine

306. 1

307. vs

308. Doctrine

309. 2
Contextualizes

310. behavior/config

311. in

312. the

313. object

314. Why I love Annotations
Easier

315. to

316. inject

317. behavior

318. without

319. extending
Doctrine

320. 1

321. vs

322. Doctrine

323. 2
Contextualizes

324. behavior/config

325. in

326. the

327. object
In

328. object

329. vs.

330. external

331. configuration

332. file

333. Why I love Annotations
Easier

334. to

335. inject

336. behavior

337. without

338. extending
Doctrine

339. 1

340. vs

341. Doctrine

342. 2
Contextualizes

343. behavior/config

344. in

345. the

346. object
In

347. object

348. vs.

349. external

350. configuration

351. file
Its

352. documented/stored

353. by

354. phpDocumentor

355. Why I love Annotations
Easier

356. to

357. inject

358. behavior

359. without

360. extending
Doctrine

361. 1

362. vs

363. Doctrine

364. 2
Contextualizes

365. behavior/config

366. in

367. the

368. object
In

369. object

370. vs.

371. external

372. configuration

373. file
Its

374. documented/stored

375. by

376. phpDocumentor
Its

377. in

378. docblocks,

379. so

380. its

381. parsed

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

385. ?php
class User -

386. persist

387. as

388. varchar
e

389.
{ -

390. length

391. should

392. not

393. b
more

394. then

395. 255
-

396. should

397. not

398. be

399. blank
-

400. only

401. letters
protected $name
...
}

402. ?php persistence
-

403. persist

404. as

405. varchar
MyProjectUser:
class User type: entity
e

406.
-

407. length

408. should

409. not

410. b
table: users
{ fields:
more

411. then

412. 255 name:
-

413. should

414. not

415. be

416. blank
type: string
length: 255
-

417. only

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

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

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

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

422. used?

423. ann ota
er e

424. are
Wh

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

426. used?

427. ann ota
er e

428. are
Wh

429. 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),
);
}
}

430. /**
* @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;
}

431. /**
* @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

432. /**
Dependency

433. 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);
}
}

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

435. my

436. ow n

437.
rit

438. i

439. w ns?
How

440. can tio
a nno ta

441. My

442. Project
Annotations

443. My

444. Project
Annotation

445.
Engine
Annotations

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

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

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

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

451. Instances

452. Annotation Engines
Doctrine

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

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

455. Annotation Engines
Doctrine

456. Commons
phpDocumentor

457. 2
php-annotations
Notoj

458. Annotation Engines
Doctrine

459. Commons 2.3
phpDocumentor

460. 2 2.0
php-annotations 1.1
Notoj -

461. Annotation Engines
Doctrine

462. Commons 2.3
phpDocumentor

463. 2 2.0
php-annotations 1.1
Notoj -

464. Annotation Engines
Doctrine

465. Commons 2.3
phpDocumentor

466. 2 2.0
php-annotations 1.1
Notoj -

467. Annotation Engines
Doctrine

468. Commons 2.3 full

469. support
phpDocumentor

470. 2 2.0 only

471. string

472.
php-annotations 1.1 full

473. support
Notoj - full

474. support

475. Annotation Engines
Doctrine

476. Commons 2.3 full

477. support
phpDocumentor

478. 2 2.0 only

479. string

480.
php-annotations 1.1 full

481. support
Notoj - full

482. support

483. Annotation Engines
Doctrine

484. Commons 2.3 full

485. support
phpDocumentor

486. 2 2.0 only

487. string

488.
php-annotations 1.1 full

489. support
Notoj - full

490. support

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

492. it

493. Works

494. Declare

495. which

496. Annotations

497.
?php
you

498. will

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

500. it

501. Works

502. AnnotationReader Declare

503. which

504. Annotations

505.
?php
you

506. will

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

508. it

509. Works

510. AnnotationReader Declare

511. which

512. Annotations

513.
?php
you

514. will

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

516. it

517. Works

518. AnnotationReader Declare

519. which

520. Annotations

521.
?php
you

522. will

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

524. /

525. code
Cache How

526. it

527. Works

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

529. Input Filtering
With

530. Annotation

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

532. Ingredients:
-

533. Filter

534. Rules the

535. annotation

536. /

537. metadata,

538. configuration
-

539. Filter

540. Executioners applies

541. the

542. rules
-

543. Filter

544. Service the

545. middle-man
-

546. Annotation

547. Engine gets

548. the

549. rules

550. out

551. of

552. the

553. docblocks
-

554. Annotated

555. Objects defines

556. the

557. rules

558. annotated

559. object “Configured”

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

561. bWorld/b/p
Filter

562. Service
Annotation

563. Engine
Filtered

564. values Filter

565. Enforcer
Hello

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

567. The “rule”

568. ?php Usage:

569.
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';
}
}

570. ?php Usage:

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

572. doctrine

573. this

574.
*/
public $allowed = null; is

575. an

576. annotation
/**
* {@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';
}
}
DMSFilterRulesRule:
public function __construct($options = null)

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

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

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

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

588. key

589. =