1. *

2. Forum

3. PHP

4. Paris

5. 2012
Annotating

6. with

7.
Annotations
A

8. look

9. into

10. Annotations

11. in

12. PHP
on

13. twitter Rafael

14. Dohms
@rdohms

15. Rafael Dohms
photo credit: Eli White
@rdohms
Evangelist, Speaker and
Contributor.
Podcaster, User Group
Leader.
Developer at WEBclusive.

16. a

17. little

18. history existing

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

20. ann otations
Impl ementing

21. c DMSFilter
based

22. on

23.
show

24. me

25. the

26. code!

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

28. an no
W ha t

29. a

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 describes behavior of code and
affects your application in runtime.”
“Annotations do not directly affect program
semantics”

40. -- In Code Speak --
“An annotation describes behavior of code and
affects your application in runtime.”
“Annotations do not directly affect program
semantics”
just

41. like

42. your

43. notes

45. In

46. 2004:

47. Metadata

48. or

49.
“General

50. purpose

51. Annotations”

52. In

53. 2004:

54. Metadata

55. or

56.
“General

57. purpose

58. Annotations”
available

59. at

60. Runtime

61. using

62. Reflection

63. In

64. 2004:

65. Metadata

66. or

67.
“General

68. purpose

69. Annotations”
@Entity
@Table(name = people)
class Person implements Serializable {
@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Integer id;
@Column(length = 32)
private String name;
available

70. at

71. Runtime

72. using

73. Reflection

74. In

75. 2004:

76. Metadata

77. or

78.
“General

79. purpose

80. Annotations”
specific

81. syntax
@Entity
@Table(name = people)
class Person implements Serializable {
@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Integer id;
@Column(length = 32)
private String name;
available

82. at

83. Runtime

84. using

85. Reflection

87. No

88. core

89.
annotation

90. support

91. Questions?

92. Questions?
I’m

93. kidding!

96. phpDoc
~2000

97. PHP

98. 5.1
Reflection

99. supports

100.
getDocComments()
phpDoc
~2000 2005

101. PHP

102. 5.1
Reflection

103. supports

104.
getDocComments()
phpDoc
~2000 2005
First

105.
Annotation

106. Engines

107. in

108. PHP

109. PHP

110. 5.1
Reflection

111. supports

112.
getDocComments()
phpDoc
~2000 2005 2008
First

113.
Annotation

114. Engines

115. in

116. PHP

117. PHP

118. 5.1
Reflection

119. supports

120.
getDocComments()
phpDoc
~2000 2005 2008
First

121.
Doctrine

122. 2

123.
Annotation
Annotation

124. Engine

125. Engines

126. in

127. PHP

128. PHP

129. 5.1
Reflection

130. supports

131.
getDocComments()
RFC:

132. Annotations

133.
in

134. core

135. w/

136. custom

137.
phpDoc syntax
~2000 2005 2008 2010
First

138.
Doctrine

139. 2

140.
Annotation
Annotation

141. Engine

142. Engines

143. in

144. PHP

145. PHP

146. 5.1
Reflection

147. supports

148.
getDocComments()
RFC:

149. Annotations

150. ED
CTustom

151.
in

152. core

153. JE/

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

155.
Doctrine

156. 2

157.
Annotation
Annotation

158. Engine

159. Engines

160. in

161. PHP

162. PHP

163. 5.1
RFC:

164. DocBlock

165.
Reflection

166. supports

167.
Annotations
getDocComments()
“in

168. discussion”
RFC:

169. Annotations

170. ED
CTustom

171.
in

172. core

173. JE/

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

175.
Doctrine

176. 2

177.
Annotation
Annotation

178. Engine

179. Engines

180. in

181. PHP

182. PHP

183. 5.1
RFC:

184. DocBlock

185.
Reflection

186. supports

187.
Annotations
getDocComments()
“in

188. discussion”
RFC:

189. Annotations

190. ED
CTustom

191.
in

192. core

193. JE/

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

195.
Doctrine

196. 2

197.
Annotation
Annotation

198. Engine

199. Engines

200. in

201. PHP

202. PHP

203. 5.1
RFC:

204. DocBlock

205.
Reflection

206. supports

207.
Annotations
getDocComments() /**
* CaasBundleFundingBundleEntityReward
“in

208. discussion”
*
RFC:

209. Annotations

210. ED
* @ORMTable(reward)
CTustom

211.
* @ORMEntity(repositoryClass=CaasBundleFundingBundleEntityRewardRepository)
*/
class Reward
in

212. core

213. JE/

214. c
w
E
{
phpDoc /**
Rsyntax
?
* @var integer $id
*
* @ORMColumn(name=id, type=integer)
* @ORMId
* @ORMGeneratedValue(strategy=AUTO)
~2000 */
protected $id; 2005 2008 2010 2011
/**
* @var string $title
*
* @ORMColumn(name=title, type=string, length=150, nullable=true)
*
First

215.
* @AssertMaxLength(150)
*/
protected $title;
Doctrine

216. 2

217.
Annotation
Annotation

218. Engine

219. Engines

220. in

221. PHP

222. Note:

223. Note:
//

224. This

225. is

226. a

227. comment
T_COMMENT
/*

228. This

229. is

230. a

231. multiline

232. comment

233. */

234. Note:
//

235. This

236. is

237. a

238. comment
T_COMMENT
/*

239. This

240. is

241. a

242. multiline

243. comment

244. */
/**

246. *

247. This

248. is

249. a

250. doc

251. block T_DOC_COMMENT

252. */

253. /**
* @deprecated
*
* @ORMColumn(‘string’, length=255)
*/
public function method()

254. marker
/**
* @deprecated
*
* @ORMColumn(‘string’, length=255)
*/
public function method()

255. marker
parameterized
/**
* @deprecated
*
* @ORMColumn(‘string’, length=255)
*/
public function method()

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

257. an no tatio ns?
uld

258. I

259. use /co ns?
hy

260. sho e

261. p ros
W
t

262. are

263. th
w ha

264. -

265. Harder

266. to

267. debug

268. (dynamic

269. code)
-

270. Harder

271. to

272. debug

273. (dynamic

274. code)
- Performance

275. hit

276. (non-native

277. code)

278. Harder

279. to

280. debug

281. (dynamic

282. code)
- Performance

283. hit

284. (non-native

285. code)
Its

286. implemented

287. in

288. comments

289. docblocks!

290. +

291. Easier

292. to

293. inject

294. behavior

295. without

296. extending
+

297. Easier

298. to

299. inject

300. behavior

301. without

302. extending
Doctrine

303. 1

304. vs

305. Doctrine

306. 2
+

307. Easier

308. to

309. inject

310. behavior

311. without

312. extending
Doctrine

313. 1

314. vs

315. Doctrine

316. 2
Contextualizes

317. behavior/config

318. in

319. the

320. object
+

321. Easier

322. to

323. inject

324. behavior

325. without

326. extending
Doctrine

327. 1

328. vs

329. Doctrine

330. 2
Contextualizes

331. behavior/config

332. in

333. the

334. object
+ In

335. object

336. vs.

337. external

338. configuration

339. file

340. Easier

341. to

342. inject

343. behavior

344. without

345. extending
Doctrine

346. 1

347. vs

348. Doctrine

349. 2
Contextualizes

350. behavior/config

351. in

352. the

353. object
+ In

354. object

355. vs.

356. external

357. configuration

358. file
Its

359. documented/stored

360. by

361. phpDocumentor

362. Easier

363. to

364. inject

365. behavior

366. without

367. extending
Doctrine

368. 1

369. vs

370. Doctrine

371. 2
Contextualizes

372. behavior/config

373. in

374. the

375. object
+ In

376. object

377. vs.

378. external

379. configuration

380. file
Its

381. documented/stored

382. by

383. phpDocumentor
Its

384. in

385. docblocks,

386. so

387. its

388. parsed

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

390. ?php
-

391. persist

392. as

393. varchar
length

394. should

395. not

396. be

397.
class User
{ -

398.
more

399. then

400. 255
-

401. should

402. not

403. be

404. blank
-

405. only

406. letters
protected $name
...
}

407. persistence
DoctrineTestsORMMappingUser:
type: entity
table: cms_users
?php id:
id:
-

408. persist

409. as

410. varchar type: integer
length

411. should

412. not

413. be

414.
class User generator:
{ -

415. strategy: AUTO
more

416. then

417. 255
fields:
name:
-

418. should

419. not

420. be

421. blank type: string
-

422. only

423. letters
length: 255
protected $name Validation
AcmeBlogBundleEntityAuthor:
properties:
name:
... - NotBlank: ~
- MaxLength: 255
filter
AcmeBlogBundleEntityAuthor:
} filters:
name:
- alpha

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

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

426. used?

427. ann ota
er e

428. are
Wh

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

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

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

433. /**
Dependency

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

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

436. my

437. ow n

438.
rit

439. i

440. w ns?
How

441. can tio
a nno ta

442. My

443. Project
Annotations

444. Annotation

445.
Engine
My

446. Project
Annotations

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

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

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

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

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

453. Instances

454. Annotation Engines
Doctrine

455. Commons
ZF2

456. Annotations
phpDocumentor

457. 2 abandoned?
Notoj php-annotations
addendum
Stubble

458. Annotation Engines
Notoj
2.3 2.0

459. -

460. alpha ?
Parameterized marker parameterized
very

461. mature maturing new

462. Annotation Engines
Notoj
2.3 2.0

463. -

464. alpha ?
Parameterized marker parameterized
very

465. mature maturing new

466. How

467. it

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

469. How

470. it

471. Works Declare

472. which

473. Annotations

474.
you

475. will

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

477. How

478. it

479. Works Declare

480. which

481. Annotations

482.
you

483. will

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

485. How

486. it

487. Works Declare

488. which

489. Annotations

490.
you

491. will

492. use
AnnotationReader
?php
use DoctrineORMMapping as ORM;
use SymfonyComponentValidator
Constraints as Assert;
/**
* @ORMColumn(‘string’)
* @AssertNotBlank()
“metadata” */
new ORMColumn(‘string’)
new AssertNotBlank()

493. How

494. it

495. Works Declare

496. which

497. Annotations

498.
you

499. will

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

501. /

502. code
Cache

503. DMSFilter
https://github.com/rdohms/DMS

504. The

505. Gears

506. The

507. Gears
YourApp DoctrineCommons

508. The

509. Gears
Reader
YourApp DoctrineCommons

510. The

511. Gears
Parsing
Reader
YourApp DoctrineCommons

512. The

513. Gears
Parsing
Filter Reader
YourApp DoctrineCommons

514. The

515. Gears
“Enforcing” Parsing
Filter Reader
YourApp DoctrineCommons

516. The

517. Gears
“Enforcing” Parsing
Filter Reader
AnnotatedObject
YourApp DoctrineCommons

518. The

519. Gears
“Enforcing” Parsing
Filter Reader
AnnotatedObject
MyAnnotation
YourApp DoctrineCommons

520. The

521. Gears
“Enforcing” Parsing
Filter Reader
AnnotatedObject filter()
MyAnnotation
YourApp DoctrineCommons

522. The

523. Gears
“Enforcing” Parsing
Filter Reader
AnnotatedObject filter() getMethodAnnotation()
MyAnnotation
YourApp DoctrineCommons

524. The

525. Gears
“Enforcing” Parsing
Filter Reader
AnnotatedObject filter() getMethodAnnotation()
MyAnnotation
YourApp DoctrineCommons

526. The

527. Gears
“Enforcing” Parsing
Filter Reader
AnnotatedObject filter() getMethodAnnotation()
filtered value
MyAnnotation
YourApp DoctrineCommons

528. Usage:

529. @FilterNoDogs()
namespace FilterRule;
/**
* @Annotation
*/
class NoDogs
{
public function __construct($options)
{
/* no options */
}
public function filter($value)
{
return str_replace(dogs, , (string) $value);
}
}

530. Usage:

531. @FilterNoDogs()
namespace FilterRule;
/**
* @Annotation
tell

532. doctrine

533. this

534.
*/
class NoDogs is

535. an

536. annotation
{
public function __construct($options)
{
/* no options */
}
public function filter($value)
{
return str_replace(dogs, , (string) $value);
}
}

537. Usage:

538. @FilterNoDogs()
namespace FilterRule;
/**
* @Annotation
tell

539. doctrine

540. this

541.
*/
class NoDogs is

542. an

543. annotation
{
public function __construct($options)
{
/* no options */
}
array

544. of

545. the

546. parameters
public function filter($value)
{
return str_replace(dogs, , (string) $value);
}
}

547. Usage:

548. @FilterNoDogs()
namespace FilterRule;
/**
* @Annotation
tell

549. doctrine

550. this

551.
*/
class NoDogs is

552. an

553. annotation
{
public function __construct($options)
{
/* no options */
}
array

554. of

555. the

556. parameters
public function filter($value)
{
return str_replace(dogs, , (string) $value);
}
}
this

557. is

558. the

559. effect

560. of

561.
our

562. annotation

563. namespace Filter;
class Filter
{
private $reader;
public function __construct(DoctrineCommonAnnotationsReader $reader)
{
$this-reader = $reader;
}
public function filter($object)
{
$reflectionObject = new ReflectionObject($object);
foreach ($reflectionObject-getProperties() as $reflectionProperty) {
$this-filterProperty($object, $reflectionProperty);
}
}
public function filterProperty($object, $reflectionProperty)
{
// fetch the @NoDog annotation from the annotation reader
$annotation = $this-reader-getMethodAnnotation(
$reflectionProperty, 'FilterRuleNoDog');
if (null !== $annotation) {
return;
}
$reflectionProperty-setAccessible(true);
$value = $reflectionProperty-getValue($object);
$filteredValue = $annotation-filter($value);
$reflectionProperty-setValue( $filteredValue );
}
}

564. namespace Filter;
class Filter
{
private $reader;
public function __construct(DoctrineCommonAnnotationsReader $reader)
{
$this-reader = $reader;
}
public function filter($object)
{
$reflectionObject = new ReflectionObject($object);
foreach ($reflectionObject-getProperties() as $reflectionProperty) {
$this-filterProperty($object, $reflectionProperty);
}
}
Get

565. only

566. our

567.
annotation
public function filterProperty($object, $reflectionProperty)
{
// fetch the @NoDog annotation from the annotation reader
$annotation = $this-reader-getMethodAnnotation(
$reflectionProperty, 'FilterRuleNoDog');
if (null !== $annotation) {
return;
}
$reflectionProperty-setAccessible(true);
$value = $reflectionProperty-getValue($object);
$filteredValue = $annotation-filter($value);
$reflectionProperty-setValue( $filteredValue );
}
}

568. namespace Filter;
class Filter
{
private $reader;
public function __construct(DoctrineCommonAnnotationsReader $reader)
{
$this-reader = $reader;
}
public function filter($object)
{
$reflectionObject = new ReflectionObject($object);
foreach ($reflectionObject-getProperties() as $reflectionProperty) {
$this-filterProperty($object, $reflectionProperty);
}
}
Get

569. only

570. our

571.
annotation
public function filterProperty($object, $reflectionProperty)
{
// fetch the @NoDog annotation from the annotation reader
$annotation = $this-reader-getMethodAnnotation(
$reflectionProperty, 'FilterRuleNoDog');
if (null !== $annotation) {
return;
}
$reflectionProperty-setAccessible(true);
$value = $reflectionProperty-getValue($object);
Make

572. Annotation

573.
$filteredValue = $annotation-filter($value);
$reflectionProperty-setValue( $filteredValue );
}
}
affect

574. application

575. Taking

576. it

577. up

578. a

579. notch

580. Taking

581. it

582. up

583. a

584. notch
Filter
Reader

585. Taking

586. it

587. up

588. a

589. notch
Filter
Reader Walker
Loader

590. Taking

591. it

592. up

593. a

594. notch
Filter
Parsing Using/Walking
Reader Walker
Loading
Loader

595. Taking

596. it

597. up

598. a

599. notch
Filter
Parsing Using/Walking
Reader Walker
Loading
Loader
Filters

600. Annotations

601. Taking

602. it

603. up

604. a

605. notch
Filter
Parsing Using/Walking
Reader Walker
Loading
Loader
navigates

606. object,

607.
Filters

608. Annotations reflects

609. and

610. filters

611. Taking

612. it

613. up

614. a

615. notch
Filter
Parsing Using/Walking
Reader Walker
Loading
Loader
navigates

616. object,

617.
Filters

618. Annotations reflects

619. and

620. filters

621. Taking

622. it

623. up

624. a

625. notch
Filter
Parsing Using/Walking
Reader Walker
Loading
Loader
annotations
navigates

626. object,

627.
Filters

628. Annotations reflects

629. and

630. filters

631. Taking

632. it

633. up

634. a

635. notch
Filter
Parsing Using/Walking
Reader Walker
Loading
Loader
annotations metadata
navigates

636. object,

637.
Filters

638. Annotations reflects

639. and

640. filters

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

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

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

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

645. key

646. =