From 59ac3d507eedbaebbfebde57a1546a2a31e599e7 Mon Sep 17 00:00:00 2001 From: WouterJ Date: Wed, 18 Feb 2015 14:59:26 +0100 Subject: [PATCH 01/11] Renamed precision option to scale --- reference/forms/types/integer.rst | 4 ++-- reference/forms/types/money.rst | 14 +++++++++----- reference/forms/types/number.rst | 10 +++++----- reference/forms/types/options/precision.rst.inc | 9 --------- reference/forms/types/options/scale.rst.inc | 13 +++++++++++++ reference/forms/types/percent.rst | 14 +++++++++----- 6 files changed, 38 insertions(+), 26 deletions(-) delete mode 100644 reference/forms/types/options/precision.rst.inc create mode 100644 reference/forms/types/options/scale.rst.inc diff --git a/reference/forms/types/integer.rst b/reference/forms/types/integer.rst index edf9e9c1b9b..6a2fcdcadbe 100644 --- a/reference/forms/types/integer.rst +++ b/reference/forms/types/integer.rst @@ -16,7 +16,7 @@ integers. By default, all non-integer values (e.g. 6.78) will round down (e.g. 6 | Rendered as | ``input`` ``number`` field | +-------------+-----------------------------------------------------------------------+ | Options | - `grouping`_ | -| | - `precision`_ | +| | - `scale`_ | | | - `rounding_mode`_ | +-------------+-----------------------------------------------------------------------+ | Inherited | - `data`_ | @@ -42,7 +42,7 @@ Field Options .. include:: /reference/forms/types/options/grouping.rst.inc -.. include:: /reference/forms/types/options/precision.rst.inc +.. include:: /reference/forms/types/options/scale.rst.inc rounding_mode ~~~~~~~~~~~~~ diff --git a/reference/forms/types/money.rst b/reference/forms/types/money.rst index 6db6ead9c06..ca89ab16f4a 100644 --- a/reference/forms/types/money.rst +++ b/reference/forms/types/money.rst @@ -17,7 +17,7 @@ how the input and output of the data is handled. | Options | - `currency`_ | | | - `divisor`_ | | | - `grouping`_ | -| | - `precision`_ | +| | - `scale`_ | +-------------+---------------------------------------------------------------------+ | Inherited | - `data`_ | | options | - `disabled`_ | @@ -73,14 +73,18 @@ be set back on your object. .. include:: /reference/forms/types/options/grouping.rst.inc -precision -~~~~~~~~~ +scale +~~~~~ + +.. versionadded:: 2.7 + The ``scale`` option was introduced in Symfony 2.7. Prior to Symfony 2.7, + it was known as ``precision``. **type**: ``integer`` **default**: ``2`` -For some reason, if you need some precision other than 2 decimal places, +For some reason, if you need some scale other than 2 decimal places, you can modify this value. You probably won't need to do this unless, -for example, you want to round to the nearest dollar (set the precision +for example, you want to round to the nearest dollar (set the scale to ``0``). Inherited Options diff --git a/reference/forms/types/number.rst b/reference/forms/types/number.rst index 29f4edfaf2e..3f66fcc5386 100644 --- a/reference/forms/types/number.rst +++ b/reference/forms/types/number.rst @@ -5,14 +5,14 @@ number Field Type ================= Renders an input text field and specializes in handling number input. This -type offers different options for the precision, rounding, and grouping that -you want to use for your number. +type offers different options for the scale, rounding and grouping that you +want to use for your number. +-------------+----------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+----------------------------------------------------------------------+ | Options | - `grouping`_ | -| | - `precision`_ | +| | - `scale`_ | | | - `rounding_mode`_ | +-------------+----------------------------------------------------------------------+ | Inherited | - `data`_ | @@ -38,14 +38,14 @@ Field Options .. include:: /reference/forms/types/options/grouping.rst.inc -.. include:: /reference/forms/types/options/precision.rst.inc +.. include:: /reference/forms/types/options/scale.rst.inc rounding_mode ~~~~~~~~~~~~~ **type**: ``integer`` **default**: ``NumberToLocalizedStringTransformer::ROUND_HALFUP`` -If a submitted number needs to be rounded (based on the ``precision`` +If a submitted number needs to be rounded (based on the `scale`_ option), you have several configurable options for that rounding. Each option is a constant on the :class:`Symfony\\Component\\Form\\Extension\\Core\\DataTransformer\\NumberToLocalizedStringTransformer`: diff --git a/reference/forms/types/options/precision.rst.inc b/reference/forms/types/options/precision.rst.inc deleted file mode 100644 index ac606eb8a5d..00000000000 --- a/reference/forms/types/options/precision.rst.inc +++ /dev/null @@ -1,9 +0,0 @@ -precision -~~~~~~~~~ - -**type**: ``integer`` **default**: Locale-specific (usually around ``3``) - -This specifies how many decimals will be allowed until the field rounds -the submitted value (via ``rounding_mode``). For example, if ``precision`` -is set to ``2``, a submitted value of ``20.123`` will be rounded to, -for example, ``20.12`` (depending on your ``rounding_mode``). diff --git a/reference/forms/types/options/scale.rst.inc b/reference/forms/types/options/scale.rst.inc new file mode 100644 index 00000000000..82df7d60d3c --- /dev/null +++ b/reference/forms/types/options/scale.rst.inc @@ -0,0 +1,13 @@ +scale +~~~~~ + +.. versionadded:: 2.7 + The ``scale`` option was introduced in Symfony 2.7. Prior to Symfony 2.7, + it was known as ``precision``. + +**type**: ``integer`` **default**: Locale-specific (usually around ``3``) + +This specifies how many decimals will be allowed until the field rounds +the submitted value (via ``rounding_mode``). For example, if ``scale`` is set +to ``2``, a submitted value of ``20.123`` will be rounded to, for example, +``20.12`` (depending on your `rounding_mode`_). diff --git a/reference/forms/types/percent.rst b/reference/forms/types/percent.rst index 253a43c69b5..d0331523279 100644 --- a/reference/forms/types/percent.rst +++ b/reference/forms/types/percent.rst @@ -15,7 +15,7 @@ This field adds a percentage sign "``%``" after the input box. +-------------+-----------------------------------------------------------------------+ | Rendered as | ``input`` ``text`` field | +-------------+-----------------------------------------------------------------------+ -| Options | - `precision`_ | +| Options | - `scale`_ | | | - `type`_ | +-------------+-----------------------------------------------------------------------+ | Inherited | - `data`_ | @@ -39,13 +39,17 @@ This field adds a percentage sign "``%``" after the input box. Field Options ------------- -precision -~~~~~~~~~ +scale +~~~~~ + +.. versionadded:: 2.7 + The ``scale`` option was introduced in Symfony 2.7. Prior to Symfony 2.7, + it was known as ``precision``. **type**: ``integer`` **default**: ``0`` -By default, the input numbers are rounded. To allow for more decimal -places, use this option. +By default, the input numbers are rounded. To allow for more decimal places, +use this option. type ~~~~ From 6383a9b4b635879cd3e932092b08be6ef8a64dd8 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 10 Apr 2015 15:50:03 +0200 Subject: [PATCH 02/11] Added information about the Symfony Demo application --- best_practices/introduction.rst | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/best_practices/introduction.rst b/best_practices/introduction.rst index d1d0e760d32..3c4fb03e7e4 100644 --- a/best_practices/introduction.rst +++ b/best_practices/introduction.rst @@ -69,15 +69,23 @@ what you already know. The Application --------------- -In addition to this guide, you'll find a sample application developed with -all these best practices in mind. **The application is a simple blog engine**, -because that will allow us to focus on the Symfony concepts and features without -getting buried in difficult details. +In addition to this guide, a sample application has been developed with all these +best practices in mind. This project, called the Symfony Demo application, can +be obtained through the Symfony Installer. First, `download and install`_ the +installer and then execute this command to download the demo application: -Instead of developing the application step by step in this guide, you'll find -selected snippets of code through the chapters. Please refer to the last chapter -of this guide to find more details about this application and the instructions -to install it. +.. code-block:: bash + + # Linux and Mac OS X + $ symfony demo + + # Windows + c:\> php symfony demo + +**The demo application is a simple blog engine**, because that will allow us to +focus on the Symfony concepts and features without getting buried in difficult +implementation details. Instead of developing the application step by step in +this guide, you'll find selected snippets of code through the chapters. Don't Update Your Existing Applications --------------------------------------- @@ -95,3 +103,4 @@ practices**. The reasons for not doing it are various: your tests or adding features that provide real value to the end users. .. _`Fabien Potencier`: https://connect.sensiolabs.com/profile/fabpot +.. _`download and install`: http://symfony.com/download From cb71ad085c17e687d05808d1d6ef1f7249737c51 Mon Sep 17 00:00:00 2001 From: Philipp Rieber Date: Tue, 17 Mar 2015 12:11:01 +0100 Subject: [PATCH 03/11] [Cookbook] Custom compile steps on Heroku --- cookbook/deployment/heroku.rst | 85 ++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) diff --git a/cookbook/deployment/heroku.rst b/cookbook/deployment/heroku.rst index 1b6ed4a1bac..83f71d8949b 100644 --- a/cookbook/deployment/heroku.rst +++ b/cookbook/deployment/heroku.rst @@ -235,6 +235,85 @@ You should be seeing your Symfony application in your browser. AcmeDemoBundle is only loaded in the dev environment (check out your ``AppKernel`` class). Try opening ``/app/example`` from the AppBundle. +Custom Compile Steps +~~~~~~~~~~~~~~~~~~~~ + +If you wish to execute additional custom commands during a build, you can leverage +Heroku's `custom compile steps`_. Imagine you want to remove the ``dev`` front controller +from your production environment on Heroku in order to avoid a potential vulnerability. +Adding a command to remove ``web/app_dev.php`` to Composer's `post-install-commands`_ would +work, but it also removes the controller in your local development environment on each +``composer install`` or ``composer update`` respectively. Instead, you can add a +`custom Composer command`_ named ``compile`` (this key name is a Heroku convention) to the +``scripts`` section of your ``composer.json``. The listed commands hook into Heroku's deploy +process: + +.. code-block:: json + + { + "scripts": { + "compile": [ + "rm web/app_dev.php" + ] + } + } + +This is also very useful to build assets on the production system, e.g. with Assetic: + +.. code-block:: json + + { + "scripts": { + "compile": [ + "app/console assetic:dump" + ] + } + } + +.. sidebar:: Node.js Dependencies + + Building assets may depend on node packages, e.g. ``uglifyjs`` or ``uglifycss`` + for asset minification. Installing node packages during the deploy requires a node + installation. But currently, Heroku compiles your app using the PHP buildpack, which + is auto-detected by the presence of a ``composer.json`` file, and does not include a + node installation. Because the Node.js buildpack has a higher precedence than the PHP + buildpack (see `Heroku buildpacks`_), adding a ``package.json`` listing your node + dependencies makes Heroku opt for the Node.js buildpack instead: + + .. code-block:: json + + { + "name": "myApp", + "engines": { + "node": "0.12.x" + }, + "dependencies": { + "uglifycss": "*", + "uglify-js": "*" + } + } + + With the next deploy, Heroku compiles your app using the Node.js buildpack and + your npm packages become installed. On the other hand, your ``composer.json`` is + now ignored. To compile your app with both buildpacks, Node.js *and* PHP, you can + use a special `multiple buildpack`_. To override buildpack auto-detection, you + need to explicitly set the buildpack URL: + + .. code-block:: bash + + $ heroku buildpack:set https://github.com/ddollar/heroku-buildpack-multi.git + + Next, add a ``.buildpacks`` file to your project, listing the buildpacks you need: + + .. code-block:: text + + https://github.com/heroku/heroku-buildpack-nodejs.git + https://github.com/heroku/heroku-buildpack-php.git + + With the next deploy, you can benefit from both buildpacks. This setup also enables + your Heroku environment to make use of node based automatic build tools like + `Grunt`_ or `gulp`_. + .. _`the original article`: https://devcenter.heroku.com/articles/getting-started-with-symfony2 .. _`signup with Heroku`: https://signup.heroku.com/signup/dc .. _`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. .. _`verified that the RSA key fingerprint is correct`: https://devcenter.heroku.com/articles/git-repository-ssh-fingerprints .. _`post-install-commands`: https://getcomposer.org/doc/articles/scripts.md .. _`config vars`: https://devcenter.heroku.com/articles/config-vars +.. _`custom compile steps`: https://devcenter.heroku.com/articles/php-support#custom-compile-step +.. _`custom Composer command`: https://getcomposer.org/doc/articles/scripts.md#writing-custom-commands +.. _`Heroku buildpacks`: https://devcenter.heroku.com/articles/buildpacks +.. _`multiple buildpack`: https://github.com/ddollar/heroku-buildpack-multi.git +.. _`Grunt`: http://gruntjs.com +.. _`gulp`: http://gulpjs.com From f9cae6c26713023462434e30101945f1ddffe76f Mon Sep 17 00:00:00 2001 From: Darien Date: Fri, 20 Mar 2015 16:55:14 -0700 Subject: [PATCH 04/11] Change MySQL UTF-8 examples to use utf8mb4, which is closer to the standard most people would expect --- book/doctrine.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index 14a5c63080b..55940c2dcfb 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -134,6 +134,12 @@ for you: There's no way to configure these defaults inside Doctrine, as it tries to be as agnostic as possible in terms of environment configuration. One way to solve this problem is to configure server-level defaults. + +.. caution:: + + If you are using MySQL, its `utf8` character set has some shortcomings + which may cause problems. Prefer the `utf8mb4` character set instead, if + your version supports it. Setting UTF8 defaults for MySQL is as simple as adding a few lines to your configuration file (typically ``my.cnf``): @@ -141,8 +147,8 @@ for you: .. code-block:: ini [mysqld] - collation-server = utf8_general_ci - character-set-server = utf8 + collation-server = utf8mb4_general_ci + character-set-server = utf8mb4 .. note:: From f0ced918c26c1c41fee3e8f3b2dcb3c351768f00 Mon Sep 17 00:00:00 2001 From: Darien Hager Date: Mon, 23 Mar 2015 19:55:34 -0700 Subject: [PATCH 05/11] Fix example name to avoid breaking collision with standard data-collectors --- cookbook/profiler/data_collector.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index db3a86bfdab..5ecb546185a 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -67,7 +67,7 @@ populate the ``$this->data`` property (it takes care of serializing the public function getName() { - return 'memory'; + return 'example_memory'; } } From 216ae511e33166ef79c8d32aaaadb3e940149471 Mon Sep 17 00:00:00 2001 From: Darien Hager Date: Mon, 23 Mar 2015 19:58:18 -0700 Subject: [PATCH 06/11] Add a cautionary note telling users where the "standard" data-collector names can be found. --- cookbook/profiler/data_collector.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 5ecb546185a..50eef5e42a1 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -70,6 +70,12 @@ populate the ``$this->data`` property (it takes care of serializing the return 'example_memory'; } } + +.. caution:: + + The string you use with `getName()` should not collide with standard data- + collectors, such as those within the + `Symfony\Component\HttpKernel\DataCollector\` package. .. _data_collector_tag: From dfc562069c88e15b20735bed262b276e5792d3fb Mon Sep 17 00:00:00 2001 From: Darien Hager Date: Tue, 24 Mar 2015 09:54:46 -0700 Subject: [PATCH 07/11] Revert "Add a cautionary note telling users where the "standard" data-collector names can be found." This reverts commit 62acae4ac2f5c309a56749aa9d4c0cd7979efc52. --- cookbook/profiler/data_collector.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 50eef5e42a1..5ecb546185a 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -70,12 +70,6 @@ populate the ``$this->data`` property (it takes care of serializing the return 'example_memory'; } } - -.. caution:: - - The string you use with `getName()` should not collide with standard data- - collectors, such as those within the - `Symfony\Component\HttpKernel\DataCollector\` package. .. _data_collector_tag: From 6406f225a42ec211cd4620f1bfa0d9ae3e32bef3 Mon Sep 17 00:00:00 2001 From: Darien Hager Date: Wed, 25 Mar 2015 13:41:47 -0700 Subject: [PATCH 08/11] Revert "Fix example name to avoid breaking collision with standard data-collectors" This reverts commit cbb500d64bb0dfe65f03ccba23c7cfe57a24a293. --- cookbook/profiler/data_collector.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/profiler/data_collector.rst b/cookbook/profiler/data_collector.rst index 5ecb546185a..db3a86bfdab 100644 --- a/cookbook/profiler/data_collector.rst +++ b/cookbook/profiler/data_collector.rst @@ -67,7 +67,7 @@ populate the ``$this->data`` property (it takes care of serializing the public function getName() { - return 'example_memory'; + return 'memory'; } } From e3c2fb6203140a341dbb74fda37e07aa8a48163d Mon Sep 17 00:00:00 2001 From: Darien Hager Date: Wed, 25 Mar 2015 13:48:18 -0700 Subject: [PATCH 09/11] Indenting caution block to nest it inside the sidebar --- book/doctrine.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index 55940c2dcfb..ce8332961ab 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -135,11 +135,11 @@ for you: as agnostic as possible in terms of environment configuration. One way to solve this problem is to configure server-level defaults. -.. caution:: + .. caution:: - If you are using MySQL, its `utf8` character set has some shortcomings - which may cause problems. Prefer the `utf8mb4` character set instead, if - your version supports it. + If you are using MySQL, its `utf8` character set actually only supports + a portion of valid UTF-8 data that you may encounter. Instead, try to + use the newer `utf8mb4` if your system supports it. Setting UTF8 defaults for MySQL is as simple as adding a few lines to your configuration file (typically ``my.cnf``): From 55874c449fbd0c96501eebfe78740e186dc68354 Mon Sep 17 00:00:00 2001 From: Darien Hager Date: Thu, 26 Mar 2015 13:02:11 -0700 Subject: [PATCH 10/11] Add backticks for code-styling --- book/doctrine.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index ce8332961ab..e1b4666e8bb 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -137,9 +137,9 @@ for you: .. caution:: - If you are using MySQL, its `utf8` character set actually only supports + If you are using MySQL, its ``utf8`` character set actually only supports a portion of valid UTF-8 data that you may encounter. Instead, try to - use the newer `utf8mb4` if your system supports it. + use the newer ``utf8mb4`` if your system supports it. Setting UTF8 defaults for MySQL is as simple as adding a few lines to your configuration file (typically ``my.cnf``): From 7d7d94e8ba0f1acf7c27897eddbfcd09a5f9ad56 Mon Sep 17 00:00:00 2001 From: Darien Hager Date: Wed, 29 Apr 2015 11:27:52 -0700 Subject: [PATCH 11/11] Rewrite utf8mb4 cautions, add comment into sample configuration --- book/doctrine.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/book/doctrine.rst b/book/doctrine.rst index e1b4666e8bb..d3b424920eb 100644 --- a/book/doctrine.rst +++ b/book/doctrine.rst @@ -134,12 +134,6 @@ for you: There's no way to configure these defaults inside Doctrine, as it tries to be as agnostic as possible in terms of environment configuration. One way to solve this problem is to configure server-level defaults. - - .. caution:: - - If you are using MySQL, its ``utf8`` character set actually only supports - a portion of valid UTF-8 data that you may encounter. Instead, try to - use the newer ``utf8mb4`` if your system supports it. Setting UTF8 defaults for MySQL is as simple as adding a few lines to your configuration file (typically ``my.cnf``): @@ -147,8 +141,13 @@ for you: .. code-block:: ini [mysqld] - collation-server = utf8mb4_general_ci - character-set-server = utf8mb4 + # Version 5.5.3 introduced "utf8mb4", which is recommended + collation-server = utf8mb4_general_ci # Replaces utf8_general_ci + character-set-server = utf8mb4 # Replaces utf8 + + We recommend against MySQL's ``utf8`` character set, since it does not + support 4-byte unicode characters, and strings containing them will be + truncated. This is fixed by the `newer utf8mb4 character set`_. .. note:: @@ -1428,3 +1427,4 @@ For more information about Doctrine, see the *Doctrine* section of the .. _`migrations`: http://symfony.com/doc/current/bundles/DoctrineMigrationsBundle/index.html .. _`DoctrineFixturesBundle`: http://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html .. _`FrameworkExtraBundle documentation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html +.. _`newer utf8mb4 character set`: https://dev.mysql.com/doc/refman/5.5/en/charset-unicode-utf8mb4.html