...

...

@@ -7,7 +7,7 @@

7

7

<?phpdoc print-version-for="attributes"?>

8

8

9

9

<para>

10

-

Attributes allow to add structured, machine-readable metadata information

10

+

Attributes offer the ability to add structured, machine-readable metadata information

11

11

on declarations in code: Classes, methods, functions, parameters,

12

12

properties and class constants can be the target of an attribute. The metadata

13

13

defined by attributes can then be inspected at runtime using the

...

...

@@ -29,13 +29,13 @@

29

29

30

30

<para>

31

31

A simple example of attribute usage is to convert an interface

32

-

that has optional methods to use attributes. Lets assume an

32

+

that has optional methods to use attributes. Let's assume an

33

33

<literal>ActionHandler</literal>

34

34

interface representing an operation in an application, where some

35

35

implementations of an action handler require setup and others do not. Instead of requiring all classes

36

36

that implement <literal>ActionHandler</literal> to implement

37

37

a method <literal>setUp()</literal>,

38

-

we use an attribute that can be used instead. One benefit

38

+

an attribute can be used. One benefit

39

39

of this approach is that we can use the attribute several times.

40

40

</para>

41

41

...

...

@@ -68,7 +68,11 @@ class CopyFile implements ActionHandler

68

68

#[SetUp]

69

69

public function targetDirectoryExists()

70

70

{

71

-

mkdir($this->targetDirectory);

71

+

if (!file_exists($this->targetDirectory)) {

72

+

mkdir($this->targetDirectory);

73

+

} elseif (!is_dir($this->targetDirectory)) {

74

+

throw new RuntimeException("Target directory $this->targetDirectory is not a directory");

75

+

}

72

76

}

73

77

74

78

public function execute()

...

...

@@ -108,11 +112,11 @@ executeAction($copyAction);

108

112

<title>Attribute syntax</title>

109

113

110

114

<para>

111

-

There are several parts to the attributes syntax. First, attribute

112

-

declaration are always enclosed with a starting

115

+

There are several parts to the attributes syntax. First, an attribute

116

+

declaration is always enclosed with a starting

113

117

<literal>#[</literal> and a corresponding ending

114

118

<literal>]</literal>. Inside, one or many attributes are listed,

115

-

seperated by comma. The attribute name is an unqualified, qualified

119

+

separated by comma. The attribute name is an unqualified, qualified

116

120

or fully-qualified name as described in <link linkend="language.namespaces.basics">Using Namespaces Basics</link>.

117

121

Arguments to the attribute are optional, but are enclosed in the usual parenthesis <literal>()</literal>.

118

122

Arguments to attributes can only be literal values or constant expressions. Both positional and

...

...

@@ -189,7 +193,7 @@ class AnotherThing

189

193

<para>

190

194

This separation of reflected attribute representation from actual instance increases control of the programmer

191

195

to handle errors regarding missing attribute classes, mistyped or missing arguments. Only after

192

-

calling <function>newInstance</function>, objects of the attribute class are instantiated and the correct matching of arguments

196

+

calling <function>ReflectionAttribute::newInstance</function>, objects of the attribute class are instantiated and the correct matching of arguments

193

197

is validated, not earlier.

194

198

</para>

195

199

...

...

@@ -266,7 +270,7 @@ function dumpMyAttributeData($reflection) {

266

270

}

267

271

}

268

272

269

-

dumpAttributeData(new ReflectionClass(Thing::class));

273

+

dumpMyAttributeData(new ReflectionClass(Thing::class));

270

274

]]>

271

275

</programlisting>

272

276

</example>

...

...

@@ -282,7 +286,7 @@ dumpAttributeData(new ReflectionClass(Thing::class));

282

286

</para>

283

287

284

288

<example>

285

-

<title>Using target specification to restrict where attributes can be used</title>

289

+

<title>Simple Attribute Class</title>

286

290

287

291

<programlisting role="php">

288

292

<![CDATA[

...

...

@@ -306,7 +310,7 @@ class MyAttribute

306

310

</para>

307

311

308

312

<example>

309

-

<title>Simple Attribute Class</title>

313

+

<title>Using target specification to restrict where attributes can be used</title>

310

314

311

315

<programlisting role="php">

312

316

<![CDATA[

...

...

@@ -329,6 +333,18 @@ class MyAttribute

329

333

</para>

330

334

</example>

331

335

336

+

<para>The following targets can be specified:</para>

337

+

338

+

<simplelist>

339

+

<member><constant>Attribute::TARGET_CLASS</constant></member>

340

+

<member><constant>Attribute::TARGET_FUNCTION</constant></member>

341

+

<member><constant>Attribute::TARGET_METHOD</constant></member>

342

+

<member><constant>Attribute::TARGET_PROPERTY</constant></member>

343

+

<member><constant>Attribute::TARGET_CLASS_CONSTANT</constant></member>

344

+

<member><constant>Attribute::TARGET_PARAMETER</constant></member>

345

+

<member><constant>Attribute::TARGET_ALL</constant></member>

346

+

</simplelist>

347

+

332

348

<para>

333

349

By default an attribute can only be used once per declaration. If the attribute should be repeatable on declarations it must

334

350

be specified as part of the bitmask to the <literal>#[Attribute]</literal> declaration.

335

351