8000 Merge branch '2.8' into 3.0 · jameshalsall/symfony-docs@dadb75c · GitHub
[go: up one dir, main page]
Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit dadb75c

Browse files
wouterjwouterj
committed
Merge branch '2.8' into 3.0
Conflicts: reference/configuration/framework.rst
2 parents 98e65bf + 0fffa1c commit dadb75c

File tree

8 files changed

+152
-101
lines changed

8 files changed

+152
-101
lines changed

‎components/event_dispatcher.rst

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -440,14 +440,9 @@ EventDispatcher Aware Events and Listeners
440440
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
441441

442442
The ``EventDispatcher`` always passes the dispatched event, the event's
443-
name and a reference to itself to the listeners. This can be used in some
444-
advanced usages of the ``EventDispatcher`` like dispatching other events
445-
in listeners, event chaining or even lazy loading of more listeners into
446-
the dispatcher object as shown in the following examples.
447-
448-
This can lead to some advanced applications of the ``EventDispatcher``
449-
including dispatching other events inside listeners, chaining events or even
450-
lazy loading listeners into the dispatcher object.
443+
name and a reference to itself to the listeners. This can lead to some advanced
444+
applications of the ``EventDispatcher`` including dispatching other events inside
445+
listeners, chaining events or even lazy loading listeners into the dispatcher object.
451446

452447
.. index::
453448
single: EventDispatcher; Dispatcher shortcuts

‎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
.. _`components-property-information-installation`:
2218

@@ -39,22 +35,48 @@ Additional dependencies may be required for some of the
3935
Usage
4036
-----
4137

42-
The entry point of this component is a new instance of the
43-
:class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`
44-
class, providing sets of information extractors.
38+
To use this component, create a new
39+
:class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor` instance and
40+
provide it with a set of information extractors.
4541

4642
.. code-block:: php
4743
4844
use Symfony\Component\PropertyInfo\PropertyInfoExtractor;
45+
use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
46+
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
47+
use Example\Namespace\YourAwesomeCoolClass;
48+
49+
// a full list of extractors is shown further below
50+
$phpDocExtractor = new PhpDocExtractor();
51+
$reflectionExtractor = new ReflectionExtractor();
52+
53+
// array of PropertyListExtractorInterface
54+
$listExtractors = array($reflectionExtractor);
55+
56+
// array of PropertyTypeExtractorInterface
57+
$typeExtractors = array($phpDocExtractor, $reflectionExtractor);
58+
59+
// array of PropertyDescriptionExtractorInterface
60+
$descriptionExtractors = array($phpDocExtractor);
61+
62+
// array of PropertyAccessExtractorInterface
63+
$accessExtractors = array($reflectionExtractor);
4964
5065
$propertyInfo = new PropertyInfoExtractor(
51-
$arrayOfListExtractors,
52-
$arrayOfTypeExtractors,
53-
$arrayOfDescriptionExtractors,
54-
$arrayOfAccessExtractors
66+
$listExtractors,
67+
$typeExtractors,
68+
$descriptionExtractors,
69+
$accessExtractors
5570
);
5671
57-
The order of extractor instances within an array matters, as the first non-null
72+
// see below for more examples
73+
$class = YourAwesomeCoolClass::class;
74+
$properties = $propertyInfo->getProperties($class);
75+
76+
Extractor Ordering
77+
~~~~~~~~~~~~~~~~~~
78+
79+
The order of extractor instances within an array matters: the first non-null
5880
result will be returned. That is why you must provide each category of extractors
5981
as a separate array, even if an extractor provides information for more than
6082
one category.
@@ -98,21 +120,26 @@ Extractable Information
98120
-----------------------
99121

100122
The :class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`
101-
class exposes public methods to extract four types of information: list,
102-
type, description and access information. The first type of information is
103-
about the class, while the remaining three are about the individual properties.
123+
class exposes public methods to extract four types of information:
124+
125+
* :ref:`*List* of properties <property-info-list>`: `getProperties()`
126+
* :ref:`Property *type* <property-info-type>`: `getTypes()`
127+
* :ref:`Property *description* <property-info-description>`: `getShortDescription()` and `getLongDescription()`
128+
* :ref:`Property *access* details <property-info-access>`: `isReadable()` and `isWritable()`
104129

105130
.. note::
106131

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

114-
Since the PropertyInfo component requires PHP 5.5 or greater, you can
115-
also make use of the `class constant`_.
137+
// Good!
138+
$propertyInfo->getProperties(get_class($awesomeObject));
139+
$propertyInfo->getProperties('Example\Namespace\YourAwesomeClass');
140+
$propertyInfo->getProperties(YourAwesomeClass::class);
141+
142+
.. _property-info-list:
116143

117144
List Information
118145
~~~~~~~~~~~~~~~~
@@ -134,6 +161,8 @@ containing each property name as a string.
134161
}
135162
*/
136163
164+
.. _property-info-type:
165+
137166
Type Information
138167
~~~~~~~~~~~~~~~~
139168

@@ -161,6 +190,10 @@ for a property.
161190
}
162191
*/
163192
193+
See :ref:`components-property-info-type` for info about the ``Type`` class.
194+
195+
.. _property-info-description:
196+
164197
Description Information
165198
~~~~~~~~~~~~~~~~~~~~~~~
166199

@@ -186,6 +219,8 @@ strings.
186219
It can span multiple lines.
187220
*/
188221
222+
.. _property-info-access:
223+
189224
Access Information
190225
~~~~~~~~~~~~~~~~~~
191226

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

205245
The main :class:`Symfony\\Component\\PropertyInfo\\PropertyInfoExtractor`
@@ -216,10 +256,9 @@ Type Objects
216256
------------
217257

218258
Compared to the other extractors, type information extractors provide much
219-
more information than can be represented as simple scalar values - because
220-
of this, type extractors return an array of objects. The array will contain
221-
an instance of the :class:`Symfony\\Component\\PropertyInfo\\Type`
222-
class for each type that the property supports.
259+
more information than can be represented as simple scalar values. Because
260+
of this, type extractors return an array of :class:`Symfony\\Component\\PropertyInfo\\Type`
261+
objects for each type that the property supports.
223262

224263
For example, if a property supports both ``integer`` and ``string`` (via
225264
the ``@return int|string`` annotation),
@@ -233,15 +272,12 @@ class.
233272
instance. The :class:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpDocExtractor`
234273
is currently the only extractor that returns multiple instances in the array.
235274

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

241277
.. _`components-property-info-type-builtin`:
242278

243-
Built-in Type
244-
~~~~~~~~~~~~~
279+
Type::getBuiltInType()
280+
~~~~~~~~~~~~~~~~~~~~~~
245281

246282
The :method:`Type::getBuiltinType() <Symfony\\Component\\PropertyInfo\\Type::getBuiltinType>`
247283
method will return the built-in PHP data type, which can be one of 9 possible
@@ -251,22 +287,22 @@ string values: ``array``, ``bool``, ``callable``, ``float``, ``int``, ``null``,
251287
Constants inside the :class:`Symfony\\Component\\PropertyInfo\\Type`
252288
class, in the form ``Type::BUILTIN_TYPE_*``, are provided for convenience.
253289

254-
Nullable
255-
~~~~~~~~
290+
Type::isNullable()
291+
~~~~~~~~~~~~~~~~~~
256292

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

261-
Class
262-
~~~~~
297+
Type::getClassName()
298+
~~~~~~~~~~~~~~~~~~~~
263299

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

268-
Collection
269-
~~~~~~~~~~
304+
Type::isCollection()
305+
~~~~~~~~~~~~~~~~~~~~
270306

271307
The :method:`Type::isCollection() <Symfony\\Component\\PropertyInfo\\Type::isCollection>`
272308
method will return a boolean value indicating if the property parameter is
@@ -278,8 +314,8 @@ this returns ``true`` if:
278314
* The mutator method the property is derived from has a prefix of ``add``
279315
or ``remove`` (which are defined as the list of array mutator prefixes).
280316

281-
Collection Key & Value Types
282-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
317+
Type::getCollectionKeyType() & Type::getCollectionValueType()
318+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
283319

284320
If the property is a collection, additional type objects may be returned
285321
for both the key and value types of the collection (if the information is
@@ -312,13 +348,14 @@ Using PHP reflection, the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\R
312348
provides list, type and access information from setter and accessor methods.
313349
It can also provide return and scalar types for PHP 7+.
314350

315-
This service is automatically registered with the ``property_info`` service.
351+
This service is automatically registered with the ``property_info`` service in
352+
the Symfony Framework.
316353

317354
.. code-block:: php
318355
319356
use Symfony\Component\PropertyInfo\Extractor\ReflectionExtractor;
320357
321-
$reflectionExtractor = new ReflectionExtractor;
358+
$reflectionExtractor = new ReflectionExtractor();
322359
323360
// List information.
324361
$reflectionExtractor->getProperties($class);
@@ -338,13 +375,14 @@ PhpDocExtractor
338375
Using `phpDocumentor Reflection`_ to parse property and method annotations,
339376
the :class:`Symfony\\Component\\PropertyInfo\\Extractor\\PhpDocExtractor`
340377
provides type and description information. This extractor is automatically
341-
registered with the ``property_info`` providing its dependencies are detected.
378+
registered with the ``property_info`` in the Symfony Framework *if* the dependent
379+
library is present.
342380

343381
.. code-block:: php
344382
345383
use Symfony\Component\PropertyInfo\Extractor\PhpDocExtractor;
346384
347-
$phpDocExtractor = new PhpDocExtractor;
385+
$phpDocExtractor = new PhpDocExtractor();
348386
349387
// Type information.
350388
$phpDocExtractor->getTypes($class, $property);
@@ -359,10 +397,11 @@ SerializerExtractor
359397

360398
This extractor depends on the `symfony/serializer`_ library.
361399

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

367406
.. code-block:: php
368407
@@ -389,9 +428,8 @@ DoctrineExtractor
389428

390429
Using entity mapping data from `Doctrine ORM`_, the
391430
:class:`Symfony\\Bridge\\Doctrine\\PropertyInfo\\DoctrineExtractor`
392-
- located in the Doctrine bridge - provides list and type information.
393-
This extractor is not registered automatically with the ``property_info``
394-
service.
431+
provides list and type information. This extractor is not registered automatically
432+
with the ``property_info`` service in the Symfony Framework.
395433

396434
.. code-block:: php
397435
@@ -440,4 +478,3 @@ service by defining it as a service with one or more of the following
440478
.. _`symfony/serializer`: https://packagist.org/packages/symfony/serializer
441479
.. _`symfony/doctrine-bridge`: https://packagist.org/packages/symfony/doctrine-bridge
442480
.. _`doctrine/orm`: https://packagist.org/packages/doctrine/orm
443-
.. _`class constant`: http://php.net/manual/en/language.oop5.basic.php#language.oop5.basic.class.class

‎console.rst

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -216,21 +216,16 @@ console::
216216
namespace Tests\AppBundle\Command;
217217

218218
use AppBundle\Command\CreateUserCommand;
219-
use Symfony\Component\Console\Application;
220-
// use this if you're in the Symfony Framework
221-
//use Symfony\Bundle\FrameworkBundle\Console\Application;
219+
use Symfony\Bundle\FrameworkBundle\Console\Application;
220+
use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
222221
use Symfony\Component\Console\Tester\CommandTester;
223222

224-
class CreateUserCommandTest extends \PHPUnit_Framework_TestCase
223+
class CreateUserCommandTest extends KernelTestCase
225224
{
226225
public function testExecute()
227226
{
228-
$application = new Application();
229-
230-
// if you're in the Symfony framework, do this instead
231-
// extend the KernelTestCase class
232-
// self::bootKernel();
233-
// $application = new Application(self::$kernel);
227+
self::bootKernel();
228+
$application = new Application(self::$kernel);
234229

235230
$application->add(new CreateUserCommand());
236231

@@ -259,6 +254,12 @@ console::
259254
You can also test a whole console application by using
260255
:class:`Symfony\\Component\\Console\\Tester\\ApplicationTester`.
261256

257+
.. note::
258+
259+
When using the Console component in a standalone project, use
260+
:class:`Symfony\\Component\\Console\\Application <Symfony\\Component\\Console\\Application>`
261+
and extend the normal ``\PHPUnit_Framework_TestCase``.
262+
262263
To be able to use the fully set up service container for your console tests
263264
you can extend your test from
264265
:class:`Symfony\\Bundle\\FrameworkBundle\\Test\\KernelTestCase`::

‎contributing/documentation/overview.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -261,10 +261,10 @@ link displayed for Platform.sh service.
261261
Build the Documentation Locally
262262
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
263263

264-
Alternatively you can build the documentation in your own computer for testing
264+
Alternatively you can build the documentation on your own computer for testing
265265
purposes following these steps:
266266

267-
#. Install `pip`_ as explained in the `pip installation`_ article.
267+
#. Install `pip`_ as explained in the `pip installation`_ article;
268268

269269
#. Install `Sphinx`_ and `Sphinx Extensions for PHP and Symfony`_
270270
(depending on your system, you may need to execute this command as root user):

0 commit comments

Comments
 (0)
0