8000 Merge branch '3.4' · symfony/symfony-docs@5710d64 · GitHub
[go: up one dir, main page]
Skip to content

Commit 5710d64

Browse files
xabbuhxabbuh
committed
Merge branch '3.4'
* 3.4: (46 commits) Minor reword Update deployment.rst Update best_practices.rst Better explain 10000 the purpose of the "license" Composer metadata Reverted the changes about bundle namespaces Removed backticks from bundle names add mention of symfony.com re folder structure reword the documentation section re Resources/doc Reverting previous grammar change Removing trailing space Minor changes throughout BP for Reusable Bundles Mention the YAML features not supported by the Yaml component Update storage.rst Moved the commas in the opening paragraph. Adjust .platform.app.yaml from 'symfony' to 'composer' Don't pass .ico through app.php Update shared.rst Update business-logic.rst Update autoload file added a note about bundle inheritance deprecation ...
2 parents f654343 + 154d8e9 commit 5710d64

27 files changed

+191
-66
lines changed

‎best_practices/business-logic.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ Now you can use the custom slugger in any controller class, such as the
121121
// $slugger = $this->get('app.slugger');
122122
123123
if ($form->isSubmitted() && $form->isValid()) {
124-
$slug = $this->get('app.slugger')->slugify($post->getTitle());
124+
$slug = $slugger->slugify($post->getTitle());
125125
$post->setSlug($slug);
126126
127127
// ...

‎bundles/best_practices.rst

Lines changed: 24 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Bundle Name
3131
A bundle is also a PHP namespace. The namespace must follow the `PSR-0`_ or
3232
`PSR-4`_ interoperability standards for PHP namespaces and class names: it starts
3333
with a vendor segment, followed by zero or more category segments, and it ends
34-
with the namespace short name, which must end with a ``Bundle`` suffix.
34+
with the namespace short name, which must end with ``Bundle``.
3535

3636
A namespace becomes a bundle as soon as you add a bundle class to it. The
3737
bundle class name must follow these simple rules:
@@ -48,8 +48,8 @@ Here are some valid bundle namespaces and class names:
4848
========================== ==================
4949
Namespace Bundle Class Name
5050
========================== ==================
51-
``Acme\Bundle\BlogBundle`` ``AcmeBlogBundle``
52-
``Acme\BlogBundle`` ``AcmeBlogBundle``
51+
``Acme\Bundle\BlogBundle`` AcmeBlogBundle
52+
``Acme\BlogBundle`` AcmeBlogBundle
5353
========================== ==================
5454

5555
By convention, the ``getName()`` method of the bundle class should return the
@@ -58,8 +58,7 @@ class name.
5858
.. note::
5959

6060
If you share your bundle publicly, you must use the bundle class name as
61-
the name of the repository (``AcmeBlogBundle`` and not ``BlogBundle``
62-
for instance).
61+
the name of the repository (AcmeBlogBundle and not BlogBundle for instance).
6362

6463
.. note::
6564

@@ -68,7 +67,7 @@ class name.
6867
:class:`Symfony\\Bundle\\FrameworkBundle\\FrameworkBundle`.
6968

7069
Each bundle has an alias, which is the lower-cased short version of the bundle
71-
name using underscores (``acme_blog`` for ``AcmeBlogBundle``). This alias
70+
name using underscores (``acme_blog`` for AcmeBlogBundle). This alias
7271
is used to enforce uniqueness within a project and for defining bundle's
7372
configuration options (see below for some usage examples).
7473

@@ -105,8 +104,8 @@ that automated tools can rely on:
105104
bundles are published under the MIT license, but you can `choose any license`_;
106105
* ``Resources/doc/index.rst``: The root file for the Bundle documentation.
107106

108-
The depth of sub-directories should be kept to the minimum for most used
109-
classes and files (two levels maximum).
107+
The depth of subdirectories should be kept to a minimum for the most used
108+
classes and files. Two levels is the maximum.
110109

111110
The bundle directory is read-only. If you need to write temporary files, store
112111
them under the ``cache/`` or ``log/`` directory of the host application. Tools
@@ -138,9 +137,9 @@ Classes
138137
-------
139138

140139
The bundle directory structure is used as the namespace hierarchy. For
141-
instance, a ``ContentController`` controller is stored in
142-
``Acme/BlogBundle/Controller/ContentController.php`` and the fully qualified
143-
class name is ``Acme\BlogBundle\Controller\ContentController``.
140+
instance, a ``ContentController`` controller which is stored in
141+
``Acme/BlogBundle/Controller/ContentController.php`` would have the fully
142+
qualified class name of ``Acme\BlogBundle\Controller\ContentController``.
144143

145144
All classes and files must follow the :doc:`Symfony coding standards </contributing/code/standards>`.
146145

@@ -158,8 +157,8 @@ Vendors
158157
A bundle must not embed third-party PHP libraries. It should rely on the
159158
standard Symfony autoloading instead.
160159

161-
A bundle should not embed third-party libraries written in JavaScript, CSS or
162-
any other language.
160+
A bundle should also not embed third-party libraries written in JavaScript,
161+
CSS or any other language.
163162

164163
Tests
165164
-----
@@ -183,10 +182,13 @@ Documentation
183182

184183
All classes and functions must come with full PHPDoc.
185184

186-
Extensive documentation should also be provided in the
187-
:doc:`reStructuredText </contributing/documentation/format>` format, under
188-
the ``Resources/doc/`` directory; the ``Resources/doc/index.rst`` file is
189-
the only mandatory file and must be the entry point for the documentation.
185+
Extensive documentation should also be provided in the ``Resources/doc/``
186+
directory.
187+
The index file (for example ``Resources/doc/index.rst`` or
188+
``Resources/doc/index.md``) is the only mandatory file and must be the entry
189+
point for the documentation. The
190+
:doc:`reStructuredText (rST) </contributing/documentation/format>` is the format
191+
used to render the documentation on symfony.com.
190192

191193
Installation Instructions
192194
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -232,7 +234,6 @@ following standardized instructions in your ``README.md`` file.
232234
{
233235
$bundles = array(
234236
// ...
235-
236237
new <vendor>\<bundle-name>\<bundle-long-name>(),
237238
);
238239
@@ -406,9 +407,9 @@ The ``composer.json`` file should include at least the following metadata:
406407
``name``
407408
Consists of the vendor and the short bundle name. If you are releasing the
408409
bundle on your own instead of on behalf of a company, use your personal name
409-
(e.g. ``johnsmith/blog-bundle``). The bundle short name excludes the vendor
410-
name and separates each word with an hyphen. For example: ``AcmeBlogBundle``
411-
is transformed into ``blog-bundle`` and ``AcmeSocialConnectBundle`` is
410+
(e.g. ``johnsmith/blog-bundle``). Exclude the vendor name from the bundle
411+
short name and separate each word with an hyphen. For example: AcmeBlogBundle
412+
is transformed into ``blog-bundle`` and AcmeSocialConnectBundle is
412413
transformed into ``social-connect-bundle``.
413414

414415
``description``
@@ -418,8 +419,7 @@ The ``composer.json`` file should include at least the following metadata:
418419
Use the ``symfony-bundle`` value.
419420

420421
``license``
421-
``MIT`` is the preferred license for Symfony bundles, but you can use any
422-
other license.
422+
a string (or array of strings) with a `valid license identifier`_, such as ``MIT``.
423423

424424
``autoload``
425425
This information is used by Symfony to load the classes of the bundle. The
@@ -455,3 +455,4 @@ Learn more
455455
.. _`Semantic Versioning Standard`: http://semver.org/
456456
.. _`Packagist`: https://packagist.org/
457457
.. _`choose any license`: http://choosealicense.com/
458+
.. _`valid license identifier`: https://spdx.org/licenses/

‎bundles/inheritance.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@
44
How to Use Bundle Inheritance to Override Parts of a Bundle
55
===========================================================
66

7+
.. caution::
8+
9+
Bundle inheritance is deprecated since Symfony 3.4 and will be removed in
10+
4.0.
11+
712
When working with third-party bundles, you'll probably come across a situation
813
where you want to override a file in that third-party bundle with a file
914
in one of your own bundles. Symfony gives you a very convenient way to override

‎components/http_foundation.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -349,9 +349,9 @@ UTF-8.
349349
Sending the Response
350350
~~~~~~~~~~~~~~~~~~~~
351351

352-
Before sending the Response, you can ensure that it is compliant with the HTTP
353-
specification by calling the
354-
:method:`Symfony\\Component\\HttpFoundation\\Response::prepare` method::
352+
Before sending the Response, you can optionally call the
353+
:method:`Symfony\\Component\\HttpFoundation\\Response::prepare` method to fix any
354+
incompatibility with the HTTP specification (e.g. a wrong ``Content-Type`` header)::
355355

356356
$response->prepare($request);
357357

‎components/yaml/yaml_format.rst

Lines changed: 25 additions & 12 deletions
10000
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,11 @@
44
The YAML Format
55
===============
66

7-
According to the official `YAML`_ website, YAML is "a human friendly data
8-
serialization standard for all programming languages".
9-
10-
Even if the YAML format can describe complex nested data structure, this
11-
article only describes the minimum set of features needed to use YAML as a
12-
configuration file format.
13-
14-
YAML is a simple language that describes data. As PHP, it has a syntax for
15-
simple types like strings, booleans, floats, or integers. But unlike PHP, it
16-
makes a difference between arrays (sequences) and hashes (mappings).
7+
According to the official `YAML website`_, YAML is "a human friendly data
8+
serialization standard for all programming languages". The Symfony Yaml
9+
component implements a subset of the `YAML specification`_. Specifically, it
10+
implements the minimum set of features needed to use YAML as a configuration
11+
file format.
1712

1813
Scalars
1914
-------
@@ -171,8 +166,8 @@ Collections
171166
-----------
172167

173168
A YAML file is rarely used to describe a simple scalar. Most of the time, it
174-
describes a collection. A collection can be a sequence or a mapping of
175-
elements. Both sequences and mappings are converted to PHP arrays.
169+
describes a collection. YAML collections can be a sequence (indexed arrays in PHP)
170+
or a mapping of elements (associative arrays in PHP).
176171

177172
Sequences use a dash followed by a space:
178173

@@ -325,3 +320,21 @@ The YAML specification defines some tags to set the type of any data explicitly:
325320
Support for the ``!!str`` tag was introduced in Symfony 3.4.
326321

327322
.. _YAML: http://yaml.org/
323+
324+
Unsupported YAML Features
325+
-------------------------
326+
327+
The following YAML features are not supported by the Symfony Yaml component:
328+
329+
* Multi-documents (``---`` and ``...`` markers);
330+
* Complex mapping keys and complex values starting with ``?``;
331+
* Tagged values as keys;
332+
* The following tags and types: `!!set`, `!!omap`, `!!pairs`, `!!set`, `!!seq`,
333+
`!!bool`, `!!int`, `!!merge`, `!!null`, `!!timestamp`, `!!value`, `!!yaml`;
334+
* Tags (``TAG`` directive; example: ``%TAG ! tag:example.com,2000:app/``)
335+
and tag references (example: ``!<tag:example.com,2000:app/foo>``);
336+
* Using sequence-like syntax for mapping elements (example: ``{foo, bar}``; use
337+
``{foo: ~, bar: ~}`` instead).
338+
339+
.. _`YAML website`: http://yaml.org/
340+
.. _`YAML specification`: http://www.yaml.org/spec/1.2/spec.html

‎controller/upload_file.rst

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -400,8 +400,6 @@ Now, register this class as a Doctrine listener:
400400
<!-- ... -->
401401
402402
<service id="AppBundle\EventListener\BrochureUploaderListener">
403-
<argument type="service" id="app.brochure_uploader"/>
404-
405403
<tag name="doctrine.event_listener" event="prePersist"/>
406404
<tag name="doctrine.event_listener" event="preUpdate"/>
407405
</service>

‎deployment.rst

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -52,9 +52,10 @@ Using Source Control
5252
~~~~~~~~~~~~~~~~~~~~
5353

5454
If you're using source control (e.g. Git or SVN), you can simplify by having
55-
your live installation also be a copy of your repository. When you're ready
56-
to upgrade it is as simple as fetching the latest updates from your source
57-
control system.
55+
your live installation also be a copy of your repository. When you're ready to
56+
upgrade it is as simple as fetching the latest updates from your source control
57+
system. When using Git, a common approach is to create a tag for each release
58+
and check out the appropriate tag on deployment (see `Git Tagging`_).
5859

5960
This makes updating your files *easier*, but you still need to worry about
6061
manually taking other steps (see `Common Post-Deployment Tasks`_).
@@ -207,6 +208,7 @@ Don't forget that deploying your application also involves updating any dependen
207208
(typically via Composer), migrating your database, clearing your cache and
208209
other potential things like pushing assets to a CDN (see `Common Post-Deployment Tasks`_).
209210

211+
.. _`Git Tagging`: https://git-scm.com/book/en/v2/Git-Basics-Tagging
210212
.. _`Capifony`: https://github.com/everzet/capifony
211213
.. _`Capistrano`: http://capistranorb.com/
212214
.. _`sf2debpkg`: https://github.com/liip/sf2debpkg

‎deployment/azure-website.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -417,7 +417,7 @@ application, configure it with the following content:
417417
<action type="CustomResponse" statusCode="403" statusReason="Forbidden: Access is denied." statusDescription="You do not have permission to view this directory or page using the credentials that you supplied." />
418418
</rule>
419419
<rule name="RewriteAssetsToPublic" stopProcessing="true">
420-
<match url="^(.*)(\.css|\.js|\.jpg|\.png|\.gif)$" />
420+
<match url="^(.*)(\.css|\.js|\.jpg|\.png|\.gif|\.ico)$" />
421421
<conditions logicalGrouping="MatchAll" trackAllCaptures="false">
422422
</conditions>
423423
<action type="Rewrite" url="web/{R:0}" />

‎deployment/fortrabbit.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@ Make sure this file is imported into the main config file:
151151
<!-- .. -->
152152
<framework:config>
153153
<!-- .. -->
154-
<framework:session save-path="null" />
154+
<framework:session handler-id="null" />
155155
</framework:config>
156156
</container>
157157

‎deployment/platformsh.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ Platform.sh how to deploy your application (read more about
4141
# The type of the application to build.
4242
type: php:5.6
4343
build:
44-
flavor: symfony
44+
flavor: composer
4545
4646
# The relationships of the application with services or other applications.
4747
# The left-hand side is the name of the relationship as it will be exposed

‎email/dev_environment.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ will not be sent when you run tests, but will continue to be sent in the
2828
2929
# app/config/config_test.yml
3030
swiftmailer:
31-
disable_delivery: true
31+
disable_delivery: true
3232
3333
.. code-block:: xml
3434
@@ -48,7 +48,7 @@ will not be sent when you run tests, but will continue to be sent in the
4848
4949
// app/config/config_test.php
5050
$container->loadFromExtension('swiftmailer', array(
51-
'disable_delivery' => "true",
51+
'disable_delivery' => "true",
5252
));
5353
5454
If you'd also like to disable deliver in the ``dev`` environment, simply
@@ -80,7 +80,8 @@ via the ``delivery_addresses`` option:
8080
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
8181
xsi:schemaLocation="http://symfony.com/schema/dic/services
8282
http://symfony.com/schema/dic/services/services-1.0.xsd
83-
http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
83+
http://symfony.com/schema/dic/swiftmailer
84+
http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
8485
8586
<swiftmailer:config>
8687
<swiftmailer:delivery-address>dev@example.com</swiftmailer:delivery-address>
@@ -154,15 +155,14 @@ by adding the ``delivery_whitelist`` option:
154155
.. code-block:: xml
155156
156157
<!-- app/config/config_dev.xml -->
157-
158-
<?xml version="1.0" charset="UTF-8" ?>
159158
<?xml version="1.0" encoding="UTF-8" ?>
160159
<container xmlns="http://symfony.com/schema/dic/services"
161160
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
162161
xmlns:swiftmailer="http://symfony.com/schema/dic/swiftmailer"
163162
xsi:schemaLocation="http://symfony.com/schema/dic/services
164163
http://symfony.com/schema/dic/services/services-1.0.xsd
165-
http://symfony.com/schema/dic/swiftmailer http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
164+
http://symfony.com/schema/dic/swiftmailer
165+
http://symfony.com/schema/dic/swiftmailer/swiftmailer-1.0.xsd">
166166
167167
<swiftmailer:config>
168168
<!-- all email addresses matching these regexes will be delivered
@@ -177,7 +177,7 @@ by adding the ``delivery_whitelist`` option:
177177
178178
// app/config/config_dev.php
179179
$container->loadFromExtension('swiftmailer', array(
180-
'delivery_addresses' => array("dev@example.com"),
180+
'delivery_addresses' => array("dev@example.com"),
181181
'delivery_whitelist' => array(
182182
// all email addresses matching these regexes will be delivered
183183
// like normal, as well as being sent to dev@example.com

‎form/action_method.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ form, you can use ``setAction()`` and ``setMethod()``:
5656
$formFactory = $formFactoryBuilder->getFormFactory();
5757
5858
$form = $formFactory->createBuilder(FormType::class, $task)
59-
->setAction($this->generateUrl('target_route'))
59+
->setAction('...')
6060
->setMethod('GET')
6161
->add('task', TextType::class)
6262
->add('dueDate', DateType::class)
@@ -108,7 +108,7 @@ options:
108108
$formFactory = $formFactoryBuilder->getFormFactory();
109109
110110
$form = $formFactory->create(TaskType::class, $task, array(
111-
'action' => $this->generateUrl('target_route'),
111+
'action' => '...',
112112
'method' => 'GET',
113113
));
114114

‎form/multiple_buttons.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,10 @@ querying if the "Save and add" button was clicked::
2828

2929
return $this->redirectToRoute($nextAction);
3030
}
31+
32+
Or you can get the button's name by using the
33+
:method:`Symfony\\Component\\Form\\Form::getClickedButton` method of the form::
34+
35+
if ($form->getClickedButton() && 'saveAndAdd' === $form->getClickedButton()->getName()) {
36+
// ...
37+
}

‎frontend/encore/installation.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,14 @@ Then, install Encore into your project with Yarn:
1414
If you want to use `npm`_ instead of `yarn`_, replace ``yarn add xxx --dev`` by
1515
``npm install xxx --save-dev``.
1616

17+
.. tip::
18+
19+
If you are using Flex for your project, you can install Encore via:
20+
21+
.. code-block:: terminal
22+
23+
$ composer require encore
24+
1725
This command creates (or modifies) a ``package.json`` file and downloads dependencies
1826
into a ``node_modules/`` directory. When using Yarn, a file called ``yarn.lock``
1927
is also created/updated. When using npm 5, a ``package-lock.json`` file is created/updated.

0 commit comments

Comments
 (0)
0