Annotating with Annotations - ForumPHP 2012

2. Forum

3. PHP

4. Paris

5. 2012Annotating

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.

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 noW ha t

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

44. In

45. 2004:

46. Metadata

47. or

48. “General

49. purpose

50. Annotations”

51. In

52. 2004:

53. Metadata

54. or

55. “General

56. purpose

57. Annotations” available

58. at

59. Runtime

60. using

61. Reflection

62. In

63. 2004:

64. Metadata

65. or

66. “General

67. purpose

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

69. at

70. Runtime

71. using

72. Reflection

73. In

74. 2004:

75. Metadata

76. or

77. “General

78. purpose

79. Annotations” specific

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

81. at

82. Runtime

83. using

84. Reflection

85. No

86. core

87. annotation

88. support

89. Questions?

90. Questions?I’m

91. kidding!

92. phpDoc~2000

93. PHP

94. 5.1 Reflection

95. supports

96. getDocComments()phpDoc~2000 2005

97. PHP

98. 5.1 Reflection

99. supports

100. getDocComments()phpDoc~2000 2005 First

101. Annotation

102. Engines

103. in

104. PHP

105. PHP

106. 5.1 Reflection

107. supports

108. getDocComments()phpDoc~2000 2005 2008 First

109. Annotation

110. Engines

111. in

112. PHP

113. PHP

114. 5.1 Reflection

115. supports

116. getDocComments()phpDoc~2000 2005 2008 First

117. Doctrine

118. 2

119. Annotation Annotation

120. Engine

121. Engines

122. in

123. PHP

124. PHP

125. 5.1 Reflection

126. supports

127. getDocComments() RFC:

128. Annotations

129. in

130. core

131. w/

132. custom

133. phpDoc syntax~2000 2005 2008 2010 First

134. Doctrine

135. 2

137. Engine

138. Engines

139. in

140. PHP

141. PHP

142. 5.1 Reflection

143. supports

144. getDocComments() RFC:

145. Annotations

146. ED CTustom

147. in

148. core

149. JE/

150. c wphpDoc E Rsyntax~2000 2005 2008 2010 First

151. Doctrine

152. 2

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 CTustom

167. in

168. core

169. JE/

170. c wphpDoc E Rsyntax~2000 2005 2008 2010 2011 First

171. Doctrine

172. 2

174. Engine

175. Engines

176. in

177. PHP

178. PHP

179. 5.1 RFC:

180. DocBlock

181. Reflection

182. supports

183. Annotations getDocComments() “in

184. discussion” RFC:

185. Annotations

186. ED CTustom

187. in

188. core

189. JE/

190. c wphpDoc E Rsyntax~2000 2005 2008 2010 2011 ? First

191. Doctrine

192. 2

194. Engine

195. Engines

196. in

197. PHP

198. PHP

199. 5.1 RFC:

200. DocBlock

201. Reflection

202. supports

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

204. discussion” * RFC:

205. Annotations

206. ED * @ORMTable(reward) CTustom

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

208. core

209. JE/

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

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

212. 2

214. Engine

215. Engines

216. in

217. PHP

218. Note:

219. Note://

220. This

221. is

222. a

223. comment T_COMMENT/*

224. This

225. is

226. a

227. multiline

228. comment

229. */

230. Note://

231. This

232. is

233. a

234. comment T_COMMENT/*

235. This

236. is

237. a

238. multiline

239. comment

240. *//**

242. *

243. This

244. is

245. a

246. doc

247. block T_DOC_COMMENT

248. */

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

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

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

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

253. an no tatio ns? uld

254. I

255. use /co ns? hy

256. sho e

257. p rosW t

258. are

259. th w ha

260. -

261. Harder

262. to

263. debug

264. (dynamic

265. code)-

266. Harder

267. to

268. debug

269. (dynamic

270. code)- Performance

271. hit

272. (non-native

273. code)

274. Harder

275. to

276. debug

277. (dynamic

278. code)- Performance

279. hit

280. (non-native

281. code) Its

282. implemented

283. in

284. comments

285. docblocks!

286. +

287. Easier

288. to

289. inject

290. behavior

291. without

292. extending+

293. Easier

294. to

295. inject

296. behavior

297. without

298. extending Doctrine

299. 1

300. vs

301. Doctrine

302. 2+

303. Easier

304. to

305. inject

306. behavior

307. without

309. 1

310. vs

311. Doctrine

312. 2 Contextualizes

313. behavior/config

314. in

315. the

316. object+

317. Easier

318. to

319. inject

320. behavior

321. without

323. 1

324. vs

325. Doctrine

328. in

329. the

330. object+ In

331. object

332. vs.

333. external

334. configuration

335. file

336. Easier

337. to

338. inject

339. behavior

340. without

342. 1

343. vs

344. Doctrine

347. in

348. the

349. object+ In

350. object

351. vs.

352. external

353. configuration

354. file Its

355. documented/stored

356. by

357. phpDocumentor

358. Easier

359. to

360. inject

361. behavior

362. without

364. 1

365. vs

366. Doctrine

369. in

370. the

371. object+ In

372. object

373. vs.

374. external

375. configuration

376. file Its

377. documented/stored

378. by

379. phpDocumentor Its

380. in

381. docblocks,

382. so

383. its

384. parsed

385. ?phpclass User{ protected $name ...}

386. ?php -

387. persist

388. as

389. varchar length

390. should

391. not

392. be

393. class User{ -

394. more

395. then

396. 255 -

397. should

398. not

399. be

400. blank -

401. only

402. letters protected $name ...}

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

404. persist

405. as

406. varchar type: integer length

407. should

408. not

409. be

410. class User generator:{ -

411. strategy: AUTO more

412. then

413. 255 fields: name: -

414. should

415. not

416. be

417. blank type: string -

418. only

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

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

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

422. used?

423. ann ota er e

424. areWh

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

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

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

428. /** Dependency

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

430. http://ecdesignrebels.blogspot.comH o w ? e

431. my

432. ow n

433. rit

434. i

435. w ns?How

436. can tio a nno ta

437. My

438. ProjectAnnotations

439. Annotation

440. Engine My

441. ProjectAnnotations

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

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

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

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

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

447. Instances

448. Annotation EnginesDoctrine

449. CommonsZF2

450. AnnotationsphpDocumentor

451. 2 abandoned?Notoj php-annotations addendum Stubble

452. Annotation Engines Notoj 2.3 2.0

453. -

454. alpha ?Parameterized marker parameterizedvery

455. mature maturing new

456. Annotation Engines Notoj 2.3 2.0

457. -

458. alpha ?Parameterized marker parameterizedvery

459. mature maturing new

460. How

461. it

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

463. How

464. it

465. Works Declare

466. which

467. Annotations

468. you

469. will

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

471. How

472. it

473. Works Declare

474. which

475. Annotations

476. you

477. will

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

479. How

480. it

481. Works Declare

482. which

483. Annotations

484. you

485. will

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

487. How

488. it

489. Works Declare

490. which

491. Annotations

492. you

493. will

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

495. /

496. code Cache

497. DMSFilterhttps://github.com/rdohms/DMS

498. The

499. Gears

500. The

501. Gears YourApp DoctrineCommons

502. The

503. Gears Reader YourApp DoctrineCommons

504. The

505. Gears Parsing Reader YourApp DoctrineCommons

506. The

507. Gears Parsing Filter Reader YourApp DoctrineCommons

508. The

509. Gears “Enforcing” Parsing Filter Reader YourApp DoctrineCommons

510. The

511. Gears “Enforcing” Parsing Filter ReaderAnnotatedObject YourApp DoctrineCommons

512. The

513. Gears “Enforcing” Parsing Filter ReaderAnnotatedObject MyAnnotation YourApp DoctrineCommons

514. The

515. Gears “Enforcing” Parsing Filter ReaderAnnotatedObject ﬁlter() MyAnnotation YourApp DoctrineCommons

516. The

517. Gears “Enforcing” Parsing Filter ReaderAnnotatedObject ﬁlter() getMethodAnnotation() MyAnnotation YourApp DoctrineCommons

518. The

519. Gears “Enforcing” Parsing Filter ReaderAnnotatedObject ﬁlter() getMethodAnnotation() MyAnnotation YourApp DoctrineCommons

520. The

521. Gears “Enforcing” Parsing Filter ReaderAnnotatedObject ﬁlter() getMethodAnnotation() ﬁltered value MyAnnotation YourApp DoctrineCommons

522. Usage:

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

524. Usage:

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

526. doctrine

527. this

528. */class NoDogs is

529. an

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

531. Usage:

533. doctrine

534. this

536. an

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

538. of

539. the

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

541. Usage:

543. doctrine

544. this

546. an

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

548. of

549. the

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

551. is

552. the

553. effect

554. of

555. our

556. annotation

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

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

559. only

560. our

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

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

563. only

564. our

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

566. Annotation

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

568. application

569. Taking

570. it

571. up

572. a

573. notch

574. Taking

575. it

576. up

577. a

578. notch Filter Reader

579. Taking

580. it

581. up

582. a

583. notch Filter Reader Walker Loader

584. Taking

585. it

586. up

587. a

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

589. Taking

590. it

591. up

592. a

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

594. Annotations

595. Taking

596. it

597. up

598. a

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

600. object,

601. Filters

602. Annotations reflects

603. and

604. filters

605. Taking

606. it

607. up

608. a

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

610. object,

611. Filters

613. and

614. filters

615. Taking

616. it

617. up

618. a

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

620. object,

621. Filters

623. and

624. filters

625. Taking

626. it

627. up

628. a

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

630. object,

631. Filters

633. and

634. filters

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

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

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

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

639. key

640. =

641. value or string:

642. valuenew MyAnnotation($options);

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

644. key

645. =