8000 Review other reference articles · symfony/symfony-docs@08178a5 · GitHub
[go: up one dir, main page]

Skip to content

Commit 08178a5

Browse files
committed
Review other reference articles
1 parent c765aa5 commit 08178a5

File tree

3 files changed

+139
-110
lines changed

3 files changed

+139
-110
lines changed

reference/dic_tags.rst

Lines changed: 97 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@ The Dependency Injection Tags
22
=============================
33

44
Dependency Injection Tags are little strings that can be applied to a service
5-
to "flag" it to be used in some special way. For example, if you have a service
6-
that you would like to register as a listener to one of Symfony's core events,
7-
you can flag it with the ``kernel.event_listener`` tag.
5+
to "flag" it to be used in some special way. For example, if you have a
6+
service that you would like to register as a listener to one of Symfony's
7+
core events, you can flag it with the ``kernel.event_listener`` tag.
88

99
You can learn a little bit more about "tags" by reading the ":ref:`book-service-container-tags`"
1010
section of the Service Container chapter.
@@ -296,12 +296,13 @@ form.type_extension
296296
297297
**Purpose**: Create a custom "form extension"
298298
299-
Form type extensions are a way for you took "hook into" the creation of any
300-
field in your form. For example, the addition of the CSRF token is done via
301-
a form type extension (:class:`Symfony\\Component\\Form\\Extension\\Csrf\\Type\\FormTypeCsrfExtension`).
299+
Form type extensions are a way for you took "hook into" the creation of
300+
any field in your form. For example, the addition of the CSRF token is done
301+
via a form type extension
302+
(:class:`Symfony\\Component\\Form\\Extension\\Csrf\\Type\\FormTypeCsrfExtension`).
302303
303-
A form type extension can modify any part of any field in your form. To create
304-
a form type extension, first create a class that implements the
304+
A form type extension can modify any part of any field in your form. To
305+
create a form type extension, first create a class that implements the
305306
:class:`Symfony\\Component\\Form\\FormTypeExtensionInterface` interface.
306307
For simplicity, you'll often extend an
307308
:class:`Symfony\\Component\\Form\\AbstractTypeExtension` class instead of
@@ -318,8 +319,8 @@ the interface directly::
318319
// like buildForm(), buildView(), finishView(), setDefaultOptions()
319320
}
320321
321-
In order for Symfony to know about your form extension and use it, give it
322-
the ``form.type_extension`` tag:
322+
In order for Symfony to know about your form extension and use it, give
323+
it the ``form.type_extension`` tag:
323324
324325
.. configuration-block::
325326
@@ -351,13 +352,16 @@ the ``form.type_extension`` tag:
351352
.. code-block:: php
352353
353354
$container
354-
->register('main.form.type.my_form_type_extension', 'Acme\MainBundle\Form\Type\MyFormTypeExtension')
355+
->register(
356+
'main.form.type.my_form_type_extension',
357+
'Acme\MainBundle\Form\Type\MyFormTypeExtension'
358+
)
355359
->addTag('form.type_extension', array('alias' => 'field'))
356360
;
357361
358362
The ``alias`` key of the tag is the type of field that this extension should
359-
be applied to. For example, to apply the extension to any form/field, use the
360-
"form" value.
363+
be applied to. For example, to apply the extension to any form/field, use
364+
the "form" value.
361365
362366
.. _reference-dic-type_guesser:
363367
@@ -379,7 +383,8 @@ metadata and Doctrine metadata (if you're using Doctrine) or Propel metadata
379383
kernel.cache_clearer
380384
--------------------
381385
382-
**Purpose**: Register your service to be called during the cache clearing process
386+
**Purpose**: Register your service to be called during the cache clearing
387+
process
383388
384389
Cache clearing occurs whenever you call ``cache:clear`` command. If your
385390
bundle caches files, you should add custom cache clearer for clearing those
@@ -438,14 +443,15 @@ Then register this class and tag it with ``kernel.cache_clearer``:
438443
kernel.cache_warmer
439444
-------------------
440445
441-
**Purpose**: Register your service to be called during the cache warming process
446+
**Purpose**: Register your service to be called during the cache warming
447+
process
442448
443449
Cache warming occurs whenever you run the ``cache:warmup`` or ``cache:clear``
444-
task (unless you pass ``--no-warmup`` to ``cache:clear``). It is also run when
445-
handling the request, if it wasn't done by one of the commands yet. The purpose is
446-
to initialize any cache that will be needed by the application and prevent
447-
the first user from any significant "cache hit" where the cache is generated
448-
dynamically.
450+
task (unless you pass ``--no-warmup`` to ``cache:clear``). It is also run
451+
when handling the request, if it wasn't done by one of the commands yet.
452+
The purpose is to initialize any cache that will be needed by the application
453+
and prevent the first user from any significant "cache hit" where the cache
454+
is generated dynamically.
449455
450456
To register your own cache warmer, first create a service that implements
451457
the :class:`Symfony\\Component\\HttpKernel\\CacheWarmer\\CacheWarmerInterface` interface::
@@ -473,7 +479,8 @@ application without calling this cache warmer. In Symfony, optional warmers
473479
are always executed by default (you can change this by using the
474480
``--no-optional-warmers`` option when executing the command).
475481
476-
To register your warmer with Symfony, give it the ``kernel.cache_warmer`` tag:
482+
To register your warmer with Symfony, give it the ``kernel.cache_warmer``
483+
tag:
477484
478485
.. configuration-block::
479486
@@ -493,7 +500,9 @@ To register your warmer with Symfony, give it the ``kernel.cache_warmer`` tag:
493500
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
494501
495502
<services>
496-
<service id="main.warmer.my_custom_warmer" class="Acme\MainBundle\Cache\MyCustomWarmer">
503+
<service id="main.warmer.my_custom_warmer"
504+
class="Acme\MainBundle\Cache\MyCustomWarmer"
505+
>
497506
<tag name="kernel.cache_warmer" priority="0" />
498507
</service>
499508
</services>
@@ -508,8 +517,8 @@ To register your warmer with Symfony, give it the ``kernel.cache_warmer`` tag:
508517
509518
.. note::
510519
511-
The ``priority`` value is optional, and defaults to 0.
512-
The higher the priority, the sooner it gets executed.
520+
The ``priority`` value is optional and defaults to 0. The higher the
521+
priority, the sooner it gets executed.
513522
514523
Core Cache Warmers
515524
~~~~~~~~~~~~~~~~~~
@@ -629,7 +638,7 @@ kernel.event_subscriber
629638
**Purpose**: To subscribe to a set of different events/hooks in Symfony
630639
631640
To enable a custom subscriber, add it as a regular service in one of your
632-
configuration, and tag it with ``kernel.event_subscriber``:
641+
configuration and tag it with ``kernel.event_subscriber``:
633642
634643
.. configuration-block::
635644
@@ -661,7 +670,10 @@ configuration, and tag it with ``kernel.event_subscriber``:
661670
.. code-block:: php
662671
663672
$container
664-
->register('kernel.subscriber.your_subscriber_name', 'Fully\Qualified\Subscriber\Class\Name')
673+
->register(
674+
'kernel.subscriber.your_subscriber_name',
675+
'Fully\Qualified\Subscriber\Class\Name'
676+
)
665677
->addTag('kernel.event_subscriber')
666678
;
667679
@@ -672,8 +684,8 @@ configuration, and tag it with ``kernel.event_subscriber``:
672684
673685
.. note::
674686
675-
If your service is created by a factory, you **MUST** correctly set the ``class``
676-
parameter for this tag to work correctly.
687+
If your service is created by a factory, you **MUST** correctly set
688+
the ``class`` parameter for this tag to work correctly.
677689
678690
kernel.fragment_renderer
679691
------------------------
@@ -724,7 +736,9 @@ channel when injecting the logger in a service.
724736
725737
.. code-block:: php
726738
727-
$definition = new Definition('Fully\Qualified\Loader\Class\Name', array(new Reference('logger'));
739+
$definition = new Definition('Fully\Qualified\Loader\Class\Name', array(
740+
new Reference('logger'),
741+
));
728742
$definition->addTag('monolog.logger', array('channel' => 'acme'));
729743
$container->setDefinition('my_service', $definition);
730744
@@ -741,13 +755,13 @@ monolog.processor
741755
742756
**Purpose**: Add a custom processor for logging
743757
744-
Monolog allows you to add processors in the logger or in the handlers to add
745-
extra data in the records. A processor receives the record as an argument and
746-
must return it after adding some extra data in the ``extra`` attribute of
747-
the record.
758+
Monolog allows you to add processors in the logger or in the handlers to
759+
add extra data in the records. A processor receives the record as an argument
760+
and must return it after adding some extra data in the ``extra`` attribute
761+
of the record.
748762
749-
The built-in ``IntrospectionProcessor`` can be used to add the file, the line,
750-
the class and the method where the logger was triggered.
763+
The built-in ``IntrospectionProcessor`` can be used to add the file, the
764+
line, the class and the method where the logger was triggered.
751765
752766
You can add a processor globally:
753767
@@ -821,9 +835,9 @@ attribute:
821835
->addTag('monolog.processor', array('handler' => 'firephp'))
822836
;
823837
824-
You can also add a processor for a specific logging channel by using the ``channel``
825-
attribute. This will register the processor only for the ``security`` logging
826-
channel used in the Security component:
838+
You can also add a processor for a specific logging channel by using the
839+
``channel`` attribute. This will register the processor only for the
840+
``security`` logging channel used in the Security component:
827841
828842
.. configuration-block::
829843
@@ -867,7 +881,7 @@ routing.loader
867881
**Purpose**: Register a custom service that loads routes
868882
869883
To enable a custom routing loader, add it as a regular service in one
870-
of your configuration, and tag it with ``routing.loader``:
884+
of your configuration and tag it with ``routing.loader``:
871885
872886
.. configuration-block::
873887
@@ -910,9 +924,9 @@ security.remember_me_aware
910924
911925
**Purpose**: To allow remember me authentication
912926
913-
This tag is used internally to allow remember-me authentication to work. If
914-
you have a custom authentication method where a user can be remember-me authenticated,
915-
then you may need to use this tag.
927+
This tag is used internally to allow remember-me authentication to work.
928+
If you have a custom authentication method where a user can be remember-me
929+
authenticated, then you may need to use this tag.
916930
917931
If your custom authentication factory extends
918932
:class:`Symfony\\Bundle\\SecurityBundle\\DependencyInjection\\Security\\Factory\\AbstractFactory`
@@ -961,15 +975,16 @@ swiftmailer.default.plugin
961975
962976
**Purpose**: Register a custom SwiftMailer Plugin
963977
964-
If you're using a custom SwiftMailer plugin (or want to create one), you can
965-
register it with SwiftMailer by creating a service for your plugin and tagging
966-
it with ``swiftmailer.default.plugin`` (it has no options).
978+
If you're using a custom SwiftMailer plugin (or want to create one), you
979+
can register it with SwiftMailer by creating a service for your plugin and
980+
tagging it with ``swiftmailer.default.plugin`` (it has no options).
967981
968982
.. note::
969983
970984
``default`` in this tag is the name of the mailer. If you have multiple
971-
mailers configured or have changed the default mailer name for some reason,
972-
you should change it to the name of your mailer in order to use this tag.
985+
mailers configured or have changed the default mailer name for some
986+
reason, you should change it to the name of your mailer in order to
987+
use this tag.
973988
974989
A SwiftMailer plugin must implement the ``Swift_Events_EventListener`` interface.
975990
For more information on plugins, see `SwiftMailer's Plugin Documentation`_.
@@ -1028,8 +1043,8 @@ translation.loader
10281043
10291044
**Purpose**: To register a custom service that loads translations
10301045
1031-
By default, translations are loaded from the filesystem in a variety of different
1032-
formats (YAML, XLIFF, PHP, etc).
1046+
By default, translations are loaded from the filesystem in a variety of
1047+
different formats (YAML, XLIFF, PHP, etc).
10331048
10341049
.. seealso::
10351050
@@ -1068,19 +1083,23 @@ Now, register your loader as a service and tag it with ``translation.loader``:
10681083
.. code-block:: php
10691084
10701085
$container
1071-
->register('main.translation.my_custom_loader', 'Acme\MainBundle\Translation\MyCustomLoader')
1086+
->register(
1087+
'main.translation.my_custom_loader',
1088+
'Acme\MainBundle\Translation\MyCustomLoader'
1089+
)
10721090
->addTag('translation.loader', array('alias' => 'bin'))
10731091
;
10741092
10751093
The ``alias`` option is required and very important: it defines the file
1076-
"suffix" that will be used for the resource files that use this loader. For
1077-
example, suppose you have some custom ``bin`` format that you need to load.
1078-
If you have a ``bin`` file that contains French translations for the ``messages``
1079-
domain, then you might have a file ``app/Resources/translations/messages.fr.bin``.
1094+
"suffix" that will be used for the resource files that use this loader.
1095+
For example, suppose you have some custom ``bin`` format that you need to
1096+
load. If you have a ``bin`` file that contains French translations for
1097+
the ``messages`` domain, then you might have a file
1098+
``app/Resources/translations/messages.fr.bin``.
10801099
1081-
When Symfony tries to load the ``bin`` file, it passes the path to your custom
1082-
loader as the ``$resource`` argument. You can then perform any logic you need
1083-
on that file in order to load your translations.
1100+
When Symfony tries to load the ``bin`` file, it passes the path to your
1101+
custom loader as the ``$resource`` argument. You can then perform any logic
1102+
you need on that file in order to load your translations.
10841103
10851104
If you're loading translations from a database, you'll still need a resource
10861105
file, but it might either be blank or contain a little bit of information
@@ -1090,7 +1109,8 @@ the ``load`` method on your custom loader.
10901109
translation.extractor
10911110
---------------------
10921111
1093-
**Purpose**: To register a custom service that extracts messages from a file
1112+
**Purpose**: To register a custom service that extracts messages from a
1113+
file
10941114
10951115
.. versionadded:: 2.1
10961116
The ability to add message extractors was introduced in Symfony 2.1.
@@ -1102,9 +1122,9 @@ has a :class:`Symfony\\Bridge\\Twig\\Translation\\TwigExtractor` and a
11021122
help to find and extract translation keys from Twig templates and PHP files.
11031123
11041124
You can create your own extractor by creating a class that implements
1105-
:class:`Symfony\\Component\\Translation\\Extractor\\ExtractorInterface` and
1106-
tagging the service with ``translation.extractor``. The tag has one required
1107-
option: ``alias``, which defines the name of the extractor::
1125+
:class:`Symfony\\Component\\Translation\\Extractor\\ExtractorInterface`
1126+
and tagging the service with ``translation.extractor``. The tag has one
1127+
required option: ``alias``, which defines the name of the extractor::
11081128
11091129
// src/Acme/DemoBundle/Translation/FooExtractor.php
11101130
namespace Acme\DemoBundle\Translation;
@@ -1176,9 +1196,9 @@ translation.dumper
11761196
.. versionadded:: 2.1
11771197
The ability to add message dumpers was introduced in Symfony 2.1.
11781198
1179-
After an `Extractor <translation.extractor>`_ has extracted all messages from
1180-
the templates, the dumpers are executed to dump the messages to a translation
1181-
file in a specific format.
1199+
After an `Extractor <translation.extractor>`_ has extracted all messages
1200+
from the templates, the dumpers are executed to dump the messages to a
1201+
translation file in a specific format.
11821202
11831203
Symfony already comes with many dumpers:
11841204
@@ -1245,7 +1265,7 @@ twig.extension
12451265
**Purpose**: To register a custom Twig Extension
12461266
12471267
To enable a Twig extension, add it as a regular service in one of your
1248-
configuration, and tag it with ``twig.extension``:
1268+
configuration and tag it with ``twig.extension``:
12491269
12501270
.. configuration-block::
12511271
@@ -1277,7 +1297,10 @@ configuration, and tag it with ``twig.extension``:
12771297
.. code-block:: php
12781298
12791299
$container
1280-
->register('twig.extension.your_extension_name', 'Fully\Qualified\Extension\Class\Name')
1300+
->register(
1301+
'twig.extension.your_extension_name',
1302+
'Fully\Qualified\Extension\Class\Name'
1303+
)
12811304
->addTag('twig.extension')
12821305
;
12831306
@@ -1362,7 +1385,10 @@ the new loader and tag it with ``twig.loader``:
13621385
.. code-block:: php
13631386
13641387
$container
1365-
->register('acme.demo_bundle.loader.some_twig_loader', 'Acme\DemoBundle\Loader\SomeTwigLoader')
1388+
->register(
1389+
'acme.demo_bundle.loader.some_twig_loader',
1390+
'Acme\DemoBundle\Loader\SomeTwigLoader'
1391+
)
13661392
->addTag('twig.loader')
13671393
;
13681394
@@ -1383,14 +1409,15 @@ This tag provides a very uncommon piece of functionality that allows you
13831409
to perform some sort of action on an object right before it's validated.
13841410
For example, it's used by Doctrine to query for all of the lazily-loaded
13851411
data on an object before it's validated. Without this, some data on a Doctrine
1386-
entity would appear to be "missing" when validated, even though this is not
1387-
really the case.
1412+
entity would appear to be "missing" when validated, even though this is
1413+
not really the case.
13881414
13891415
If you do need to use this tag, just make a new class that implements the
13901416
:class:`Symfony\\Component\\Validator\\ObjectInitializerInterface` interface.
13911417
Then, tag it with the ``validator.initializer`` tag (it has no options).
13921418
1393-
For an example, see the ``EntityInitializer`` class inside the Doctrine Bridge.
1419+
For an example, see the ``EntityInitializer`` class inside the Doctrine
1420+
Bridge.
13941421
13951422
.. _`Twig's documentation`: http://twig.sensiolabs.org/doc/advanced.html#creating-an-extension
13961423
.. _`Twig official extension repository`: https://github.com/twigphp/Twig-extensions

reference/requirements.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@
66
Requirements for Running Symfony
77
================================
88

9-
To run Symfony, your system needs to adhere to a list of requirements. You can
10-
easily see if your system passes all requirements by running the ``web/config.php``
11-
in your Symfony distribution. Since the CLI often uses a different ``php.ini``
12-
configuration file, it's also a good idea to check your requirements from
13-
the command line via:
9+
To run Symfony, your system needs to adhere to a list of requirements. You
10+
can easily see if your system passes all requirements by running the
11+
``web/config.php`` in your Symfony distribution. Since the CLI often uses
12+
a different ``php.ini`` configuration file, it's also a good idea to check
13+
your requirements from the command line via:
1414

1515
.. code-block:: bash
1616

0 commit comments

Comments
 (0)
0