8000 Merge branch '4.0' into 4.1 · weaverryan/symfony-docs@fcbe118 · GitHub
[go: up one dir, main page]
Skip to content

Commit fcbe118

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '4.0' into 4.1
* 4.0: Improved the front controller of the HttpCache Better docs about overriding third-party translations event constant mistake Updated the default values of some Cache config options add legacy labels Update Best Practices about service config format Update simple-example.rst to use const for jQuery Update shared-entry.rst to use Bootstrap 4's SCSS Removed an extra blank line Reword and added a note Link to proxy configuration docs from the routing scheme page Fixed typos Fixed security expression testing user Update messenger.rst Fix a configuration block in the Doctrine Associations page Fix numbering Mentioned Debian explicitly
2 parents 7860b54 + 48063ce commit fcbe118

File tree

18 files changed

+109
-38
lines changed

18 files changed

+109
-38
lines changed

‎best_practices/business-logic.rst

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,11 +96,13 @@ all services are private by default.
9696
Service Format: YAML
9797
--------------------
9898

99-
In the previous section, YAML was used to define the service.
99+
If you use the :ref:`default services.yaml configuration <service-container-services-load-example>`,
100+
most services will be configured automatically. However, in some edge cases
101+
you'll need to configure services (or parts of them) manually.
100102

101103
.. best-practice::
102104

103-
Use the YAML format to define your own services.
105+
Use the YAML format to configure your own services.
104106

105107
This is controversial, and in our experience, YAML and XML usage is evenly
106108
distributed among developers, with a slight preference towards YAML.

‎bundles/override.rst

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -149,8 +149,12 @@ instead of the original ones.
149149
Translations
150150
------------
151151

152-
Translations are not related to bundles, but to domains. That means that you
153-
can override the translations from any translation file, as long as it is in
154-
:ref:`the correct domain <using-message-domains>`.
152+
Translations are not related to bundles, but to :ref:`translation domains <using-message-domains>`.
153+
For this reason, you can override any bundle translation file from the main
154+
``translations/`` directory, as long as the new file uses the same domain.
155+
156+
For example, to override the translations defined in the
157+
``Resources/translations/FOSUserBundle.es.yml`` file of the FOSUserBundle,
158+
create a``<your-project>/translations/FOSUserBundle.es.yml`` file.
155159

156160
.. _`the Doctrine documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/inheritance-mapping.html#overrides

‎components/cache/adapters/chain_adapter.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ slowest storage engines, :class:`Symfony\\Component\\Cache\\Adapter\\ApcuAdapter
4646
));
4747

4848
When calling this adapter's :method:`Symfony\\Component\\Cache\\ChainAdapter::prune` method,
49-
the call is deligated to all its compatibe cache adapters. It is safe to mix both adapters
49+
the call is delegated to all its compatible cache adapters. It is safe to mix both adapters
5050
that *do* and do *not* implement :class:`Symfony\\Component\\Cache\\PruneableInterface`, as
5151
incompatible adapters are silently ignored::
5252

‎components/cache/cache_pools.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -160,18 +160,18 @@ Pruning Cache Items
160160
-------------------
161161

162162
Some cache pools do not include an automated mechanism for pruning expired cache items.
163-
For example, the :ref:`FilesystemAdaper <component-cache-filesystem-adapter>` cache
163+
For example, the :ref:`FilesystemAdapter <component-cache-filesystem-adapter>` cache
164164
does not remove expired cache items *until an item is explicitly requested and determined to
165165
be expired*, for example, via a call to ``Psr\\Cache\\CacheItemPoolInterface::getItem``.
166166
Under certain workloads, this can cause stale cache entries to persist well past their
167167
expiration, resulting in a sizable consumption of wasted disk or memory space from excess,
168168
expired cache items.
169169

170-
This shortcomming has been solved through the introduction of
170+
This shortcoming has been solved through the introduction of
171171
:class:`Symfony\\Component\\Cache\\PruneableInterface`, which defines the abstract method
172172
:method:`Symfony\\Component\\Cache\\PruneableInterface::prune`. The
173173
:ref:`ChainAdapter <component-cache-chain-adapter>`,
174-
:ref:`FilesystemAdaper <component-cache-filesystem-adapter>`,
174+
:ref:`FilesystemAdapter <component-cache-filesystem-adapter>`,
175175
:ref:`PdoAdapter <pdo-doctrine-adapter>`, and
176176
:ref:`PhpFilesAdapter <component-cache-files-adapter>` all implement this new interface,
177177
allowing manual removal of stale cache items::
@@ -185,7 +185,7 @@ allowing manual removal of stale cache items::
185185
The :ref:`ChainAdapter <component-cache-chain-adapter>` implementation does not directly
186186
contain any pruning logic itself. Instead, when calling the chain adapter's
187187
:method:`Symfony\\Component\\Cache\\ChainAdapter::prune` method, the call is delegated to all
188-
its compatibe cache adapters (and those that do not implement ``PruneableInterface`` are
188+
its compatible cache adapters (and those that do not implement ``PruneableInterface`` are
189189
silently ignored)::
190190

191191
use Symfony\Component\Cache\Adapter\ApcuAdapter;

‎components/console/events.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,7 +149,7 @@ Listeners receive a
149149
.. tip::
150150

151151
This event is also dispatched when an exception is thrown by the command.
152-
It is then dispatched just after the ``ConsoleEvents::EXCEPTION`` event.
152+
It is then dispatched just after the ``ConsoleEvents::ERROR`` event.
153153
The exit code received in this case is the exception code.
154154

155155
.. _`reserved exit codes`: http://www.tldp.org/LDP/abs/html/exitcodes.html

‎components/http_foundation/session_configuration.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -166,8 +166,8 @@ the ``php.ini`` directive ``session.gc_maxlifetime``. The meaning in this contex
166166
that any stored session that was saved more than ``gc_maxlifetime`` ago should be
167167
deleted. This allows one to expire records based on idle time.
168168

169-
However, some operating systems do their own session handling and set the
170-
``session.gc_probability`` variable to ``0`` to stop PHP doing garbage
169+
However, some operating systems (e.g. Debian) do their own session handling and set
170+
the ``session.gc_probability`` variable to ``0`` to stop PHP doing garbage
171171
collection. That's why Symfony now overwrites this value to ``1``.
172172

173173
If you wish to use the original value set in your ``php.ini``, add the following

‎components/messenger.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,7 @@ First, create your receiver::
165165
private $serializer;
166166
private $filePath;
167167

168-
public function __construct(SerializerInteface $serializer, string $filePath)
168+
public function __construct(SerializerInterface $serializer, string $filePath)
169169
{
170170
$this->serializer = $serializer;
171171
$this->filePath = $filePath;

‎configuration/override_dir_structure.rst

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,54 @@ own templates directory (or directories):
129129
),
130130
));
131131
132+
Override the Translations Directory
133+
-----------------------------------
134+
135+
If your translation files are not stored in the default ``translations/``
136+
directory, use the :ref:`framework.translator.paths <reference-translator-paths>`
137+
configuration option to define your own translations directory (or directories):
138+
139+
.. configuration-block::
140+
141+
.. code-block:: yaml
142+
143+
# config/packages/translation.yaml
144+
framework:
145+
translator:
146+
# ...
147+
paths: ["%kernel.project_dir%/i18n"]
148+
149+
.. code-block:: xml
150+
151+
<!-- config/packages/translation.xml -->
152+
<?xml version="1.0" ?>
153+
<container xmlns="http://symfony.com/schema/dic/services"
154+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
155+
xmlns:twig="http://symfony.com/schema/dic/twig"
156+
xsi:schemaLocation="http://symfony.com/schema/dic/services
157+
http://symfony.com/schema/dic/services/services-1.0.xsd
158+
http://symfony.com/schema/dic/twig
159+
http://symfony.com/schema/dic/twig/twig-1.0.xsd">
160+
161+
<framework:config>
162+
<framework:translator>
163+
<framework:path>%kernel.project_dir%/i18n</framework:path>
164+
</framework:translator>
165+
</framework:config>
166+
167+
</container>
168+
169+
.. code-block:: php
170+
171+
// config/packages/translation.php
172+
$container->loadFromExtension('framework', array(
173+
'translator' => array(
174+
'paths' => array(
175+
'%kernel.project_dir%/i18n',
176+
),
177+
),
178+
));
179+
132180
.. _override-web-dir:
133181
.. _override-the-web-directory:
134182

‎doctrine/associations.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -200,9 +200,9 @@ This ``ManyToOne`` mapping is required. It tells Doctrine to use the ``category_
200200
column on the ``product`` table to relate each record in that table with
201201
a record in the ``category`` table.
202202

203-
Next, since a *one* ``Category`` object will relate to *many* ``Product`` objects,
203+
Next, since *one* ``Category`` object will relate to *many* ``Product`` objects,
204204
the ``make:entity`` command *also* added a ``products`` property to the ``Category``
205-
class that will hold these objects::
205+
class that will hold these objects:
206206

207207
.. configuration-block::
208208

‎frontend/encore/legacy-apps.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Using Libraries that Expect jQuery to be Global
1919
Some legacy JavaScript applications use programming practices that don't play
2020
well with the new practices promoted by Webpack. The most common of these
2121
problems is using code (e.g. jQuery plugins) that assume that jQuery is already
22-
available via the the ``$`` or ``jQuery`` global variables. If those variables
22+
available via the ``$`` or ``jQuery`` global variables. If those variables
2323
are not defined, you'll get these errors:
2424

2525
.. code-block:: text

‎frontend/encore/shared-entry.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ that's included on every page:
2121
2222
// you can also extract CSS - this will create a 'vendor.css' file
2323
// this CSS will *not* be included in page1.css or page2.css anymore
24-
'bootstrap-sass/assets/stylesheets/_bootstrap.scss'
24+
'bootstrap/scss/bootstrap.scss'
2525
])
2626
2727
As soon as you make this change, you need to include two extra JavaScript files

‎frontend/encore/simple-example.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,7 +163,7 @@ Great! Use ``require()`` to import ``jquery`` and ``greet.js``:
163163
// assets/js/app.js
164164
165165
// loads the jquery package from node_modules
166-
var $ = require('jquery');
166+
const $ = require('jquery');
167167
168168
// import the function from greet.js (the .js extension is optional)
169169
// ./ (or ../) means to look for a local file

‎http_cache.rst

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -95,14 +95,19 @@ caching kernel:
9595
9696
// public/index.php
9797
98-
use App\Kernel;
9998
+ use App\CacheKernel;
99+
use App\Kernel;
100100
101101
// ...
102-
$kernel = new Kernel($_SERVER['APP_ENV'] ?? 'dev', $_SERVER['APP_DEBUG'] ?? ('prod' !== ($_SERVER['APP_ENV'] ?? 'dev')));
102+
$env = $_SERVER['APP_ENV'] ?? 'dev';
103+
$debug = (bool) ($_SERVER['APP_DEBUG'] ?? ('prod' !== $env));
104+
// ...
105+
$kernel = new Kernel($env, $debug);
103106
104-
+ // Wrap the default Kernel with the CacheKernel one
105-
+ $kernel = new CacheKernel($kernel);
107+
+ // Wrap the default Kernel with the CacheKernel one in 'prod' environment
108+
+ if ('prod' === $env) {
109+
+ $kernel = new CacheKernel($kernel);
110+
+ }
106111
107112
$request = Request::createFromGlobals();
108113
// ...

‎reference/configuration/framework.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2080,8 +2080,8 @@ Full Default Configuration
20802080
20812081
# cache configuration
20822082
cache:
2083-
app: cache.app
2084-
system: cache.system
2083+
app: cache.adapter.filesystem
2084+
system: cache.adapter.system
20852085
directory: '%kernel.cache_dir%/pools'
20862086
default_doctrine_provider: ~
20872087
default_psr6_provider: ~

‎security.rst

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,10 @@ These are followed by a number of small (but still captivating) sections,
2626
like :ref:`logging out <security-logging-out>` and
2727
:doc:`encoding user passwords </security/password_encoding>`.
2828

29-
Installation
30-
------------
29+
.. _installation:
30+
31+
1) Installation
32+
---------------
3133

3234
In applications using :doc:`Symfony Flex </setup/flex>`, run this command to
3335
install the security feature before using it:
@@ -39,8 +41,9 @@ install the security feature before using it:
3941
.. _security-firewalls:
4042
.. _firewalls-authentication:
4143
.. _initial-security-yml-setup-authentication:
44+
.. _initial-security-yaml-setup-authentication:
4245

43-
1) Initial security.yaml Setup (Authentication)
46+
2) Initial security.yaml Setup (Authentication)
4447
-----------------------------------------------
4548

4649
The security system is configured in ``config/packages/security.yaml``. The
@@ -637,8 +640,9 @@ Your next steps depend on your setup:
637640
:ref:`Authorization <security-authorization>` section.
638641

639642
.. _`security-authorization`:
643+
.. _denying-access-roles-and-other-authorization:
640644

641-
2) Denying Access, Roles and other Authorization
645+
3) Denying Access, Roles and other Authorization
642646
------------------------------------------------
643647

644648
Users can now login to your app using ``http_basic`` or some other method.
@@ -980,15 +984,15 @@ You can also use expressions inside your templates:
980984
.. code-block:: html+jinja
981985

982986
{% if is_granted(expression(
983-
'"ROLE_ADMIN" in roles or (user and user.isSuperAdmin())'
987+
'"ROLE_ADMIN" in roles or (not is_anonymous() and user.isSuperAdmin())'
984988
)) %}
985989
<a href="...">Delete</a>
986990
{% endif %}
987991

988992
.. code-block:: html+php
989993

990994
<?php if ($view['security']->isGranted(new Expression(
991-
'"ROLE_ADMIN" in roles or (user and user.isSuperAdmin())'
995+
'"ROLE_ADMIN" in roles or (not is_anonymous() and user.isSuperAdmin())'
992996
))): ?>
993997
<a href="...">Delete</a>
994998
<?php endif; ?>
@@ -1012,7 +1016,9 @@ security systems.
10121016

10131017
If you still prefer to use traditional ACLs, refer to the `Symfony ACL bundle`_.
10141018

1015-
3) Retrieving the User Object
1019+
.. _retrieving-the-user-object:
1020+
1021+
4) Retrieving the User Object
10161022
-----------------------------
10171023

10181024
After authentication, the ``User`` object of the current user can be accessed

‎security/expressions.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ accepts an :class:`Symfony\\Component\\ExpressionLanguage\\Expression` object::
1818
public function index()
1919
{
2020
$this->denyAccessUnlessGranted(new Expression(
21-
'"ROLE_ADMIN" in roles or (user and user.isSuperAdmin())'
21+
'"ROLE_ADMIN" in roles or (not is_anonymous() and user.isSuperAdmin())'
2222
));
2323

2424
// ...

‎security/force_https.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,3 +105,9 @@ role:
105105
106106
It is also possible to specify using HTTPS in the routing configuration,
107107
see :doc:`/routing/scheme` for more details.
108+
109+
.. note::
110+
111+
Forcing HTTPS while using a reverse proxy or load balancer requires a proper
112+
configuration to avoid infinite redirect loops; see :doc:`/deployment/proxies`
113+
for more details.

‎security/ldap.rst

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -201,13 +201,13 @@ use the ``ldap`` user provider.
201201
provider is used. However, the LDAP component itself does not provide
202202
any escaping yet. Thus, it's your responsibility to prevent LDAP injection
203203
attacks when using the component directly.
204-
204+
205205
.. caution::
206206

207-
The user configured above in the the user provider is only used to retrieve
207+
The user configured above in the user provider is only used to retrieve
208208
data. It's a static user defined by its username and password (for improved
209209
security, define the password as an environment variable).
210-
210+
211211
If your LDAP server allows to retrieve information anonymously, you can
212212
set the ``search_dn`` and ``search_password`` options to ``null``.
213213

@@ -218,7 +218,7 @@ service
218218

219219
**type**: ``string`` **default**: ``ldap``
220220

221-
This is the name of your configured LDAP client. You can freely chose the
221+
This is the name of your configured LDAP client. You can freely choose the
222222
name, but it must be unique in your application and it cannot start with a
223223
number or contain white spaces.
224224

@@ -297,7 +297,7 @@ service
297297

298298
**type**: ``string`` **default**: ``ldap``
299299

300-
This is the name of your configured LDAP client. You can freely chose the
300+
This is the name of your configured LDAP client. You can freely choose the
301301
name, but it must be unique in your application and it cannot start with a
302302
number or contain white spaces.
303303

0 commit comments

Comments
 (0)
0