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

3. -

4. June

5. Meeting
Annotating

6. with

7.
Annotations
A

8. look

9. into

10. Annotations

11. in

12. PHP
on

13. twitter Rafael

14. Dohms
@rdohms

15. *

16. PHPBenelux

17. -

18. June

19. Meeting
Annotating

20. with

21.
Annotations
A

22. look

23. into

24. Annotations

25. in

26. PHP
on

27. twitter Rafael

28. Dohms
@rdohms

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

30. a

31. little

32. history existing

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

34. ann otations
Impl ementing

35. c DMSFilter
based

36. on

37.
show

38. me

39. the

40. code!

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

42. an no
W ha t

43. a

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

45. something

46. that

47. describes

48. an

49. aspect

50. of

51. the

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

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

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

55. like

56. your

57. notes

59. In

60. 2004:

61. Metadata

62. or

63.
“General

64. purpose

65. Annotations”

66. In

67. 2004:

68. Metadata

69. or

70.
“General

71. purpose

72. Annotations”
available

73. at

74. Runtime

75. using

76. Reflection

77. In

78. 2004:

79. Metadata

80. or

81.
“General

82. purpose

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

84. at

85. Runtime

86. using

87. Reflection

88. In

89. 2004:

90. Metadata

91. or

92.
“General

93. purpose

94. Annotations”
specific

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

96. at

97. Runtime

98. using

99. Reflection

101. No

102. core

103.
annotation

104. support

105. Questions?

106. Questions?
I’m

107. kidding!

110. phpDoc
~2000

111. PHP

112. 5.1
Reflection

113. supports

114.
getDocComments()
phpDoc
~2000 2005

115. PHP

116. 5.1
Reflection

117. supports

118.
getDocComments()
phpDoc
~2000 2005
First

119.
Annotation

120. Engines

121. in

122. PHP

123. PHP

124. 5.1
Reflection

125. supports

126.
getDocComments()
phpDoc
~2000 2005 2008
First

127.
Annotation

128. Engines

129. in

130. PHP

131. PHP

132. 5.1
Reflection

133. supports

134.
getDocComments()
phpDoc
~2000 2005 2008
First

135.
Doctrine

136. 2

137.
Annotation
Annotation

138. Engine

139. Engines

140. in

141. PHP

142. PHP

143. 5.1
Reflection

144. supports

145.
getDocComments()
RFC:

146. Annotations

147.
in

148. core

149. w/

150. custom

151.
phpDoc syntax
~2000 2005 2008 2010
First

152.
Doctrine

153. 2

154.
Annotation
Annotation

155. Engine

156. Engines

157. in

158. PHP

159. PHP

160. 5.1
Reflection

161. supports

162.
getDocComments()
RFC:

163. Annotations

164. ED
CTustom

165.
in

166. core

167. JE/

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

169.
Doctrine

170. 2

171.
Annotation
Annotation

172. Engine

173. Engines

174. in

175. PHP

176. PHP

177. 5.1
RFC:

178. DocBlock

179.
Reflection

180. supports

181.
Annotations
getDocComments()
“in

182. discussion”
RFC:

183. Annotations

184. ED
CTustom

185.
in

186. core

187. JE/

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

189.
Doctrine

190. 2

191.
Annotation
Annotation

192. Engine

193. Engines

194. in

195. PHP

196. PHP

197. 5.1
RFC:

198. DocBlock

199.
Reflection

200. supports

201.
Annotations
getDocComments()
“in

202. discussion”
RFC:

203. Annotations

204. ED
CTustom

205.
in

206. core

207. JE/

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

209.
Doctrine

210. 2

211.
Annotation
Annotation

212. Engine

213. Engines

214. in

215. PHP

216. PHP

217. 5.1
RFC:

218. DocBlock

219.
Reflection

220. supports

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

222. discussion”
*
RFC:

223. Annotations

224. ED
* @ORMTable(reward)
CTustom

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

226. core

227. JE/

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

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

230. 2

231.
Annotation
Annotation

232. Engine

233. Engines

234. in

235. PHP

236. Note:

237. Note:
//

238. This

239. is

240. a

241. comment
T_COMMENT
/*

242. This

243. is

244. a

245. multiline

246. comment

247. */

248. Note:
//

249. This

250. is

251. a

252. comment
T_COMMENT
/*

253. This

254. is

255. a

256. multiline

257. comment

258. */
/**

260. *

261. This

262. is

263. a

264. doc

265. block T_DOC_COMMENT

266. */

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

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

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

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

271. an no tatio ns?
uld

272. I

273. use /co ns?
hy

274. sho e

275. p ros
W
t

276. are

277. th
w ha

278. -

279. Harder

280. to

281. debug

282. (dynamic

283. code)
-

284. Harder

285. to

286. debug

287. (dynamic

288. code)
- Performance

289. hit

290. (non-native

291. code)

292. Harder

293. to

294. debug

295. (dynamic

296. code)
- Performance

297. hit

298. (non-native

299. code)
Its

300. implemented

301. in

302. comments

303. docblocks!

304. +

305. Easier

306. to

307. inject

308. behavior

309. without

310. extending
+

311. Easier

312. to

313. inject

314. behavior

315. without

316. extending
Doctrine

317. 1

318. vs

319. Doctrine

320. 2
+

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
+

335. Easier

336. to

337. inject

338. behavior

339. without

340. extending
Doctrine

341. 1

342. vs

343. Doctrine

344. 2
Contextualizes

345. behavior/config

346. in

347. the

348. object
+ In

349. object

350. vs.

351. external

352. configuration

353. file

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

376. Easier

377. to

378. inject

379. behavior

380. without

381. extending
Doctrine

382. 1

383. vs

384. Doctrine

385. 2
Contextualizes

386. behavior/config

387. in

388. the

389. object
+ In

390. object

391. vs.

392. external

393. configuration

394. file
Its

395. documented/stored

396. by

397. phpDocumentor
Its

398. in

399. docblocks,

400. so

401. its

402. 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. //Get Doctrine Reader
$reader = new AnnotationsAnnotationReader();
$reader-setEnableParsePhpImports(true);
//Load AnnotationLoader
$loader = new MappingLoaderAnnotationLoader($reader);
$this-loader = $loader;
//Get a MetadataFactory
$metadataFactory = new MappingClassMetadataFactory($loader);
//Get a Filter
$filter = new DMSFilterFilter($metadataFactory);
//Get your Entity
$user = new AppEntityUser();
$user-name = My bname/b;
$user-email = email@mail.com;
//Filter you entity
$filter-filter($user);
echo $user-name; //My name
echo $user-email; //email@mail.com

676. //Get Doctrine Reader
$reader = new AnnotationsAnnotationReader();
$reader-setEnableParsePhpImports(true);
put

677. this

678. in