8000 Added the documentation of the PropertyInfo component by javiereguiluz · Pull Request #6047 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

Added the documentation of the PropertyInfo component #6047

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

Added the documentation of the PropertyInfo component #6047

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8b36745
[PropertyInfo] Add the doc
dunglas Sep 22, 2015
dfa5c45
Sync with the merged version
dunglas Oct 6, 2015
73b8d17
Finish the documentation of PropertyInfo
javiereguiluz Dec 18, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Finish the documentation of PropertyInfo
  • Loading branch information
@javiereguiluz
javiereguiluz committed Dec 18, 2015
commit 73b8d17b5d5cff1cfeef9c8eba9662d77a11c882
250 changes: 128 additions & 122 deletions components/property_info.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,26 +5,28 @@
The PropertyInfo Component
==========================

The PropertyInfo component extracts information about PHP class' properties
using metadata of popular sources.
The PropertyInfo component extracts information about the properties of PHP
classes using different sources of metadata.

The PropertyInfo component is able to extract the following information:
The PropertyInfo component extracts the following information:

* List of properties exposed by a class
* Types of a property
* It's short and long DockBlock description
* If the property is readable or writable
* List of properties exposed by a class;
* Type of each property (``int``, ``array``, ``callable``, etc.);
* The short and long DockBlock description (if available);
* Whether the property is readable and/or writable.

To do so, the component use extractors. It natively support the following
metadata sources:
This information is obtained using several *extractors*, which work by parsing
different sources of properties metadata:

* ``ReflectionExtractor``: use the PHP Reflection API (setter type hint,
return and scalar type hint for PHP 7+, accessor methods)
* ``PhpDocExtractor``: use the PHPDoc of properties and accessor methods
* ``DoctrineExtractor``: use metadata provided by the Doctrine ORM
* ``SerializerExtractor``: use groups metadata of the Serializer component
* ``ReflectionExtractor``: uses the built-in PHP Reflection API to parse setter
type hints, return and scalar type hints (for PHP 7+) and accessor methods
(*getXxx()*, *hasXxx()*, *isXxx()*);
* ``PhpDocExtractor``: parses the PHPDoc of properties and accessor methods;
* ``DoctrineExtractor``: gets the metadata provided by the Doctrine ORM;
* ``SerializerExtractor``: gets groups metadata from the Serializer component.

Custom extractors can be also be registered.
Besides these built-in extractors, you can create your own custom extractors,
as explained in the following sections.

Installation
------------
Expand All @@ -37,18 +39,21 @@ You can install the component in 2 different ways:

.. include:: /components/require_autoload.rst.inc

To use the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpDocExtractor`,
Optional dependencies
~~~~~~~~~~~~~~~~~~~~~

* To use the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpDocExtractor`,
install `phpDocumentator Reflection`_.
To use the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\SerializerExtractor`
* To use the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\SerializerExtractor`
extractor, install the :doc:`Serializer component </components/serializer>`.
To use the :class:`Symfony\\Bridge\\Doctrine\\PropertyInfo\\DoctrineExtractor`,
* To use the :class:`Symfony\\Bridge\\Doctrine\\PropertyInfo\\DoctrineExtractor`,
install the Doctrine Bridge and the `Doctrine ORM`_.

Usage
-----

Using the PropertyInfo component is straightforward. You need to register
all metadata extractors you want to use in the constructor of the :class:`Symfony\\Component\\PropertyInfo\\PropertyInfo`
Before using the PropertyInfo component, you need to register the extractors by
passing them to the constructor of the :class:`Symfony\\Component\\PropertyInfo\\PropertyInfo`
class::

use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
Expand All @@ -65,28 +70,26 @@ class::
array($reflectionExtractor)
);

An array of implementations of :class:`Symfony\\Component\\PropertyInfo\\PropertyListExtractorInterface`
must be passed as first parameter. These extractors are responsible of extracting
the list of properties of a class.

An array of implementations of :class:`Symfony\\Component\\PropertyInfo\\PropertyTypeExtractorInterface`
must be passed as second parameter. These extractors are responsible of extracting
types of a property.
The **first argument** must be an array of implementations of :class:`Symfony\\Component\\PropertyInfo\\PropertyListExtractorInterface`.
These extractors are responsible of extracting the list of properties of a class.

An array of implementations of :class:`Symfony\\Component\\PropertyInfo\\PropertyDescriptionExtractorInterface`
must be passed as third parameter. These extractors are responsible of extracting
short and long DocBlock description of a property.
The **second argument** must be an array of implementations of :class:`Symfony\\Component\\PropertyInfo\\PropertyTypeExtractorInterface`.
These extractors are responsible of extracting types of a property.

Finally, an array of implementations of :class:`Symfony\\Component\\PropertyInfo\\PropertyAccessExtractorInterface`
must be passed as fourth parameter. These extractors are responsible of guessing
if a property is readable or writable.
The **third argument** must be an array of implementations of :class:`Symfony\\Component\\PropertyInfo\\PropertyDescriptionExtractorInterface`.
These extractors are responsible of extracting the DocBlock description of a
property.

The order of registration matter: the data returned will be the one returned
by the first extractor if different than ``null``.
The **fourth argument** must be an array of implementations of :class:`Symfony\\Component\\PropertyInfo\\PropertyAccessExtractorInterface`.
These extractors are responsible of guessing if a property is readable and/or
writable.

The order in which extractors are registered is important, because the returned
data will be the one returned by the first extractor which returns something
different than ``null``.

Once instantiated, the ``PropertyInfo`` class can be used to retrieve info
about properties of a class::
Once instantiated, use the ``PropertyInfo`` class to retrieve info about any of
the properties of a class. Consider the following example class::

class MyClass
{
Expand All @@ -107,84 +110,94 @@ about properties of a class::
}
}

var_dump($propertyInfo->getProperties('MyClass'));
var_dump($propertyInfo->getTypes('MyClass', 'foo'));
var_dump($propertyInfo->getTypes('MyClass', 'bar'));
var_dump($propertyInfo->isReadable('MyClass', 'foo'));
var_dump($propertyInfo->isReadable('MyClass', 'bar'));
var_dump($propertyInfo->isWritable('MyClass', 'foo'));
var_dump($propertyInfo->getShortDescription('MyClass', 'bar'));
var_dump($propertyInfo->getLongDescription('MyClass', 'foo'));
Given the previous ``$propertyInfo`` object, you can easily extract all the
information about any property::

/*
Output:
array(1) {
[0] =>
string(3) "foo"
}
array(1) {
[0] =>
class Symfony\Component\PropertyInfo\Type#7 (6) {
private $builtinType =>
string(6) "string"
private $nullable =>
bool(false)
private $class =>
NULL
private $collection =>
bool(false)
private $collectionKeyType =>
NULL
private $collectionValueType =>
NULL
}
}
array(1) {
[0] =>
class Symfony\Component\PropertyInfo\Type#129 (6) {
private $builtinType =>
string(5) "array"
private $nullable =>
bool(false)
private $class =>
NULL
private $collection =>
bool(true)
private $collectionKeyType =>
NULL
private $collectionValueType =>
NULL
}
}
bool(true)
bool(false)
bool(true)
string(17) "Virtual property."
string(37) "And here is its extended description."
*/
$properties = $propertyInfo->getProperties('MyClass');
// $properties = array('foo')

$barIsReadable = $propertyInfo->isReadable('MyClass', 'bar');
// $barIsReadable = false

$fooIsWritable = $propertyInfo->isWritable('MyClass', 'foo');
// $fooIsWritable = true

Extraction Methods
------------------

As PHP doesn't support explicit type definition, ``PropertyInfo::getTypes``
use registered extractors to an array of :class:`Symfony\\Component\\PropertyInfo\\Type`
value objects.
Those object represent complex PHP types. Refer to the API documentation
of this class for more details.
These are the public methods exposed by the API of this component:

:method:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractorInterface::getProperties`
It returns an array with the names of all the properties exposed by the given
class:

$result = $propertyInfo->getProperties('MyClass');

:method:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractorInterface::isReadable`
It returns ``true`` when the value of the given property is readable in any
way for the given class (through the property itself or through some access
method)::

$result = $propertyInfo->isReadable('MyClass', 'foo');

:method:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractorInterface::isWritable`
It returns ``true`` when the value of the given property is writable in any
way for the given class (through the property itself or through some access
method):

$result = $propertyInfo->isWritable('MyClass', 'foo');

:method:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractorInterface::getShortDescription`
It returns the short PHPDoc description for the given property and class (or
``null`` if no short description is available). This short description corresponds
to the first line of the full PHPDoc description::

$result = $propertyInfo->getShortDescription('MyClass', 'foo');

:method:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractorInterface::getLongDescription`
It returns the full PHPDoc description for the given property and class (or
``null`` if no description is available). This long description corresponds
to the full PHPDoc description except its first line::

$result = $propertyInfo->getLongDescription('MyClass', 'foo');

:method:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractorInterface::getTypes`
It returns an array of :class:`Symfony\\Component\\PropertyInfo\\Type` objects
describing the type of each property of the given class and property::

$result = $propertyInfo->getTypes('MyClass', 'foo');

Since PHP doesn't support explicit type definition, these ``Type`` objects
represent complex PHP types. Using the same ``MyClass`` class as shown above,
the content of the ``$result`` variable would be::

array(1) {
[0] =>
class Symfony\Component\PropertyInfo\Type#7 (6) {
private $builtinType => string(6) "string"
private $nullable => bool(false)
private $class => NULL
private $collection => bool(false)
private $collectionKeyType => NULL
private $collectionValueType => NULL
}
}

Extractors
----------

Symfony is shipped with two extractors in addition to the already presented
``ReflectionExtractor`` and ``PhpDocExtractors``.
Moreover, custom extractors can be created by implementing the extractor
interfaces provided with the PropertyInfo component.
Besides the basic ``ReflectionExtractor`` and ``PhpDocExtractors`` extractors,
Symfony framework includes two additional extractors: ``ReflectionExtractor``
and ``PhpDocExtractors``.

The ``DoctrineExtractor``
~~~~~~~~~~~~~~~~~~~~~~~~~

The Doctrine extractor reuse metadata of the Doctrine ORM to extract the
The Doctrine extractor reuses the metadata of the Doctrine ORM to extract the
list of properties and their type. It implements ``PropertyListExtractorInterface``
and ``PropertyTypeExtractorInterface`` interfaces.

Instantiate it::
First, instantiate the extractor::

use Doctrine\ORM\EntityManager;
use Doctrine\ORM\Tools\Setup;
Expand All @@ -198,7 +211,7 @@ Instantiate it::

$doctrineExtractor = new DoctrineExtractor($entityManager->getMetadataFactory());

You can now use it to retrieve information about an entity mapped with Doctrine::
Then, retrieve information about an entity mapped with Doctrine::

use Doctrine\ORM\Mapping\Column;
use Doctrine\ORM\Mapping\Entity;
Expand All @@ -223,29 +236,23 @@ You can now use it to retrieve information about an entity mapped with Doctrine:
Output:

array(1) {
[0] =>
string(2) "id"
[0] => string(2) "id"
}

array(1) {
[0] =>
class Symfony\Component\PropertyInfo\Type#27 (6) {
private $builtinType =>
string(3) "int"
private $nullable =>
bool(false)
private $class =>
NULL
private $collection =>
bool(false)
private $collectionKeyType =>
NULL
private $collectionValueType =>
NULL
private $builtinType => string(3) "int"
private $nullable => bool(false)
private $class => NULL
private $collection => bool(false)
private $collectionKeyType = B149 > NULL
private $collectionValueType => NULL
}
}
*/

Of course you can also register this extractor in the ``PropertyInfo`` class::
You can also register this extractor in the ``PropertyInfo`` class::

$propertyInfo = new PropertyInfo(
array($reflectionExtractor, $doctrineExtractor),
Expand All @@ -258,7 +265,7 @@ The ``SerializerExtractor``
The ``SerializerExtractor`` leverages groups metadata of the Symfony Serializer
Component (2.7+) to list properties having the groups passed in the context.

Instantiate it::
First, instantiate the extractor::

use Doctrine\Common\Annotations\AnnotationReader;
use Symfony\Component\PropertyInfo\Extractor\SerializerExtractor;
Expand All @@ -268,7 +275,7 @@ Instantiate it::
$serializerClassMetadataFactory = new ClassMetadataFactory(new AnnotationLoader(new AnnotationReader()));
$serializerExtractor = new SerializerExtractor($serializerClassMetadataFactory);

Usage::
Then, use it to extract the information::

use Symfony\Component\Serializer\Annotation\Groups;

Expand All @@ -285,8 +292,7 @@ Usage::
/*
Output:
array(1) {
[0] =>
string(2) "bar"
[0] => string(2) "bar"
}
*/

Expand Down
0