Merge branch '5.0'

* 5.0:
  [Validator] Removed old versionadded directive
  [Routing] Removed old versionadded directive
  Added the docs for the UUID polyfill
  [Validation] Mention the option to pass stringable objects
  [Routing] Documented the option to exclude patterns
  [Monolog] Add a caution note about Symfony Mailer and Monolog
  [ErrorHandler] Simplified docs

Author: OskarStark

components/error_handler.rst

@@ -22,14 +22,9 @@ Installation
 Usage
 -----
 
-The ErrorHandler component provides several tools to help you debug PHP code:
-
-* An **error handler** that turns PHP errors into exceptions;
-* An **exception handler** that turns uncaught PHP exceptions into nice PHP responses;
-* A **debug class loader** that provides better errors when a class is not found.
-
+The ErrorHandler component provides several tools to help you debug PHP code.
 Call this method (e.g. in your :ref:`front controller <architecture-front-controller>`)
-to enable all these features in your application::
+to enable all of them in your application::
 
     // public/index.php
     use Symfony\Component\ErrorHandler\Debug;
@@ -52,9 +47,10 @@ Turning PHP Errors into Exceptions
 ----------------------------------
 
 The :class:`Symfony\\Component\\ErrorHandler\\ErrorHandler` class catches PHP
-errors and turns them into PHP's :phpclass:`ErrorException` objects, except for
-fatal PHP errors, which are turned into Symfony's
-:class:`Symfony\\Component\\ErrorHandler\\Exception\\FatalErrorException` objects.
+errors and uncaught PHP exceptions and turns them into PHP's
+:phpclass:`ErrorException` objects, except for fatal PHP errors, which are
+turned into Symfony's :class:`Symfony\\Component\\ErrorHandler\\Exception\\FatalErrorException`
+objects.
 
 If the application uses the FrameworkBundle, this error handler is enabled by
 default in the :ref:`production environment <configuration-environments>`
@@ -120,26 +116,6 @@ wrap several function calls inside an anonymous function::
         return $data;
     });
 
-Debugging Uncaught PHP Exceptions
----------------------------------
-
-The :class:`Symfony\\Component\\ErrorHandler\\ExceptionHandler` class catches
-uncaught PHP exceptions and turns them into a nice response, so you can debug
-them. It is useful in :ref:`debug mode <debug-mode>` to replace the default
-PHP/XDebug output with something prettier and more useful.
-
-If the :doc:`HttpFoundation component </components/http_foundation>` is
-available, the handler returns a Symfony's
-:class:`Symfony\\Component\\HttpFoundation\\Response` object. Otherwise, it returns
-a generic PHP response.
-
-Use the following code (e.g. in your :ref:`front controller <architecture-front-controller>`)
-to enable this exception handler::
-
-    use Symfony\Component\ErrorHandler\ExceptionHandler;
-
-    ExceptionHandler::register();
-
 .. _component-debug-class-loader:
 
 Class Loading Debugger

components/polyfill_uuid.rst

@@ -0,0 +1,57 @@
+.. index::
+    single: Polyfill
+    single: PHP
+    single: Components; Polyfill
+
+The Symfony Polyfill / UUID Component
+=====================================
+
+    This component provides ``uuid_*`` functions to users who run PHP versions
+    without the UUID extension.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/polyfill-uuid
+
+.. include:: /components/require_autoload.rst.inc
+
+Usage
+-----
+
+Once this component is installed in your application, you can use the following
+functions, no matter if the `PHP UUID extension`_ is installed or not in your
+server.
+
+Provided Constants
+~~~~~~~~~~~~~~~~~~
+
+* ``UUID_VARIANT_NCS`` (value = 0)
+* ``UUID_VARIANT_DCE`` (value = 1)
+* ``UUID_VARIANT_MICROSOFT`` (value = 2)
+* ``UUID_VARIANT_OTHER`` (value = 3)
+* ``UUID_TYPE_DEFAULT`` (value = 0)
+* ``UUID_TYPE_TIME`` (value = 1)
+* ``UUID_TYPE_DCE`` (value = 4)
+* ``UUID_TYPE_NAME`` (value = 1)
+* ``UUID_TYPE_RANDOM`` (value = 4)
+* ``UUID_TYPE_NULL`` (value = -1)
+* ``UUID_TYPE_INVALID`` (value = -42)
+
+Provided Functions
+~~~~~~~~~~~~~~~~~~
+
+* :phpfunction:`uuid_create`
+* :phpfunction:`uuid_is_valid`
+* :phpfunction:`uuid_compare`
+* :phpfunction:`uuid_is_null`
+* :phpfunction:`uuid_type`
+* :phpfunction:`uuid_variant`
+* :phpfunction:`uuid_time`
+* :phpfunction:`uuid_mac`
+* :phpfunction:`uuid_parse`
+* :phpfunction:`uuid_unparse`
+
+.. _`PHP UUID extension`: https://pecl.php.net/package/uuid

logging/monolog_email.rst

@@ -4,6 +4,11 @@
 How to Configure Monolog to Email Errors
 ========================================
 
+.. caution::
+
+    This feature is not compatible yet with the new :doc:`Symfony mailer </mailer>`,
+    so it requires using SwiftMailer.
+
 `Monolog`_ can be configured to send an email when an error occurs with an
 application. The configuration for this requires a few nested handlers
 in order to avoid receiving too many emails. This configuration looks

routing.rst

@@ -1165,6 +1165,8 @@ the common configuration using options when importing the routes.
             # An imported route with an empty URL will become "/blog/"
             # Uncomment this option to make that URL "/blog" instead
             # trailing_slash_on_root: false
+            # you can optionally exclude some files/subdirectories when loading annotations
+            # exclude: '../src/Controller/{DebugEmailController}.php'
 
     .. code-block:: xml
 
@@ -1178,11 +1180,13 @@ the common configuration using options when importing the routes.
             <!--
                 the 'prefix' value is added to the beginning of all imported route URLs
                 the 'name-prefix' value is added to the beginning of all imported route names
+                the 'exclude' option defines the files or subdirectories ignored when loading annotations
             -->
             <import resource="../src/Controller/"
                 type="annotation"
                 prefix="/blog"
-                name-prefix="blog_">
+                name-prefix="blog_"
+                exclude="../src/Controller/{DebugEmailController}.php">
                 <!-- these requirements are added to all imported routes -->
                 <requirement key="_locale">en|es|fr</requirement>
             </import>
@@ -1202,6 +1206,8 @@ the common configuration using options when importing the routes.
         use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;
 
         return function (RoutingConfigurator $routes) {
+            // use the optional fifth argument of import() to exclude some files
+            // or subdirectories when loading annotations
             $routes->import('../src/Controller/', 'annotation')
                 // this is added to the beginning of all imported route URLs
                 ->prefix('/blog')

validation/custom_constraint.rst

@@ -85,6 +85,7 @@ The validator class is also simple, and only has one required method ``validate(
             }
 
             if (!preg_match('/^[a-zA-Z0-9]+$/', $value, $matches)) {
+                // the argument must be a string or an object implementing __toString()
                 $this->context->buildViolation($constraint->message)
                     ->setParameter('{{ string }}', $value)
                     ->addViolation();