8000 final tweaks · symfony/symfony-docs@bf5188f · GitHub
[go: up one dir, main page]
Skip to content

Commit bf5188f

Browse files
weaverryanweaverryan
committed
final tweaks
1 parent 7e296d8 commit bf5188f

File tree

1 file changed

+49
-41
lines changed

1 file changed

+49
-41
lines changed

‎components/property_info.rst

Lines changed: 49 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ provide it with a set of information extractors.
4747
use Symfony\Component\PropertyInfo\PropertyInfoExtractor;
4848
use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
4949
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
50+
use Example\Namespace\YourAwesomeCoolClass;
5051
5152
// a full list of extractors is shown further below
5253
$phpDocExtractor = new PhpDocExtractor();
@@ -71,6 +72,13 @@ provide it with a set of information extractors.
7172
$accessExtractors
7273
);
7374
75+
// see below for more examples
76+
$class = YourAwesomeCoolClass::class;
77+
$properties = $propertyInfo->getProperties($class);
78+
79+
Extractor Ordering
80+
~~~~~~~~~~~~~~~~~~
81+
7482
The order of extractor instances within an array matters: the first non-null
7583
result will be returned. That is why you must provide each category of extractors
7684
as a separate array, even if an extractor provides information for more than
@@ -122,21 +130,17 @@ class exposes public methods to extract four types of information:
122130
* :ref:`Property *description* <property-info-description>`: `getShortDescription()` and `getLongDescription()`
123131
* :ref:`Property *access* details <property-info-access>`: `isReadable()` and `isWritable()`
124132

125-
list,
126-
type, description and access information. The first type of information is
127-
about the class, while the remaining three are about the individual properties.
128-
129133
.. note::
130134

131-
When specifiying a class that the PropertyInfo component should work
132-
with, use the fully-qualified class name. Do not directly pass an object
133-
as some extractors (the
134-
:class:`Symfony\\Component\\PropertyInfo\\Extractor\\SerializerExtractor`
135-
is an example) may not automatically resolve objects to their class
136-
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);
137139

138-
Since the PropertyInfo component requires PHP 5.5 or greater, you can
139-
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);
140144

141145
.. _property-info-list:
142146

@@ -189,6 +193,8 @@ for a property.
189193
}
190194
*/
191195
196+
See :ref:`components-property-info-type` for info about the ``Type`` class.
197+
192198
.. _property-info-description:
193199

194200
Description Information
@@ -232,6 +238,11 @@ provide whether properties are readable or writable as booleans.
232238
$propertyInfo->isWritable($class, $property);
233239
// Example Result: bool(false)
234240
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 :ref:`PropertyAccess </components/property_access>`
244+
works.
245+
235246
.. tip::
236247

237248
The main :class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`
@@ -248,10 +259,9 @@ Type Objects
248259
------------
249260

250261
Compared to the other extractors, type information extractors provide much
251-
more information than can be represented as simple scalar values - because
252-
of this, type ex 10000 tractors return an array of objects. The array will contain
253-
an instance of the :class:`Symfony\\Component\\PropertyInfo\\Type`
254-
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.
255265

256266
For example, if a property supports both ``integer`` and ``string`` (via
257267
the ``@return int|string`` annotation),
@@ -265,15 +275,12 @@ class.
265275
instance. The :class:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpDocExtractor`
266276
is currently the only extractor that returns multiple instances in the array.
267277

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

273280
.. _`components-property-info-type-builtin`:
274281

275-
Built-in Type
276-
~~~~~~~~~~~~~
282+
Type::getBuiltInType()
283+
~~~~~~~~~~~~~~~~~~~~~~
277284

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

286-
Nullable
287-
~~~~~~~~
293+
Type::isNullable()
294+
~~~~~~~~~~~~~~~~~~
288295

289296
The :method:`Type::isNullable() <Symfony\\Component\\PropertyInfo\\Type::isNullable>`
290297
method will return a boolean value indicating whether the property parameter
291298
can be set to ``null``.
292299

293-
Class
294-
~~~~~
300+
Type::getClassName()
301+
~~~~~~~~~~~~~~~~~~~~
295302

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

300-
Collection
301-
~~~~~~~~~~
307+
Type::isCollection()
308+
~~~~~~~~~~~~~~~~~~~~
302309

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

313-
Collection Key & Value Types
314-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
320+
Type::getCollectionKeyType() & Type::getCollectionValueType()
321+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
315322

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

347-
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.
348356

349357
.. code-block:: php
350358
351359
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
352360
353-
$reflectionExtractor = new ReflectionExtractor;
361+
$reflectionExtractor = new ReflectionExtractor();
354362
355363
// List information.
356364
$reflectionExtractor->getProperties($class);
@@ -370,13 +378,14 @@ PhpDocExtractor
370378
Using `phpDocumentor Reflection`_ to parse property and method annotations,
371379
the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpDocExtractor`
372380
provides type and description information. This extractor is automatically
373-
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.
374383

375384
.. code-block:: php
376385
377386
use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
378387
379-
$phpDocExtractor = new PhpDocExtractor;
388+
$phpDocExtractor = new PhpDocExtractor();
380389
381390
// Type information.
382391
$phpDocExtractor->getTypes($class, $property);
@@ -391,10 +400,11 @@ SerializerExtractor
391400

392401
This extractor depends on the `symfony/serializer`_ library.
393402

394-
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>`,
395405
the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\SerializerExtractor`
396-
provides list information. This extractor is not registered automatically
397-
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.
398408

399409
.. code-block:: php
400410
@@ -421,9 +431,8 @@ DoctrineExtractor
421431

422432
Using entity mapping data from `Doctrine ORM`_, the
423433
:class:`Symfony\\Bridge\\Doctrine\\PropertyInfo\\DoctrineExtractor`
424-
- located in the Doctrine bridge - provides list and type information.
425-
This extractor is not registered automatically with the ``property_info``
426-
service.
434+
provides list and type information. This extractor is not registered automatically
435+
with the ``property_info`` service in the Symfony Framework.
427436

428437
.. code-block:: php
429438
@@ -472,4 +481,3 @@ service by defining it as a service with one or more of the following
472481
.. _`symfony/serializer`: https://packagist.org/packages/symfony/serializer
473482
.. _`symfony/doctrine-bridge`: https://packagist.org/packages/symfony/doctrine-bridge
474483
.. _`doctrine/orm`: https://packagist.org/packages/doctrine/orm
475-
.. _`class constant`: http://php.net/manual/en/language.oop5.basic.php#language.oop5.basic.class.class

0 commit comments

Comments
 (0)
0