8000 minor #6896 Tweaks to property info component (weaverryan) · symfony/symfony-docs@081c2d6 · GitHub
[go: up one dir, main page]
Skip to content

Commit 081c2d6

Browse files
weaverryanweaverryan
committed
minor #6896 Tweaks to property info component (weaverryan)
This PR was merged into the 2.8 branch. Discussion ---------- Tweaks to property info component Just proofreading and making some tweaks to #5974 Commits ------- c9ea21f bad link! fcf5e69 fixing indentation bf5188f final tweaks 7e296d8 [WIP] Tweaks to property info
2 parents 563bab8 + c9ea21f commit 081c2d6

File tree

1 file changed

+94
-57
lines changed

1 file changed

+94
-57
lines changed

‎components/property_info.rst

Lines changed: 94 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,14 @@
55
The PropertyInfo Component
66
==========================
77

8-
The PropertyInfo component provides the functionality to get information
9-
about class properties using metadata of popular sources.
8+
The PropertyInfo component allows you to get information
9+
about class properties by using different sources of metadata.
1010

1111
While the :doc:`PropertyAccess component </components/property_access>`
1212
allows you to read and write values to/from objects and arrays, the PropertyInfo
13-
component works solely with class definitions to provide information such
14-
as data type and visibility about properties within that class.
15-
16-
Similar to PropertyAccess, the PropertyInfo component combines both class
17-
properties (such as ``$property``) and properties defined via accessor and
18-
mutator methods such as ``getProperty()``, ``isProperty()``, ``setProperty()``,
19-
``addProperty()``, ``removeProperty()``, etc.
13+
component works solely with class definitions to provide information about the
14+
data type and visibility - including via getter or setter methods - of the properties
15+
within that class.
2016

2117
.. versionadded:: 2.8
2218
The PropertyInfo component was introduced in Symfony 2.8.
@@ -42,22 +38,48 @@ Additional dependencies may be required for some of the
4238
Usage
4339
-----
4440

45-
The entry point of this component is a new instance of the
46-
:class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`
47-
class, providing sets of information extractors.
41+
To use this component, create a new
42+
:class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor` instance and
43+
provide it with a set of information extractors.
4844

4945
.. code-block:: php
5046
5147
use Symfony\Component\PropertyInfo\PropertyInfoExtractor;
48+
use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
49+
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
50+
use Example\Namespace\YourAwesomeCoolClass;
51+
52+
// a full list of extractors is shown further below
53+
$phpDocExtractor = new PhpDocExtractor();
54+
$reflectionExtractor = new ReflectionExtractor();
55+
56+
// array of PropertyListExtractorInterface
57+
$listExtractors = array($reflectionExtractor);
58+
59+
// array of PropertyTypeExtractorInterface
60+
$typeExtractors = array($phpDocExtractor, $reflectionExtractor);
61+
62+
// array of PropertyDescriptionExtractorInterface
63+
$descriptionExtractors = array($phpDocExtractor);
64+
65+
// array of PropertyAccessExtractorInterface
66+
$accessExtractors = array($reflectionExtractor);
5267
5368
$propertyInfo = new PropertyInfoExtractor(
54-
$arrayOfListExtractors,
55-
$arrayOfTypeExtractors,
56-
$arrayOfDescriptionExtractors,
57-
$arrayOfAccessExtractors
69+
$listExtractors,
70+
$typeExtractors,
71+
$descriptionExtractors,
72+
$accessExtractors
5873
);
5974
60-
The order of extractor instances within an array matters, as the first non-null
75+
// see below for more examples
76+
$class = YourAwesomeCoolClass::class;
77+
$properties = $propertyInfo->getProperties($class);
78+
79+
Extractor Ordering
80+
~~~~~~~~~~~~~~~~~~
81+
82+
The order of extractor instances within an array matters: the first non-null
6183
result will be returned. That is why you must provide each category of extractors
6284
as a separate array, even if an extractor provides information for more than
6385
one category.
@@ -101,21 +123,26 @@ Extractable Information
101123
-----------------------
102124

103125
The :class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`
104-
class exposes public methods to extract four types of information: list,
105-
type, description and access information. The first type of information is
106-
about the class, while the remaining three are about the individual properties.
126+
class exposes public methods to extract four types of information:
127+
128+
* :ref:`*List* of properties <property-info-list>`: `getProperties()`
129+
* :ref:`Property *type* <property-info-type>`: `getTypes()`
130+
* :ref:`Property *description* <property-info-description>`: `getShortDescription()` and `getLongDescription()`
131+
* :ref:`Property *access* details <property-info-access>`: `isReadable()` and `isWritable()`
107132

108133
.. note::
109134

110-
When specifiying a class that the PropertyInfo component should work
111-
with, use the fully-qualified class name. Do not directly pass an object
112-
as some extractors (the
113-
:class:`Symfony\\Component\\PropertyInfo\\Extractor\\SerializerExtractor`
114-
is an example) may not automatically resolve objects to their class
115-
names - use the ``get_class()`` function.
135+
Be sure to pass a *class* name, not an object to the extractor methods::
136+
137+
// bad! It may work, but not with all extractors
138+
$propertyInfo->getProperties($awesomeObject);
116139

117-
Since the PropertyInfo component requires PHP 5.5 or greater, you can
118-
also make use of the `class constant`_.
140+
// Good!
141+
$propertyInfo->getProperties(get_class($awesomeObject));
142+
$propertyInfo->getProperties('Example\Namespace\YourAwesomeClass');
143+
$propertyInfo->getProperties(YourAwesomeClass::class);
144+
145+
.. _property-info-list:
119146

120147
List Information
121148
~~~~~~~~~~~~~~~~
@@ -137,6 +164,8 @@ containing each property name as a string.
137164
}
138165
*/
139166
167+
.. _property-info-type:
168+
140169
Type Information
141170
~~~~~~~~~~~~~~~~
142171

@@ -164,6 +193,10 @@ for a property.
164193
}
165194
*/
166195
196+
See :ref:`components-property-info-type` for info about the ``Type`` class.
197+
198+
.. _property-info-description:
199+
167200
Description Information
168201
~~~~~~~~~~~~~~~~~~~~~~~
169202

@@ -189,6 +222,8 @@ strings.
189222
It can span multiple lines.
190223
*/
191224
225+
.. _property-info-access:
226+
192227
Access Information
193228
~~~~~~~~~~~~~~~~~~
194229

@@ -203,6 +238,11 @@ provide whether properties are readable or writable as booleans.
203238
$propertyInfo->isWritable($class, $property);
204239
// Example Result: bool(false)
205240
241+
The :class:`Symfony\\Component\\PropertyInfo\\Extractor\\ReflectionExtractor` looks
242+
for getter/isser/setter method in addition to whether or not a property is public
243+
to determine if it's accessible. This based on how the :doc:`PropertyAccess </components/property_access>`
244+
works.
245+
206246
.. tip::
207247

208248
The main :class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`
@@ -219,10 +259,9 @@ Type Objects
219259
------------
220260

221261
Compared to the other extractors, type information extractors provide much
222-
more information than can be represented as simple scalar values - because
223-
of this, type extractors return an array of objects. The array will contain
224-
an instance of the :class:`Symfony\\Component\\PropertyInfo\\Type`
225-
class for each type that the property supports.
262+
more information than can be represented as simple scalar values. Because
263+
of this, type extractors return an array of :class:`Symfony\\Component\\PropertyInfo\\Type`
264+
objects for each type that the property supports.
226265

227266
For example, if a property supports both ``integer`` and ``string`` (via
228267
the ``@return int|string`` annotation),
@@ -236,15 +275,12 @@ class.
236275
instance. The :class:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpDocExtractor`
237276
is currently the only extractor that returns multiple instances in the array.
238277

239-
Each object will provide 6 attributes; the first four (built-in type, nullable,
240-
class and collection) are scalar values and the last two (collection key
241-
type and collection value type) are more instances of the :class:`Symfony\\Component\\PropertyInfo\\Type`
242-
class again if collection is ``true``.
278+
Each object will provide 6 attributes, available in the 6 methods:
243279

244280
.. _`components-property-info-type-builtin`:
245281

246-
Built-in Type
247-
~~~~~~~~~~~~~
282+
Type::getBuiltInType()
283+
~~~~~~~~~~~~~~~~~~~~~~
248284

249285
The :method:`Type::getBuiltinType() <Symfony\\Component\\PropertyInfo\\Type::getBuiltinType>`
250286
method will return the built-in PHP data type, which can be one of 9 possible
@@ -254,22 +290,22 @@ string values: ``array``, ``bool``, ``callable``, ``float``, ``int``, ``null``,
254290
Constants inside the :class:`Symfony\\Component\\PropertyInfo\\Type`
255291
class, in the form ``Type::BUILTIN_TYPE_*``, are provided for convenience.
256292

257-
Nullable
258-
~~~~~~~~
293+
Type::isNullable()
294+
~~~~~~~~~~~~~~~~~~
259295

260296
The :method:`Type::isNullable() <Symfony\\Component\\PropertyInfo\\Type::isNullable>`
261297
method will return a boolean value indicating whether the property parameter
262298
can be set to ``null``.
263299

264-
Class
265-
~~~~~
300+
Type::getClassName()
301+
~~~~~~~~~~~~~~~~~~~~
266302

267303
If the :ref:`built-in PHP data type <components-property-info-type-builtin>`
268304
is ``object``, the :method:`Type::getClassName() <Symfony\\Component\\PropertyInfo\\Type::getClassName>`
269305
method will return the fully-qualified class or interface name accepted.
270306

271-
Collection
272-
~~~~~~~~~~
307+
Type::isCollection()
308+
~~~~~~~~~~~~~~~~~~~~
273309

274310
The :method:`Type::isCollection() <Symfony\\Component\\PropertyInfo\\Type::isCollection>`
275311
method will return a boolean value indicating if the property parameter is
@@ -281,8 +317,8 @@ this returns ``true`` if:
281317
* The mutator method the property is derived from has a prefix of ``add``
282318
or ``remove`` (which are defined as the list of array mutator prefixes).
283319

284-
Collection Key & Value Types
285-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
320+
Type::getCollectionKeyType() & Type::getCollectionValueType()
321+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
286322

287323
If the property is a collection, additional type objects may be returned
288324
for both the key and value types of the collection (if the information is
@@ -315,13 +351,14 @@ Using PHP reflection, the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\R
315351
provides list, type and access information from setter and accessor methods.
316352
It can also provide return and scalar types for PHP 7+.
317353

318-
This service is automatically registered with the ``property_info`` service.
354+
This service is automatically registered with the ``property_info`` service in
355+
the Symfony Framework.
319356

320357
.. code-block:: php
321358
322359
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
323360
324-
$reflectionExtractor = new ReflectionExtractor;
361+
$reflectionExtractor = new ReflectionExtractor();
325362
326363
// List information.
327364
$reflectionExtractor->getProperties($class);
@@ -341,13 +378,14 @@ PhpDocExtractor
341378
Using `phpDocumentor Reflection`_ to parse property and method annotations,
342379
the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpDocExtractor`
343380
provides type and description information. This extractor is automatically
344-
registered with the ``property_info`` providing its dependencies are detected.
381+
registered with the ``property_info`` in the Symfony Framework *if* the dependent
382+
library is present.
345383

346384
.. code-block:: php
347385
348386
use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
349387
350-
$phpDocExtractor = new PhpDocExtractor;
388+
$phpDocExtractor = new PhpDocExtractor();
351389
352390
// Type information.
353391
$phpDocExtractor->getTypes($class, $property);
@@ -362,10 +400,11 @@ SerializerExtractor
362400

363401
This extractor depends on the `symfony/serializer`_ library.
364402

365-
Using groups metadata from the :doc:`Serializer component </components/serializer>`,
403+
Using :ref:`groups metadata <serializer-using-serialization-groups-annotations>`
404+
from the :doc:`Serializer component </components/serializer>`,
366405
the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\SerializerExtractor`
367-
provides list information. This extractor is not registered automatically
368-
with the ``property_info`` service.
406+
provides list information. This extractor is *not* registered automatically
407+
with the ``property_info`` service in the Symfony Framework.
369408

370409
.. code-block:: php
371410
@@ -392,9 +431,8 @@ DoctrineExtractor
392431

393432
Using entity mapping data from `Doctrine ORM`_, the
394433
:class:`Symfony\\Bridge\\Doctrine\\PropertyInfo\\DoctrineExtractor`
395-
- located in the Doctrine bridge - provides list and type information.
396-
This extractor is not registered automatically with the ``property_info``
397-
service.
434+
provides list and type information. This extractor is not registered automatically
435+
with the ``property_info`` service in the Symfony Framework.
398436

399437
.. code-block:: php
400438
@@ -443,4 +481,3 @@ service by defining it as a service with one or more of the following
443481
.. _`symfony/serializer`: https://packagist.org/packages/symfo 4E5D ny/serializer
444482
.. _`symfony/doctrine-bridge`: https://packagist.org/packages/symfony/doctrine-bridge
445483
.. _`doctrine/orm`: https://packagist.org/packages/doctrine/orm
446-
.. _`class constant`: http://php.net/manual/en/language.oop5.basic.php#language.oop5.basic.class.class

0 commit comments

Comments
 (0)
0