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

Commit c1cbb9a

Browse files
weaverryanweaverryan
committed
Merge branch '2.8'
* 2.8: Rewrite utf8mb4 cautions, add comment into sample configuration Add backticks for code-styling Indenting caution block to nest it inside the sidebar Revert "Fix example name to avoid breaking collision with standard data-collectors" Revert "Add a cautionary note telling users where the "standard" data-collector names can be found." Add a cautionary note telling users where the "standard" data-collector names can be found. Fix example name to avoid breaking collision with standard data-collectors Change MySQL UTF-8 examples to use utf8mb4, which is closer to the standard most people would expect [Cookbook] Custom compile steps on Heroku Added information about the Symfony Demo application Renamed precision option to scale
2 parents 643f4c4 + 5594531 commit c1cbb9a

File tree

9 files changed

+148
-36
lines changed

9 files changed

+148
-36
lines changed

‎best_practices/introduction.rst‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -69,15 +69,23 @@ what you already know.
6969
The Application
7070
---------------
7171

72-
In addition to this guide, you'll find a sample application developed with
73-
all these best practices in mind. **The application is a simple blog engine**,
74-
because that will allow us to focus on the Symfony concepts and features without
75-
getting buried in difficult details.
72+
In addition to this guide, a sample application has been developed with all these
73+
best practices in mind. This project, called the Symfony Demo application, can
74+
be obtained through the Symfony Installer. First, `download and install`_ the
75+
installer and then execute this command to download the demo application:
7676

77-
Instead of developing the application step by step in this guide, you'll find
78-
selected snippets of code through the chapters. Please refer to the last chapter
79-
of this guide to find more details about this application and the instructions
80-
to install it.
77+
.. code-block:: bash
78+
79+
# Linux and Mac OS X
80+
$ symfony demo
81+
82+
# Windows
83+
c:\> php symfony demo
84+
85+
**The demo application is a simple blog engine**, because that will allow us to
86+
focus on the Symfony concepts and features without getting buried in difficult
87+
implementation details. Instead of developing the application step by step in
88+
this guide, you'll find selected snippets of code through the chapters.
8189

8290
Don't Update Your Existing Applications
8391
---------------------------------------
@@ -95,3 +103,4 @@ practices**. The reasons for not doing it are various:
95103
your tests or adding features that provide real value to the end users.
96104

97105
.. _`Fabien Potencier`: https://connect.sensiolabs.com/profile/fabpot
106+
.. _`download and install`: http://symfony.com/download

‎book/doctrine.rst‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -141,8 +141,13 @@ for you:
141141
.. code-block:: ini
142142
143143
[mysqld]
144-
collation-server = utf8_general_ci
145-
character-set-server = utf8
144+
# Version 5.5.3 introduced "utf8mb4", which is recommended
145+
collation-server = utf8mb4_general_ci # Replaces utf8_general_ci
146+
character-set-server = utf8mb4 # Replaces utf8
147+
148+
We recommend against MySQL's ``utf8`` character set, since it does not
149+
support 4-byte unicode characters, and strings containing them will be
150+
truncated. This is fixed by the `newer utf8mb4 character set`_.
146151

147152
.. note::
148153

@@ -1422,3 +1427,4 @@ For more information about Doctrine, see the *Doctrine* section of the
14221427
.. _`migrations`: http://symfony.com/doc/current/bundles/DoctrineMigrationsBundle/index.html
14231428
.. _`DoctrineFixturesBundle`: http://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html
14241429
.. _`FrameworkExtraBundle documentation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
1430+
.. _`newer utf8mb4 character set`: https://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html

‎cookbook/deployment/heroku.rst‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -235,6 +235,85 @@ You should be seeing your Symfony application in your browser.
235235
AcmeDemoBundle is only loaded in the dev environment (check out your
236236
``AppKernel`` class). Try opening ``/app/example`` from the AppBundle.
237237

238+
Custom Compile Steps
239+
~~~~~~~~~~~~~~~~~~~~
240+
241+
If you wish to execute additional custom commands during a build, you can leverage
242+
Heroku's `custom compile steps`_. Imagine you want to remove the ``dev`` front controller
243+
from your production environment on Heroku in order to avoid a potential vulnerability.
244+
Adding a command to remove ``web/app_dev.php`` to Composer's `post-install-commands`_ would
245+
work, but it also removes the controller in your local development environment on each
246+
``composer install`` or ``composer update`` respectively. Instead, you can add a
247+
`custom Composer command`_ named ``compile`` (this key name is a Heroku convention) to the
248+
``scripts`` section of your ``composer.json``. The listed commands hook into Heroku's deploy
249+
process:
250+
251+
.. code-block:: json
252+
253+
{
254+
"scripts": {
255+
"compile": [
256+
"rm web/app_dev.php"
257+
]
258+
}
259+
}
260+
261+
This is also very useful to build assets on the production system, e.g. with Assetic:
262+
263+
.. code-block:: json
264+
265+
{
266+
"scripts": {
267+
"compile": [
268+
"app/console assetic:dump"
269+
]
270+
}
271+
}
272+
273+
.. sidebar:: Node.js Dependencies
274+
275+
Building assets may depend on node packages, e.g. ``uglifyjs`` or ``uglifycss``
276+
for asset minification. Installing node packages during the deploy requires a node
277+
installation. But currently, Heroku compiles your app using the PHP buildpack, which
278+
is auto-detected by the presence of a ``composer.json`` file, and does not include a
279+
node installation. Because the Node.js buildpack has a higher precedence than the PHP
280+
buildpack (see `Heroku buildpacks`_), adding a ``package.json`` listing your node
281+
dependencies makes Heroku opt for the Node.js buildpack instead:
282+
283+
.. code-block:: json
284+
285+
{
286+
"name": "myApp",
287+
"engines": {
288+
"node": "0.12.x"
289+
},
290+
"dependencies": {
291+
"uglifycss": "*",
292+
"uglify-js": "*"
293+
}
294+
}
295+
296+
With the next deploy, Heroku compiles your app using the Node.js buildpack and
297+
your npm packages become installed. On the other hand, your ``composer.json`` is
298+
now ignored. To compile your app with both buildpacks, Node.js *and* PHP, you can
299+
use a special `multiple buildpack`_. To override buildpack auto-detection, you
300+
need to explicitly set the buildpack URL:
301+
302+
.. code-block:: bash
303+
304+
$ heroku buildpack:set https://github.com/ddollar/heroku-buildpack-multi.git
305+
306+
Next, add a ``.buildpacks`` file to your project, listing the buildpacks you need:
307+
308+
.. code-block:: text
309+
310+
https://github.com/heroku/heroku-buildpack-nodejs.git
311+
https://github.com/heroku/heroku-buildpack-php.git
312+
313+
With the next deploy, you can benefit from both buildpacks. This setup also enables
314+
your Heroku environment to make use of node based automatic build tools like
315+
`Grunt`_ or `gulp`_.
316+
238317
.. _`the original article`: https://devcenter.heroku.com/articles/getting-started-with-symfony2
239318
.. _`signup with Heroku`: https://signup.heroku.com/signup/dc
240319
.. _`Heroku Toolbelt`: https://devcenter.heroku.com/articles/getting-started-with-php#local-workstation-setup
@@ -244,3 +323,9 @@ You should be seeing your Symfony application in your browser.
244323
.. _`verified that the RSA key fingerprint is correct`: https://devcenter.heroku.com/articles/git-repository-ssh-fingerprints
245324
.. _`post-install-commands`: https://getcomposer.org/doc/articles/scripts.md
246325
.. _`config vars`: https://devcenter.heroku.com/articles/config-vars
326+
.. _`custom compile steps`: https://devcenter.heroku.com/articles/php-support#custom-compile-step
327+
.. _`custom Composer command`: https://getcomposer.org/doc/articles/scripts.md#writing-custom-commands
328+
.. _`Heroku buildpacks`: https://devcenter.heroku.com/articles/buildpacks
329+
.. _`multiple buildpack`: https://github.com/ddollar/heroku-buildpack-multi.git
330+
.. _`Grunt`: http://gruntjs.com
331+
.. _`gulp`: http://gulpjs.com

‎reference/forms/types/integer.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ integers. By default, all non-integer values (e.g. 6.78) will round down (e.g. 6
1616
| Rendered as | ``input`` ``number`` field |
1717
+-------------+-----------------------------------------------------------------------+
1818
| Options | - `grouping`_ |
19-
| | - `precision`_ |
19+
| | - `scale`_ |
2020
| | - `rounding_mode`_ |
2121
+-------------+-----------------------------------------------------------------------+
2222
| Inherited | - `data`_ |
@@ -42,7 +42,7 @@ Field Options
4242

4343
.. include:: /reference/forms/types/options/grouping.rst.inc
4444

45-
.. include:: /reference/forms/types/options/precision.rst.inc
45+
.. include:: /reference/forms/types/options/scale.rst.inc
4646

4747
rounding_mode
4848
~~~~~~~~~~~~~

‎reference/forms/types/money.rst‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ how the input and output of the data is handled.
1717
| Options | - `currency`_ |
1818
| | - `divisor`_ |
1919
| | - `grouping`_ |
20-
| | - `precision`_ |
20+
| | - `scale`_ |
2121
+-------------+---------------------------------------------------------------------+
2222
| Inherited | - `data`_ |
2323
| options | - `disabled`_ |
@@ -73,14 +73,18 @@ be set back on your object.
7373

7474
.. include:: /reference/forms/types/options/grouping.rst.inc
7575

76-
precision
77-
~~~~~~~~~
76+
scale
77+
~~~~~
78+
79+
.. versionadded:: 358A 2.7
80+
The ``scale`` option was introduced in Symfony 2.7. Prior to Symfony 2.7,
81+
it was known as ``precision``.
7882

7983
**type**: ``integer`` **default**: ``2``
8084

81-
For some reason, if you need some precision other than 2 decimal places,
85+
For some reason, if you need some scale other than 2 decimal places,
8286
you can modify this value. You probably won't need to do this unless,
83-
for example, you want to round to the nearest dollar (set the precision
87+
for example, you want to round to the nearest dollar (set the scale
8488
to ``0``).
8589

8690
Inherited Options

‎reference/forms/types/number.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@ number Field Type
55
=================
66

77
Renders an input text field and specializes in handling number input. This
8-
type offers different options for the precision, rounding, and grouping that
9-
you want to use for your number.
8+
type offers different options for the scale, rounding and grouping that you
9+
want to use for your number.
1010

1111
+-------------+----------------------------------------------------------------------+
1212
| Rendered as | ``input`` ``text`` field |
1313
+-------------+----------------------------------------------------------------------+
1414
| Options | - `grouping`_ |
15-
| | - `precision`_ |
15+
| | - `scale`_ |
1616
| | - `rounding_mode`_ |
1717
+-------------+----------------------------------------------------------------------+
1818
| Inherited | - `data`_ |
@@ -38,14 +38,14 @@ Field Options
3838

3939
.. include:: /reference/forms/types/options/grouping.rst.inc
4040

41-
.. include:: /reference/forms/types/options/precision.rst.inc
41+
.. include:: /reference/forms/types/options/scale.rst.inc
4242

4343
rounding_mode
4444
~~~~~~~~~~~~~
4545

4646
**type**: ``integer`` **default**: ``NumberToLocalizedStringTransformer::ROUND_HALFUP``
4747

48-
If a submitted number needs to be rounded (based on the ``precision``
48+
If a submitted number needs to be rounded (based on the `scale`_
4949
option), you have several configurable options for that rounding. Each
5050
option is a constant on the :class:`Symfony\\Component\\Form\\Extension\\Core\\DataTransformer\\NumberToLocalizedStringTransformer`:
5151

‎reference/forms/types/options/precision.rst.inc‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎reference/forms/types/options/scale.rst.inc‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
scale
2+
~~~~~
3+
4+
.. versionadded:: 2.7
5+
The ``scale`` option was introduced in Symfony 2.7. Prior to Symfony 2.7,
6+
it was known as ``precision``.
7+
8+
**type**: ``integer`` **default**: Locale-specific (usually around ``3``)
9+
10+
This specifies how many decimals will be allowed until the field rounds
11+
the submitted value (via ``rounding_mode``). For example, if ``scale`` is set
12+
to ``2``, a submitted value of ``20.123`` will be rounded to, for example,
13+
``20.12`` (depending on your `rounding_mode`_).

‎reference/forms/types/percent.rst‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ This field adds a percentage sign "``%``" after the input box.
1515
+-------------+-----------------------------------------------------------------------+
1616
| Rendered as | ``input`` ``text`` field |
1717
+-------------+-----------------------------------------------------------------------+
18-
| Options | - `precision`_ |
18+
| Options | - `scale`_ |
1919
| | - `type`_ |
2020
+-------------+-----------------------------------------------------------------------+
2121
| Inherited | - `data`_ |
@@ -39,13 +39,17 @@ This field adds a percentage sign "``%``" after the input box.
3939
Field Options
4040
-------------
4141

42-
precision
43-
~~~~~~~~~
42+
scale
43+
~~~~~
44+
45+
.. versionadded:: 2.7
46+
The ``scale`` option was introduced in Symfony 2.7. Prior to Symfony 2.7,
47+
it was known as ``precision``.
4448

4549
**type**: ``integer`` **default**: ``0``
4650

47-
By default, the input numbers are rounded. To allow for more decimal
48-
places, use this option.
51+
By default, the input numbers are rounded. To allow for more decimal places,
52+
use this option.
4953

5054
type
5155
~~~~

0 commit comments

Comments
 (0)
0