10000 A bunch of doc fixes again by wouterj · Pull Request #5546 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

A bunch of doc fixes again #5546

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

Merged
merged 3 commits into from
Jul 21, 2015
Merged

A bunch of doc fixes again #5546

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
74267cd
Fixes due to docbot linting docs
wouterj Jun 25, 2015
63ccd0d
Finalize review of reference documentation
wouterj Jun 25, 2015
9a94a41
Review Quick Tour articles once again
wouterj Jun 25, 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
6 changes: 3 additions & 3 deletions quick_tour/the_big_picture.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,12 +106,12 @@ Congratulations! Your first Symfony project is up and running!
them are explained in the
:ref:`Setting up Permissions <book-installation-permissions>` section
of the official book.

If the welcome page does not seem to be rendering CSS or image assets,
install them first:

.. code-block:: bash

$ php app/console assets:install

When you are finished working on your Symfony application, you can stop
Expand Down
126 changes: 66 additions & 60 deletions reference/configuration/doctrine.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -324,8 +324,8 @@ you can control. The following configuration options exist for a mapping:
type
....

One of ``annotation``, ``xml``, ``yml``, ``php`` or ``staticphp``. This specifies
which type of metadata type your mapping uses.
One of ``annotation``, ``xml``, ``yml``, ``php`` or ``staticphp``. This
specifies which type of metadata type your mapping uses.

dir
...
Expand All @@ -339,27 +339,27 @@ that exist in the DIC (for example ``%kernel.root_dir%``).
prefix
......

A common namespace prefix that all entities of this mapping share. This prefix
should never conflict with prefixes of other defined mappings otherwise some
of your entities cannot be found by Doctrine. This option defaults to the
bundle namespace + ``Entity``, for example for an application bundle called
AcmeHelloBundle prefix would be ``Acme\HelloBundle\Entity``.
A common namespace prefix that all entities of this mapping share. This
prefix should never conflict with prefixes of other defined mappings otherwise
some of your entities cannot be found by Doctrine. This option defaults
to the bundle namespace + ``Entity``, for example for an application bundle
called AcmeHelloBundle prefix would be ``Acme\HelloBundle\Entity``.

alias
.....

Doctrine offers a way to alias entity namespaces to simpler, shorter names
to be used in DQL queries or for Repository access. When using a bundle the
alias defaults to the bundle name.
to be used in DQL queries or for Repository access. When using a bundle
the alias defaults to the bundle name.

is_bundle
.........

This option is a derived value from ``dir`` and by default is set to ``true``
if dir is relative proved by a ``file_exists()`` check that returns ``false``.
It is ``false`` if the existence check returns ``true``. In this case an
absolute path was specified and the metadata files are most likely in a directory
outside of a bundle.
absolute path was specified and the metadata files are most likely in a
directory outside of a bundle.

.. index::
single: Configuration; Doctrine DBAL
Expand Down Expand Up @@ -448,14 +448,15 @@ The following block shows all possible configuration keys:

.. note::

The ``server_version`` option was added in Doctrine DBAL 2.5, which is used
by DoctrineBundle 1.3. The value of this option should match your database
server version (use ``postgres -V`` or ``psql -V`` command to find
your PostgreSQL version and ``mysql -V`` to get your MySQL version).
The ``server_version`` option was added in Doctrine DBAL 2.5, which
is used by DoctrineBundle 1.3. The value of this option should match
your database server version (use ``postgres -V`` or ``psql -V`` command
to find your PostgreSQL version and ``mysql -V`` to get your MySQL
version).

If you don't define this option and you haven't created your database yet,
you may get ``PDOException`` errors because Doctrine will try to guess the
database server version automatically and none is available.
If you don't define this option and you haven't created your database
yet, you may get ``PDOException`` errors because Doctrine will try to
guess the database server version automatically and none is available.

If you want to configure multiple connections in YAML, put them under the
``connections`` key and give them a unique name:
Expand Down Expand Up @@ -524,24 +525,26 @@ Keep in mind that you can't use both syntaxes at the same time.
Custom Mapping Entities in a Bundle
-----------------------------------

Doctrine's ``auto_mapping`` feature loads annotation configuration from the
``Entity/`` directory of each bundle *and* looks for other formats (e.g. YAML, XML)
in the ``Resources/config/doctrine`` directory.
Doctrine's ``auto_mapping`` feature loads annotation configuration from
the ``Entity/`` directory of each bundle *and* looks for other formats (e.g.
YAML, XML) in the ``Resources/config/doctrine`` directory.

If you store metadata somewhere else in your bundle, you can define your own mappings,
where you tell Doctrine exactly *where* to look, along with some other configurations.
If you store metadata somewhere else in your bundle, you can define your
own mappings, where you tell Doctrine exactly *where* to look, along with
some other configurations.

If you're using the ``auto_mapping`` configuration, you just need to overwrite the
configurations you want. In this case it's important that the key of the mapping
configurations corresponds to the name of the bundle.
If you're using the ``auto_mapping`` configuration, you just need to overwrite
the configurations you want. In this case it's important that the key of
the mapping configurations corresponds to the name of the bundle.

For example, suppose you decide to store your ``XML`` configuration for ``AppBundle`` entities
in the ``@AppBundle/SomeResources/config/doctrine`` directory instead:
For example, suppose you decide to store your ``XML`` configuration for
``AppBundle`` entities in the ``@AppBundle/SomeResources/config/doctrine``
directory instead:

.. configuration-block::

.. code-block:: yaml

doctrine:
# ...
orm:
Expand All @@ -552,22 +555,22 @@ in the ``@AppBundle/SomeResources/config/doctrine`` directory instead:
AppBundle:
type: xml
dir: SomeResources/config/doctrine

.. code-block:: xml

<?xml version="1.0" charset="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:doctrine="http://symfony.com/schema/dic/doctrine">

<doctrine:config>
<doctrine:orm auto-mapping="true">
<mapping name="AppBundle" dir="SomeResources/config/doctrine" type="xml" />
</doctrine:orm>
</doctrine:config>
</container>

.. code-block:: php

$container->loadFromExtension('doctrine', array(
'orm' => array(
'auto_mapping' => true,
Expand All @@ -582,13 +585,14 @@ Mapping Entities Outside of a Bundle

You can also create new mappings, for example outside of the Symfony folder.

For example, the following looks for entity classes in the ``App\Entity`` namespace in the
``src/Entity`` directory and gives them an ``App`` alias (so you can say things like ``App:Post``):
For example, the following looks for entity classes in the ``App\Entity``
namespace in the ``src/Entity`` directory and gives them an ``App`` alias
(so you can say things like ``App:Post``):

.. configuration-block::

.. code-block:: yaml

doctrine:
# ...
orm:
Expand All @@ -601,16 +605,16 @@ For example, the following looks for entity classes in the ``App\Entity`` namesp
is_bundle: false
prefix: App\Entity
alias: App

.. code-block:: xml

6D47 <?xml version="1.0" charset="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:doctrine="http://symfony.com/schema/dic/doctrine">

<doctrine:config>
<doctrine:orm>
<mapping name="SomeEntityNamespace"
<mapping name="SomeEntityNamespace"
type="annotation"
dir="%kernel.root_dir%/../src/Entity"
is-bundle="false"
Expand All @@ -620,9 +624,9 @@ For example, the following looks for entity classes in the ``App\Entity`` namesp
</doctrine:orm>
</doctrine:config>
</container>

.. code-block:: php

$container->loadFromExtension('doctrine', array(
'orm' => array(
'auto_mapping' => true,
Expand All @@ -641,31 +645,33 @@ For example, the following looks for entity classes in the ``App\Entity`` namesp
Detecting a Mapping Configuration Format
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the ``type`` on the bundle configuration isn't set,
the DoctrineBundle will try to detect the correct mapping configuration format for
the bundle.
If the ``type`` on the bundle configuration isn't set, the DoctrineBundle
will try to detect the correct mapping configuration format for the bundle.

DoctrineBundle will look for files matching ``*.orm.[FORMAT]`` (e.g. ``Post.orm.yml``)
in the configured ``dir`` of your mapping (if you're mapping a bundle, then ``dir`` is
relative to the bundle's directory).
DoctrineBundle will look for files matching ``*.orm.[FORMAT]`` (e.g.
``Post.orm.yml``) in the configured ``dir`` of your mapping (if you're mapping
a bundle, then ``dir`` is relative to the bundle's directory).

The bundle looks for (in this order) XML, YAML and PHP files.
Using the ``auto_mapping`` feature, every bundle can have only one configuration format.
The bundle will stop as soon as it locates one.
Using the ``auto_mapping`` feature, every bundle can have only one
configuration format. The bundle will stop as soon as it locates one.

If it wasn't possible to determine a configuration format for a bundle,
the DoctrineBundle will check if there is an ``Entity`` folder in the bundle's root directory.
If the folder exist, Doctrine will fall back to using an annotation driver.
the DoctrineBundle will check if there is an ``Entity`` folder in the bundle's
root directory. If the folder exist, Doctrine will fall back to using an
annotation driver.

Default Value of dir
Default Value of Dir
~~~~~~~~~~~~~~~~~~~~

If ``dir`` is not specified, then its default value depends on which configuration driver is being used.
For drivers that rely on the PHP files (annotation, staticphp) it will
be ``[Bundle]/Entity``. For drivers that are using configuration
files (XML, YAML, ...) it will be ``[Bundle]/Resources/config/doctrine``.
If ``dir`` is not specified, then its default value depends on which configuration
driver is being used. For drivers that rely on the PHP files (annotation,
staticphp) it will be ``[Bundle]/Entity``. For drivers that are using
configuration files (XML, YAML, ...) it will be
``[Bundle]/Resources/config/doctrine``.

If the ``dir`` configuration is set and the ``is_bundle`` configuration is ``true``,
the DoctrineBundle will prefix the ``dir`` configuration with the path of the bundle.
If the ``dir`` configuration is set and the ``is_bundle`` configuration
is ``true``, the DoctrineBundle will prefix the ``dir`` configuration with
the path of the bundle.

.. _`DQL User Defined Functions`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/cookbook/dql-user-defined-functions.html
22 changes: 12 additions & 10 deletions reference/configuration/security.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@
SecurityBundle Configuration ("security")
=========================================

The security system is one of the most powerful parts of Symfony, and can
The security system is one of the most powerful parts of Symfony and can
largely be controlled via its configuration.

Full default Configuration
Full Default Configuration
--------------------------

The following is the full default configuration for the security system.
Expand Down Expand Up @@ -306,8 +306,8 @@ post_only
**type**: ``boolean`` **default**: ``true``

By default, you must submit your login form to the ``check_path`` URL as
a POST request. By setting this option to ``false``, you can send a GET request
to the ``check_path`` URL.
a POST request. By setting this option to ``false``, you can send a GET
request to the ``check_path`` URL.

Redirecting after Login
~~~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -328,7 +328,8 @@ Using the PBKDF2 Encoder: Security and Speed
The `PBKDF2`_ encoder provides a high level of Cryptographic security, as
recommended by the National Institute of Standards and Technology (NIST).

You can see an example of the ``pbkdf2`` encoder in the YAML block on this page.
You can see an example of the ``pbkdf2`` encoder in the YAML block on this
page.

But using PBKDF2 also warrants a warning: using it (with a high number
of iterations) slows down the process. Thus, PBKDF2 should be used with
Expand Down Expand Up @@ -389,10 +390,11 @@ Using the BCrypt Password Encoder
));

The ``cost`` can be in the range of ``4-31`` and determines how long a password
will be encoded. Each increment of ``cost`` *doubles* the time it takes to
encode a password.
will be encoded. Each increment of ``cost`` *doubles* the time it takes
to encode a password.

If you don't provide the ``cost`` option, the default cost of ``13`` is used.
If you don't provide the ``cost`` option, the default cost of ``13`` is
used.

.. note::

Expand All @@ -418,8 +420,8 @@ Firewall Context
Most applications will only need one :ref:`firewall <book-security-firewalls>`.
But if your application *does* use multiple firewalls, you'll notice that
if you're authenticated in one firewall, you're not automatically authenticated
in another. In other words, the systems don't share a common "context": each
firewall acts like a separate security system.
in another. In other words, the systems don't share a common "context":
each firewall acts like a separate security system.

However, each firewall has an optional ``context`` key (which defaults to
the name of the firewall), which is used when storing and retrieving security
Expand Down
36 changes: 19 additions & 17 deletions reference/configuration/swiftmailer.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,9 @@ options, see `Full Default Configuration`_
The ``swiftmailer`` key configures Symfony's integration with Swift Mailer,
which is responsible for creating and delivering email messages.

The following section lists all options that are available to configure a
mailer. It is also possible to configure several mailers (see `Using Multiple Mailers`_).
The following section lists all options that are available to configure
a mailer. It is also possible to configure several mailers (see
`Using Multiple Mailers`_).

Configuration
-------------
Expand Down Expand Up @@ -121,9 +122,9 @@ sender_address

**type**: ``string``

If set, all messages will be delivered with this address as the "return path"
address, which is where bounced messages should go. This is handled internally
by Swift Mailer's ``Swift_Plugins_ImpersonatePlugin`` class.
If set, all messages will be delivered with this address as the "return
path" address, which is where bounced messages should go. This is handled
internally by Swift Mailer's ``Swift_Plugins_ImpersonatePlugin`` class.

antiflood
~~~~~~~~~
Expand All @@ -149,10 +150,10 @@ delivery_address

**type**: ``string``

If set, all email messages will be sent to this address instead of being sent
to their actual recipients. This is often useful when developing. For example,
by setting this in the ``config_dev.yml`` file, you can guarantee that all
emails sent during development go to a single account.
If set, all email messages will be sent to this address instead of being
sent to their actual recipients. This is often useful when developing. For
example, by setting this in the ``config_dev.yml`` file, you can guarantee
that all emails sent during development go to a single account.

This uses ``Swift_Plugins_RedirectingPlugin``. Original recipients are available
on the ``X-Swift-To``, ``X-Swift-Cc`` and ``X-Swift-Bcc`` headers.
Expand All @@ -162,27 +163,28 @@ delivery_whitelist

**type**: ``array``

Used in combination with ``delivery_address``. If set, emails matching any of these
patterns will be delivered like normal, instead of being sent to ``delivery_address``.
For details, see :ref:`the cookbook entry. <sending-to-a-specified-address-but-with-exceptions>`
Used in combination with ``delivery_address``. If set, emails matching any
of these patterns will be delivered like normal, instead of being sent to
``delivery_address``. For details, see
:ref:`the cookbook entry <sending-to-a-specified-address-but-with-exceptions>`.

disable_delivery
~~~~~~~~~~~~~~~~

**type**: ``boolean`` **default**: ``false``

If true, the ``transport`` will automatically be set to ``null``, and no
If true, the ``transport`` will automatically be set to ``null`` and no
emails will actually be delivered.

logging
~~~~~~~

**type**: ``boolean`` **default**: ``%kernel.debug%``

If true, Symfony's data collector will be activated for Swift Mailer and the
information will be available in the profiler.
If true, Symfony's data collector will be activated for Swift Mailer and
the information will be available in the profiler.

Full default Configuration
Full Default Configuration
--------------------------

.. configuration-block::
Expand Down Expand Up @@ -240,7 +242,7 @@ Full default Configuration
</swiftmailer:config>
</container>

Using multiple Mailers
Using Multiple Mailers
----------------------

You can configure multiple mailers by grouping them under the ``mail 4B9A ers``
Expand Down
Loading
0