8000 minor #4539 Normalization of method listings (pedronofuentes) · symfony/symfony-docs@96455e6 · GitHub
[go: up one dir, main page]
Skip to content

Commit 96455e6

Browse files
weaverryanweaverryan
committed
minor #4539 Normalization of method listings (pedronofuentes)
This PR was merged into the 2.3 branch. Discussion ---------- Normalization of method listings | Q | A | ------------- | --- | Doc fix? | no | New docs? | no | Applies to | all | Fixed tickets | fixes #3903 Commits ------- 3fd3963 Changed to definition lists from Book section dda1905 Changed to definition lists 3649bdb Fixed heading capitalization to follow the standards 6b68e48 Changed paragraph to heading 1d571ca Changed unordered list to definition list
2 parents 5842f5c + 3fd3963 commit 96455e6

14 files changed

+309
-257
lines changed

‎book/forms.rst

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -716,14 +716,16 @@ the correct values of a number of field options.
716716
And though you'll need to manually add your server-side validation, these
717717
field type options can then be guessed from that information.
718718

719-
* ``required``: The ``required`` option can be guessed based on the validation
720-
rules (i.e. is the field ``NotBlank`` or ``NotNull``) or the Doctrine metadata
721-
(i.e. is the field ``nullable``). This is very useful, as your client-side
722-
validation will automatically match your validation rules.
719+
``required``
720+
The ``required`` option can be guessed based on the validation rules (i.e. is
721+
the field ``NotBlank`` or ``NotNull``) or the Doctrine metadata (i.e. is the
722+
field ``nullable``). This is very useful, as your client-side validation will
723+
automatically match your validation rules.
723724

724-
* ``max_length``: If the field is some sort of text field, then the ``max_length``
725-
option can be guessed from the validation constraints (if ``Length`` or
726-
``Range`` is used) or from the Doctrine metadata (via the field's length).
725+
``max_length``
726+
If the field is some sort of text field, then the ``max_length`` option can be
727+
guessed from the validation constraints (if ``Length`` or ``Range`` is used) or
728+
from the Doctrine metadata (via the field's length).
727729

728730
.. note::
729731

@@ -771,12 +773,13 @@ of code. Of course, you'll usually need much more flexibility when rendering:
771773
You already know the ``form_start()`` and ``form_end()`` functions, but what do
772774
the other functions do?
773775

774-
* ``form_errors(form)`` - Renders any errors global to the whole form
775-
(field-specific errors are displayed next to each field);
776+
``form_errors(form)``
777+
Renders any errors global to the whole form (field-specific errors are displayed
778+
next to each field).
776779

777-
* ``form_row(form.dueDate)`` - Renders the label, any errors, and the HTML
778-
form widget for the given field (e.g. ``dueDate``) inside, by default, a
779-
``div`` element.
780+
``form_row(form.dueDate)``
781+
Renders the label, any errors, and the HTML form widget for the given field
782+
(e.g. ``dueDate``) inside, by default, a ``div`` element.
780783

781784
The majority of the work is done by the ``form_row`` helper, which renders
782785
the label, errors and HTML form widget of each field inside a ``div`` tag by

‎book/http_cache.rst

Lines changed: 45 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -202,34 +202,39 @@ method::
202202

203203
Here is a list of the main options:
204204

205-
* ``default_ttl``: The number of seconds that a cache entry should be
206-
considered fresh when no explicit freshness information is provided in a
207-
response. Explicit ``Cache-Control`` or ``Expires`` headers override this
208-
value (default: ``0``);
209-
210-
* ``private_headers``: Set of request headers that trigger "private"
211-
``Cache-Control`` behavior on responses that don't explicitly state whether
212-
the response is ``public`` or ``private`` via a ``Cache-Control`` directive.
213-
(default: ``Authorization`` and ``Cookie``);
214-
215-
* ``allow_reload``: Specifies whether the client can force a cache reload by
216-
including a ``Cache-Control`` "no-cache" directive in the request. Set it to
217-
``true`` for compliance with RFC 2616 (default: ``false``);
218-
219-
* ``allow_revalidate``: Specifies whether the client can force a cache
220-
revalidate by including a ``Cache-Control`` "max-age=0" directive in the
221-
request. Set it to ``true`` for compliance with RFC 2616 (default: false);
222-
223-
* ``stale_while_revalidate``: Specifies the default number of seconds (the
224-
granularity is the second as the Response TTL precision is a second) during
225-
which the cache can immediately return a stale response while it revalidates
226-
it in the background (default: ``2``); this setting is overridden by the
227-
``stale-while-revalidate`` HTTP ``Cache-Control`` extension (see RFC 5861);
228-
229-
* ``stale_if_error``: Specifies the default number of seconds (the granularity
230-
is the second) during which the cache can serve a stale response when an
231-
error is encountered (default: ``60``). This setting is overridden by the
232-
``stale-if-error`` HTTP ``Cache-Control`` extension (see RFC 5861).
205+
``default_ttl``
206+
The number of seconds that a cache entry should be considered fresh when no
207+
explicit freshness information is provided in a response. Explicit
208+
``Cache-Control`` or ``Expires`` headers override this value (default: ``0``).
209+
210+
``private_headers``
211+
Set of request headers that trigger "private" ``Cache-Control`` behavior on
212+
responses that don't explicitly state whether the response is ``public`` or
213+
``private`` via a ``Cache-Control`` directive (default: ``Authorization``
214+
and ``Cookie``).
215+
216+
``allow_reload``
217+
Specifies whether the client can force a cache reload by including a
218+
``Cache-Control`` "no-cache" directive in the request. Set it to ``true`` for
219+
compliance with RFC 2616 (default: ``false``).
220+
221+
``allow_revalidate``
222+
Specifies whether the client can force a cache revalidate by including a
223+
``Cache-Control`` "max-age=0" directive in the request. Set it to ``true`` for
224+
compliance with RFC 2616 (default: false).
225+
226+
``stale_while_revalidate``
227+
Specifies the default number of seconds (the granularity is the second as the
228+
Response TTL precision is a second) during which the cache can immediately
229+
return a stale response while it revalidates it in the background (default:
230+
``2``); this setting is overridden by the ``stale-while-revalidate`` HTTP
231+
``Cache-Control`` extension (see RFC 5861).
232+
233+
``stale_if_error``
234+
Specifies the default number of seconds (the granularity is the second) during
235+
which the cache can serve a stale response when an error is encountered
236+
(default: ``60``). This setting is overridden by the ``stale-if-error`` HTTP
237+
``Cache-Control`` extension (see RFC 5861).
233238

234239
If ``debug`` is ``true``, Symfony automatically adds a ``X-Symfony-Cache``
235240
header to the response containing useful information about cache hits and
@@ -339,11 +344,12 @@ and then returned to every subsequent user who asked for their account page!
339344

340345
To handle this situation, every response may be set to be public or private:
341346

342-
* *public*: Indicates that the response may be cached by both private and
343-
shared caches;
347+
*public*
348+
Indicates that the response may be cached by both private and shared caches.
344349

345-
* *private*: Indicates that all or part of the response message is intended
346-
for a single user and must not be cached by a shared cache.
350+
*private*
351+
Indicates that all or part of the response message is intended for a single
352+
user and must not be cached by a shared cache.
347353

348354
Symfony conservatively defaults each response to be private. To take advantage
349355
of shared caches (like the Symfony reverse proxy), the response will need
@@ -1033,12 +1039,14 @@ possible.
10331039

10341040
The ``render_esi`` helper supports two other useful options:
10351041

1036-
* ``alt``: used as the ``alt`` attribute on the ESI tag, which allows you
1037-
to specify an alternative URL to be used if the ``src`` cannot be found;
1042+
``alt``
1043+
Used as the ``alt`` attribute on the ESI tag, which allows you to specify an
1044+
alternative URL to be used if the ``src`` cannot be found.
10381045

1039-
* ``ignore_errors``: if set to true, an ``onerror`` attribute will be added
1040-
to the ESI with a value of ``continue`` indicating that, in the event of
1041-
a failure, the gateway cache will simply remove the ESI tag silently.
1046+
``ignore_errors``
1047+
If set to true, an ``onerror`` attribute will be added to the ESI with a value
1048+
of ``continue`` indicating that, in the event of a failure, the gateway cache
1049+
will simply remove the ESI tag silently.
10421050

10431051
.. index::
10441052
single: Cache; Invalidation

‎book/http_fundamentals.rst

Lines changed: 20 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -515,30 +515,32 @@ libraries that can be used inside *any* PHP project. These libraries, called
515515
the *Symfony Components*, contain something useful for almost any situation,
516516
regardless of how your project is developed. To name a few:
517517

518-
* :doc:`HttpFoundation </components/http_foundation/introduction>` - Contains
519-
the ``Request`` and ``Response`` classes, as well as other classes for handling
520-
sessions and file uploads;
518+
:doc:`HttpFoundation </components/http_foundation/introduction>`
519+
Contains the ``Request`` and ``Response`` classes, as well as other classes for
520+
handling sessions and file uploads.
521521

522-
* :doc:`Routing </components/routing/introduction>` - Powerful and fast routing system that
523-
allows you to map a specific URI (e.g. ``/contact``) to some information
524-
about how that request should be handled (e.g. execute the ``contactAction()``
525-
method);
522+
:doc:`Routing </components/routing/introduction>`
523+
Powerful and fast routing system that allows you to map a specific URI
524+
(e.g. ``/contact``) to some information about how that request should be handled
525+
(e.g. execute the ``contactAction()`` method).
526526

527-
* :doc:`Form </components/form/introduction>` - A full-featured and flexible
528-
framework for creating forms and handling form submissions;
527+
:doc:`Form </components/form/introduction>`
528+
A full-featured and flexible framework for creating forms and handling form
529+
submissions.
529530

530-
* `Validator`_ - A system for creating rules about data and then validating
531-
whether or not user-submitted data follows those rules;
531+
`Validator`_
532+
A system for creating rules about data and then validating whether or not
533+
user-submitted data follows those rules.
532534

533-
* :doc:`Templating </components/templating/introduction>` - A toolkit for rendering
534-
templates, handling template inheritance (i.e. a template is decorated with
535-
a layout) and performing other common template tasks;
535+
:doc:`Templating </components/templating/introduction>`
536+
A toolkit for rendering templates, handling template inheritance (i.e. a
537+
template is decorated with a layout) and performing other common template tasks.
536538

537-
* :doc:`Security </components/security/introduction>` - A powerful library for
538-
handling all types of security inside an application;
539+
:doc:`Security </components/security/introduction>`
540+
A powerful library for handling all types of security inside an application.
539541

540-
* :doc:`Translation </components/translation/introduction>` - A framework for
541-
translating strings in your application.
542+
:doc:`Translation </components/translation/introduction>`
543+
A framework for translating strings in your application.
542544

543545
Each and every one of these components is decoupled and can be used in *any*
544546
PHP project, regardless of whether or not you use the Symfony framework.

‎book/internals.rst

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -212,15 +212,15 @@ Each event thrown by the Kernel is a subclass of
212212
:class:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent`. This means that
213213
each event has access to the same basic information:
214214

215-
* :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequestType`
216-
- returns the *type* of the request (``HttpKernelInterface::MASTER_REQUEST``
217-
or ``HttpKernelInterface::SUB_REQUEST``);
215+
:method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequestType`
216+
Returns the *type* of the request (``HttpKernelInterface::MASTER_REQUEST`` or
217+
``HttpKernelInterface::SUB_REQUEST``).
218218

219-
* :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getKernel`
220-
- returns the Kernel handling the request;
219+
:method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getKernel`
220+
Returns the Kernel handling the request.
221221

222-
* :method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequest`
223-
- returns the current ``Request`` being handled.
222+
:method:`Symfony\\Component\\HttpKernel\\Event\\KernelEvent::getRequest`
223+
Returns the current ``Request`` being handled.
224224

225225
``getRequestType()``
226226
....................
@@ -347,18 +347,18 @@ The purpose of this event is to allow other systems to modify or replace the
347347

348348
The FrameworkBundle registers several listeners:
349349

350-
* :class:`Symfony\\Component\\HttpKernel\\EventListener\\ProfilerListener`:
351-
collects data for the current request;
350+
:class:`Symfony\\Component\\HttpKernel\\EventListener\\ProfilerListener`
351+
Collects data for the current request.
352352

353-
* :class:`Symfony\\Bundle\\WebProfilerBundle\\EventListener\\WebDebugToolbarListener`:
354-
injects the Web Debug Toolbar;
353+
:class:`Symfony\\Bundle\\WebProfilerBundle\\EventListener\\WebDebugToolbarListener`
354+
Injects the Web Debug Toolbar.
355355

356-
* :class:`Symfony\\Component\\HttpKernel\\EventListener\\ResponseListener`: fixes the
357-
Response ``Content-Type`` based on the request format;
356+
:class:`Symfony\\Component\\HttpKernel\\EventListener\\ResponseListener`
357+
Fixes the Response ``Content-Type`` based on the request format.
358358

359-
* :class:`Symfony\\Component\\HttpKernel\\EventListener\\EsiListener`: adds a
360-
``Surrogate-Control`` HTTP header when the Response needs to be parsed for
361-
ESI tags.
359+
:class:`Symfony\\Component\\HttpKernel\\EventListener\\EsiListener`
360+
Adds a ``Surrogate-Control`` HTTP header when the Response needs to be parsed
361+
for ESI tags.
362362

363363
.. seealso::
364364

‎book/page_creation.rst

Lines changed: 30 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -488,13 +488,17 @@ you'll know where to find and put different types of files and why.
488488
Though entirely flexible, by default, each Symfony :term:`application` has
489489
the same basic and recommended directory structure:
490490

491-
* ``app/``: This directory contains the application configuration;
491+
``app/``
492+
This directory contains the application configuration.
492493

493-
* ``src/``: All the project PHP code is stored under this directory;
494+
``src/``
495+
All the project PHP code is stored under this directory.
494496

495-
* ``vendor/``: Any vendor libraries are placed here by convention;
497+
``vendor/``
498+
Any vendor libraries are placed here by convention.
496499

497-
* ``web/``: This is the web root directory and contains any publicly accessible files;
500+
``web/``
501+
This is the web root directory and contains any publicly accessible files.
498502

499503
.. _the-web-directory:
500504

@@ -554,11 +558,13 @@ needs to know about your application. You don't even need to worry about
554558
these methods when starting - Symfony fills them in for you with sensible
555559
defaults.
556560

557-
* ``registerBundles()``: Returns an array of all bundles needed to run the
558-
application (see :ref:`page-creation-bundles`);
561+
``registerBundles()``
562+
Returns an array of all bundles needed to run the application (see
563+
:ref:`page-creation-bundles`).
559564

560-
* ``registerContainerConfiguration()``: Loads the main application configuration
561-
resource file (see the `Application Configuration`_ section).
565+
``registerContainerConfiguration()``
566+
Loads the main application configuration resource file (see the
567+
`Application Configuration`_ section).
562568

563569
In day-to-day development, you'll mostly use the ``app/`` directory to modify
564570
configuration and routing files in the ``app/config/`` directory (see
@@ -743,23 +749,27 @@ bundle system follows a set of conventions that help to keep code consistent
743749
between all Symfony bundles. Take a look at ``AcmeDemoBundle``, as it contains
744750
some of the most common elements of a bundle:
745751

746-
* ``Controller/`` contains the controllers of the bundle (e.g. ``RandomController.php``);
752+
``Controller/``
753+
Contains the controllers of the bundle (e.g. ``RandomController.php``).
747754

748-
* ``DependencyInjection/`` holds certain dependency injection extension classes,
749-
which may import service configuration, register compiler passes or more
750-
(this directory is not necessary);
755+
``DependencyInjection/``
756+
Holds certain dependency injection extension classes, which may import service
757+
configuration, register compiler passes or more (this directory is not
758+
necessary).
751759

752-
* ``Resources/config/`` houses configuration, including routing configuration
753-
(e.g. ``routing.yml``);
760+
``Resources/config/``
761+
Houses configuration, including routing configuration (e.g. ``routing.yml``).
754762

755-
* ``Resources/views/`` holds templates organized by controller name (e.g.
756-
``Hello/index.html.twig``);
763+
``Resources/views/``
764+
Holds templates organized by controller name (e.g. ``Hello/index.html.twig``).
757765

758-
* ``Resources/public/`` con 10000 tains web assets (images, stylesheets, etc) and is
759-
copied or symbolically linked into the project ``web/`` directory via
760-
the ``assets:install`` console command;
766+
``Resources/public/``
767+
Contains web assets (images, stylesheets, etc) and is copied or symbolically
768+
linked into the project ``web/`` directory via the ``assets:install`` console
769+
command.
761770

762-
* ``Tests/`` holds all tests for the bundle.
771+
``Tests/``
772+
Holds all tests for the bundle.
763773

764774
A bundle can be as small or large as the feature it implements. It contains
765775
only the files you need and nothing else.

‎book/propel.rst

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -467,14 +467,22 @@ To add a hook, just add a new method to the object class::
467467

468468
Propel provides the following hooks:
469469

470-
* ``preInsert()`` code executed before insertion of a new object
471-
* ``postInsert()`` code executed after insertion of a new object
472-
* ``preUpdate()`` code executed before update of an existing object
473-
* ``postUpdate()`` code executed after update of an existing object
474-
* ``preSave()`` code executed before saving an object (new or existing)
475-
* ``postSave()`` code executed after saving an object (new or existing)
476-
* ``preDelete()`` code executed before deleting an object
477-
* ``postDelete()`` code executed after deleting an object
470+
``preInsert()``
471+
Code executed before insertion of a new object.
472+
``postInsert()``
473+
Code executed after insertion of a new object.
474+
``preUpdate()``
475+
Code executed before update of an existing object.
476+
``postUpdate()``
477+
Code executed after update of an existing object.
478+
``preSave()``
479+
Code executed before saving an object (new or existing).
480+
``postSave()``
481+
Code executed after saving an object (new or existing).
482+
``preDelete()``
483+
Code executed before deleting an object.
484+
``postDelete()``
485+
Code executed after deleting an object.
478486

479487
Behaviors
480488
---------

‎book/routing.rst

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1036,12 +1036,15 @@ As you've seen, each routing parameter or default value is eventually available
10361036
as an argument in the controller method. Additionally, there are three parameters
10371037
that are special: each adds a unique piece of functionality inside your application:
10381038

1039-
* ``_controller``: As you've seen, this parameter is used to determine which
1040-
controller is executed when the route is matched;
1039+
``_controller``
1040+
As you've seen, this parameter is used to determine which controller is
1041+
executed when the route is matched.
10411042

1042-
* ``_format``: Used to set the request format (:ref:`read more <book-routing-format-param>`);
1043+
``_format``
1044+
Used to set the request format (:ref:`read more <book-routing-format-param>`).
10431045

1044-
* ``_locale``: Used to set the locale on the request (:ref:`read more <book-translation-locale-url>`).
1046+
``_locale``
1047+
Used to set the locale on the request (:ref:`read more <book-translation-locale-url>`).
10451048

10461049
.. index::
10471050
single: Routing; Controllers

0 commit comments

Comments
 (0)
0