Annotations are more than phpdoc comments, they're a fully-featured way of including additional information alongside your code. We might have rejected an RFC to add support into the PHP core, but the community has embraced this tool anyway! This session shows you who is doing what with annotations, and will give you some ideas on how to use the existing tools in your own projects to keep life simple. Developers, architects and anyone responsible for the technical direction of an application should attend this session.

1. *

2. TrueNorthPHP

3. -

4. Toronto/2012
Annotating

5. with

6.
Annotations
A

7. look

8. into

9. Annotations

10. in

11. PHP
on

12. twitter Rafael

13. Dohms
@rdohms

14. *

15. TrueNorthPHP

16. -

17. Toronto/2012
Annotating

18. with

19.
Annotations
A

20. look

21. into

22. Annotations

23. in

24. PHP
on

25. twitter Rafael

26. Dohms
@rdohms

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

28. a

29. little

30. history existing

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

32. ann otations
Impl ementing

33. c DMSFilter
based

34. on

35.
show

36. me

37. the

38. code!

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

40. an no
W ha t

41. a

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

43. something

44. that

45. describes

46. an

47. aspect

48. of

49. the

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

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

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

53. like

54. your

55. notes

57. In

58. 2004:

59. Metadata

60. or

61.
“General

62. purpose

63. Annotations”

64. In

65. 2004:

66. Metadata

67. or

68.
“General

69. purpose

70. Annotations”
available

71. at

72. Runtime

73. using

74. Reflection

75. In

76. 2004:

77. Metadata

78. or

79.
“General

80. purpose

81. Annotations”
@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

86. In

87. 2004:

88. Metadata

89. or

90.
“General

91. purpose

92. Annotations”
specific

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

94. at

95. Runtime

96. using

97. Reflection

99. No

100. core

101.
annotation

102. support

103. Questions?

104. Questions?
I’m

105. kidding!

108. phpDoc
~2000

109. PHP

110. 5.1
Reflection

111. supports

112.
getDocComments()
phpDoc
~2000 2005

113. PHP

114. 5.1
Reflection

115. supports

116.
getDocComments()
phpDoc
~2000 2005
First

117.
Annotation

118. Engines

119. in

120. PHP

121. PHP

122. 5.1
Reflection

123. supports

124.
getDocComments()
phpDoc
~2000 2005 2008
First

125.
Annotation

126. Engines

127. in

128. PHP

129. PHP

130. 5.1
Reflection

131. supports

132.
getDocComments()
phpDoc
~2000 2005 2008
First

133.
Doctrine

134. 2

135.
Annotation
Annotation

136. Engine

137. Engines

138. in

139. PHP

140. PHP

141. 5.1
Reflection

142. supports

143.
getDocComments()
RFC:

144. Annotations

145.
in

146. core

147. w/

148. custom

149.
phpDoc syntax
~2000 2005 2008 2010
First

150.
Doctrine

151. 2

152.
Annotation
Annotation

153. Engine

154. Engines

155. in

156. PHP

157. PHP

158. 5.1
Reflection

159. supports

160.
getDocComments()
RFC:

161. Annotations

162. ED
CTustom

163.
in

164. core

165. JE/

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

167.
Doctrine

168. 2

169.
Annotation
Annotation

170. Engine

171. Engines

172. in

173. PHP

174. PHP

175. 5.1
RFC:

176. DocBlock

177.
Reflection

178. supports

179.
Annotations
getDocComments()
“in

180. discussion”
RFC:

181. Annotations

182. ED
CTustom

183.
in

184. core

185. JE/

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

187.
Doctrine

188. 2

189.
Annotation
Annotation

190. Engine

191. Engines

192. in

193. PHP

194. PHP

195. 5.1
RFC:

196. DocBlock

197.
Reflection

198. supports

199.
Annotations
getDocComments()
“in

200. discussion”
RFC:

201. Annotations

202. ED
CTustom

203.
in

204. core

205. JE/

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

207.
Doctrine

208. 2

209.
Annotation
Annotation

210. Engine

211. Engines

212. in

213. PHP

214. PHP

215. 5.1
RFC:

216. DocBlock

217.
Reflection

218. supports

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

220. discussion”
*
RFC:

221. Annotations

222. ED
* @ORMTable(reward)
CTustom

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

224. core

225. JE/

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

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

228. 2

229.
Annotation
Annotation

230. Engine

231. Engines

232. in

233. PHP

234. Note:

235. Note:
//

236. This

237. is

238. a

239. comment
T_COMMENT
/*

240. This

241. is

242. a

243. multiline

244. comment

245. */

246. Note:
//

247. This

248. is

249. a

250. comment
T_COMMENT
/*

251. This

252. is

253. a

254. multiline

255. comment

256. */
/**

258. *

259. This

260. is

261. a

262. doc

263. block T_DOC_COMMENT

264. */

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

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

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

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

269. an no tatio ns?
uld

270. I

271. use /co ns?
hy

272. sho e

273. p ros
W
t

274. are

275. th
w ha

276. -

277. Harder

278. to

279. debug

280. (dynamic

281. code)
-

282. Harder

283. to

284. debug

285. (dynamic

286. code)
- Performance

287. hit

288. (non-native

289. code)

290. Harder

291. to

292. debug

293. (dynamic

294. code)
- Performance

295. hit

296. (non-native

297. code)
Its

298. implemented

299. in

300. comments

301. docblocks!

302. +

303. Easier

304. to

305. inject

306. behavior

307. without

308. extending
+

309. Easier

310. to

311. inject

312. behavior

313. without

314. extending
Doctrine

315. 1

316. vs

317. Doctrine

318. 2
+

319. Easier

320. to

321. inject

322. behavior

323. without

324. extending
Doctrine

325. 1

326. vs

327. Doctrine

328. 2
Contextualizes

329. behavior/config

330. in

331. the

332. object
+

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

352. Easier

353. to

354. inject

355. behavior

356. without

357. extending
Doctrine

358. 1

359. vs

360. Doctrine

361. 2
Contextualizes

362. behavior/config

363. in

364. the

365. object
+ In

366. object

367. vs.

368. external

369. configuration

370. file
Its

371. documented/stored

372. by

373. phpDocumentor

374. Easier

375. to

376. inject

377. behavior

378. without

379. extending
Doctrine

380. 1

381. vs

382. Doctrine

383. 2
Contextualizes

384. behavior/config

385. in

386. the

387. object
+ In

388. object

389. vs.

390. external

391. configuration

392. file
Its

393. documented/stored

394. by

395. phpDocumentor
Its

396. in

397. docblocks,

398. so

399. its

400. parsed

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

404. ?php
-

405. persist

406. as

407. varchar
length

408. should

409. not

410. be

411.
class User
{ -

412.
more

413. then

414. 255
-

415. should

416. not

417. be

418. blank
-

419. only

420. letters
protected $name
...
}

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

422. persist

423. as

424. varchar type: integer
length

425. should

426. not

427. be

428.
class User generator:
{ -

429. strategy: AUTO
more

430. then

431. 255
fields:
name:
-

432. should

433. not

434. be

435. blank type: string
-

436. only

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

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

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

440. used?

441. ann ota
er e

442. are
Wh

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

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

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

447. /**
Dependency

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

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

450. my

451. ow n

452.
rit

453. i

454. w ns?
How

455. can tio
a nno ta

456. My

457. Project
Annotations

458. Annotation

459.
Engine
My

460. Project
Annotations

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

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

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

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

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

467. Instances

468. Annotation Engines
Doctrine

469. Commons
ZF2

470. Annotations
phpDocumentor

471. 2
Notoj abandoned?
addendum
php-annotations Stubble

472. Annotation Engines
Notoj
2.3 2.0

473. -

474. alpha ?
Parameterized marker parameterized
very

475. mature maturing new

476. Annotation Engines
Notoj
2.3 2.0

477. -

478. alpha ?
Parameterized marker parameterized
very

479. mature maturing new

480. How

481. it

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

483. How

484. it

485. Works Declare

486. which

487. Annotations

488.
you

489. will

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

491. How

492. it

493. Works Declare

494. which

495. Annotations

496.
you

497. will

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

499. How

500. it

501. Works Declare

502. which

503. Annotations

504.
you

505. will

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

507. How

508. it

509. Works Declare

510. which

511. Annotations

512.
you

513. will

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

515. /

516. code
Cache

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

518. The

519. Gears

520. The

521. Gears
YourApp DoctrineCommons

522. The

523. Gears
Reader
YourApp DoctrineCommons

524. The

525. Gears
Parsing
Reader
YourApp DoctrineCommons

526. The

527. Gears
Parsing
Filter Reader
YourApp DoctrineCommons

528. The

529. Gears
“Enforcing” Parsing
Filter Reader
YourApp DoctrineCommons

530. The

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

532. The

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

534. The

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

536. The

537. Gears
“Enforcing” Parsing
Filter Reader
AnnotatedObject filter() getMethodAnnotation()
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()
filtered value
MyAnnotation
YourApp DoctrineCommons

542. Usage:

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

544. Usage:

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

546. doctrine

547. this

548.
*/
class NoDogs is

549. an

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

551. Usage:

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

553. doctrine

554. this

555.
*/
class NoDogs is

556. an

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

558. of

559. the

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

561. Usage:

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

563. doctrine

564. this

565.
*/
class NoDogs is

566. an

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

568. of

569. the

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

571. is

572. the

573. effect

574. of

575.
our

576. annotation

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

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

579. only

580. our

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

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

583. only

584. our

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

586. Annotation

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

588. application

589. Taking

590. it

591. up

592. a

593. notch

594. Taking

595. it

596. up

597. a

598. notch
Filter
Reader

599. Taking

600. it

601. up

602. a

603. notch
Filter
Reader Walker
Loader

604. Taking

605. it

606. up

607. a

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

609. Taking

610. it

611. up

612. a

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

614. Annotations

615. Taking

616. it

617. up

618. a

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

620. object,

621.
Filters

622. Annotations reflects

623. and

624. filters

625. Taking

626. it

627. up

628. a

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

630. object,

631.
Filters

632. Annotations reflects

633. and

634. filters

635. Taking

636. it

637. up

638. a

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

640. object,

641.
Filters

642. Annotations reflects

643. and

644. filters

645. Taking

646. it

647. up

648. a

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

650. object,

651.
Filters

652. Annotations reflects

653. and

654. filters

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

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

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

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

659. key

660. =

661. value
or
string:

662. value
new MyAnnotation($options);

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

664. key

665. =

666. value
or
string:

667. value
new MyAnnotation($options);
or

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

669. key

670. =

671. value
or
string:

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

673. //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

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

675. this

676. in

677. your