What exactly are annotations? How can they change the way you code and make life simpler? Annotations allow you to implement new functionality into code using "notes" this allows you to easily maintain your own architecture but benefit from external tools. Let's look at how annotations are used today in PHP and how we can develop our own solutions based on the existing libraries.

1. *

2. Dutch

3. PHP

4. Conference

5. 2012

6. -

7. UnCon
Annotating

8. with

9.
Annotations
A

10. look

11. into

12. Annotations

13. in

14. PHP
on

15. twitter Rafael

16. Dohms
@rdohms

17. *

18. Forum

19. PHP

20. Paris

21. 2012
Annotating

22. with

23.
Annotations
A

24. look

25. into

26. Annotations

27. in

28. PHP
on

29. twitter Rafael

30. Dohms
@rdohms

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

32. a

33. little

34. history existing

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

36. ann otations
Impl ementing

37. c DMSFilter
based

38. on

39.
show

40. me

41. the

42. code!

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

44. an no
W ha t

45. a

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

47. something

48. that

49. describes

50. an

51. aspect

52. of

53. the

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

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

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

57. like

58. your

59. notes

61. In

62. 2004:

63. Metadata

64. or

65.
“General

66. purpose

67. Annotations”

68. In

69. 2004:

70. Metadata

71. or

72.
“General

73. purpose

74. Annotations”
available

75. at

76. Runtime

77. using

78. Reflection

79. In

80. 2004:

81. Metadata

82. or

83.
“General

84. purpose

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

86. at

87. Runtime

88. using

89. Reflection

90. In

91. 2004:

92. Metadata

93. or

94.
“General

95. purpose

96. Annotations”
specific

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

98. at

99. Runtime

100. using

101. Reflection

103. No

104. core

105.
annotation

106. support

107. Questions?

108. Questions?
I’m

109. kidding!

112. phpDoc
~2000

113. PHP

114. 5.1
Reflection

115. supports

116.
getDocComments()
phpDoc
~2000 2005

117. PHP

118. 5.1
Reflection

119. supports

120.
getDocComments()
phpDoc
~2000 2005
First

121.
Annotation

122. Engines

123. in

124. PHP

125. PHP

126. 5.1
Reflection

127. supports

128.
getDocComments()
phpDoc
~2000 2005 2008
First

129.
Annotation

130. Engines

131. in

132. PHP

133. PHP

134. 5.1
Reflection

135. supports

136.
getDocComments()
phpDoc
~2000 2005 2008
First

137.
Doctrine

138. 2

139.
Annotation
Annotation

140. Engine

141. Engines

142. in

143. PHP

144. PHP

145. 5.1
Reflection

146. supports

147.
getDocComments()
RFC:

148. Annotations

149.
in

150. core

151. w/

152. custom

153.
phpDoc syntax
~2000 2005 2008 2010
First

154.
Doctrine

155. 2

156.
Annotation
Annotation

157. Engine

158. Engines

159. in

160. PHP

161. PHP

162. 5.1
Reflection

163. supports

164.
getDocComments()
RFC:

165. Annotations

166. ED
CTustom

167.
in

168. core

169. JE/

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

171.
Doctrine

172. 2

173.
Annotation
Annotation

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
w
phpDoc E
Rsyntax
~2000 2005 2008 2010 2011
First

191.
Doctrine

192. 2

193.
Annotation
Annotation

194. Engine

195. Engines

196. in

197. PHP

198. PHP

199. 5.1
RFC:

200. DocBlock

201.
Reflection

202. supports

203.
Annotations
getDocComments()
“in

204. discussion”
RFC:

205. Annotations

206. ED
CTustom

207.
in

208. core

209. JE/

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

211.
Doctrine

212. 2

213.
Annotation
Annotation

214. Engine

215. Engines

216. in

217. PHP

218. PHP

219. 5.1
RFC:

220. DocBlock

221.
Reflection

222. supports

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

224. discussion”
*
RFC:

225. Annotations

226. ED
* @ORMTable(reward)
CTustom

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

228. core

229. JE/

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

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

232. 2

233.
Annotation
Annotation

234. Engine

235. Engines

236. in

237. PHP

238. Note:

239. Note:
//

240. This

241. is

242. a

243. comment
T_COMMENT
/*

244. This

245. is

246. a

247. multiline

248. comment

249. */

250. Note:
//

251. This

252. is

253. a

254. comment
T_COMMENT
/*

255. This

256. is

257. a

258. multiline

259. comment

260. */
/**

262. *

263. This

264. is

265. a

266. doc

267. block T_DOC_COMMENT

268. */

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

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

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

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

273. an no tatio ns?
uld

274. I

275. use /co ns?
hy

276. sho e

277. p ros
W
t

278. are

279. th
w ha

280. -

281. Harder

282. to

283. debug

284. (dynamic

285. code)
-

286. Harder

287. to

288. debug

289. (dynamic

290. code)
- Performance

291. hit

292. (non-native

293. code)

294. Harder

295. to

296. debug

297. (dynamic

298. code)
- Performance

299. hit

300. (non-native

301. code)
Its

302. implemented

303. in

304. comments

305. docblocks!

306. +

307. Easier

308. to

309. inject

310. behavior

311. without

312. extending
+

313. Easier

314. to

315. inject

316. behavior

317. without

318. extending
Doctrine

319. 1

320. vs

321. Doctrine

322. 2
+

323. Easier

324. to

325. inject

326. behavior

327. without

328. extending
Doctrine

329. 1

330. vs

331. Doctrine

332. 2
Contextualizes

333. behavior/config

334. in

335. the

336. object
+

337. Easier

338. to

339. inject

340. behavior

341. without

342. extending
Doctrine

343. 1

344. vs

345. Doctrine

346. 2
Contextualizes

347. behavior/config

348. in

349. the

350. object
+ In

351. object

352. vs.

353. external

354. configuration

355. file

356. Easier

357. to

358. inject

359. behavior

360. without

361. extending
Doctrine

362. 1

363. vs

364. Doctrine

365. 2
Contextualizes

366. behavior/config

367. in

368. the

369. object
+ In

370. object

371. vs.

372. external

373. configuration

374. file
Its

375. documented/stored

376. by

377. phpDocumentor

378. Easier

379. to

380. inject

381. behavior

382. without

383. extending
Doctrine

384. 1

385. vs

386. Doctrine

387. 2
Contextualizes

388. behavior/config

389. in

390. the

391. object
+ In

392. object

393. vs.

394. external

395. configuration

396. file
Its

397. documented/stored

398. by

399. phpDocumentor
Its

400. in

401. docblocks,

402. so

403. its

404. parsed

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

406. ?php
-

407. persist

408. as

409. varchar
length

410. should

411. not

412. be

413.
class User
{ -

414.
more

415. then

416. 255
-

417. should

418. not

419. be

420. blank
-

421. only

422. letters
protected $name
...
}

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

424. persist

425. as

426. varchar type: integer
length

427. should

428. not

429. be

430.
class User generator:
{ -

431. strategy: AUTO
more

432. then

433. 255
fields:
name:
-

434. should

435. not

436. be

437. blank type: string
-

438. only

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

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

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

442. used?

443. ann ota
er e

444. are
Wh

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

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

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

449. /**
Dependency

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

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

452. my

453. ow n

454.
rit

455. i

456. w ns?
How

457. can tio
a nno ta

458. My

459. Project
Annotations

460. Annotation

461.
Engine
My

462. Project
Annotations

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

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

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

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

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

469. Instances

470. Annotation Engines
Doctrine

471. Commons
ZF2

472. Annotations
phpDocumentor

473. 2 abandoned?
Notoj php-annotations
addendum
Stubble

474. Annotation Engines
Notoj
2.3 2.0

475. -

476. alpha ?
Parameterized marker parameterized
very

477. mature maturing new

478. Annotation Engines
Notoj
2.3 2.0

479. -

480. alpha ?
Parameterized marker parameterized
very

481. mature maturing new

482. How

483. it

484. Works
?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
?php
use DoctrineORMMapping as ORM;
use SymfonyComponentValidator
Constraints as Assert;
/**
* @ORMColumn(‘string’)
* @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()
*/

501. How

502. it

503. Works Declare

504. which

505. Annotations

506.
you

507. will

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

509. How

510. it

511. Works Declare

512. which

513. Annotations

514.
you

515. will

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

517. /

518. code
Cache

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

520. The

521. Gears

522. The

523. Gears
YourApp DoctrineCommons

524. The

525. Gears
Reader
YourApp DoctrineCommons

526. The

527. Gears
Parsing
Reader
YourApp DoctrineCommons

528. The

529. Gears
Parsing
Filter Reader
YourApp DoctrineCommons

530. The

531. Gears
“Enforcing” Parsing
Filter Reader
YourApp DoctrineCommons

532. The

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

534. The

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

536. The

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

538. The

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

540. The

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

542. The

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

544. Usage:

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

546. Usage:

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

548. doctrine

549. this

550.
*/
class NoDogs is

551. an

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

553. Usage:

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

555. doctrine

556. this

557.
*/
class NoDogs is

558. an

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

560. of

561. the

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

563. Usage:

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

565. doctrine

566. this

567.
*/
class NoDogs is

568. an

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

570. of

571. the

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

573. is

574. the

575. effect

576. of

577.
our

578. annotation

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

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

581. only

582. our

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

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

585. only

586. our

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

588. Annotation

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

590. application

591. Taking

592. it

593. up

594. a

595. notch

596. Taking

597. it

598. up

599. a

600. notch
Filter
Reader

601. Taking

602. it

603. up

604. a

605. notch
Filter
Reader Walker
Loader

606. Taking

607. it

608. up

609. a

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

611. Taking

612. it

613. up

614. a

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

616. Annotations

617. Taking

618. it

619. up

620. a

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

622. object,

623.
Filters

624. Annotations reflects

625. and

626. filters

627. Taking

628. it

629. up

630. a

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

632. object,

633.
Filters

634. Annotations reflects

635. and

636. filters

637. Taking

638. it

639. up

640. a

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

642. object,

643.
Filters

644. Annotations reflects

645. and

646. filters

647. Taking

648. it

649. up

650. a

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

652. object,

653.
Filters

654. Annotations reflects

655. and

656. filters

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

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

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

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

661. key

662. =

663. value
or
string:

664. value
new MyAnnotation($options);

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

666. key

667. =

668. value
or
string:

669. value
new MyAnnotation($options);
or

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

671. key

672. =

673. value
or
string:

674. value
new MyAnnotation($options);
or
$a = new MyAnnotation();
$a-nullable = true;
$a-{$a-getDefaultProperty()} = “name”;

675. DMSFilter
https://github.com/rdohms/DMS
/**
* FilterAlpha(true)
*/
Rafael

676. Dohms23
protected $name;
Alpha-filter($name);
Rafael

677. Dohms

678. What? Why? Where?
How?