Merge branch '3.0' into 3.1

xabbuh · xabbuh · commit 34ea50f1d752 · 2016-06-20T14:12:12.000+02:00
* 3.0: Updating recommended email settings for monolog Update upload_file.rst fix dumper default representation Improve `Finder::path` code example about resulting matches preg_match throw an warning [symfony#6599] Make description a little bit more clear [Process] tweak a sentence Fixed null description of query_builder option
diff --git a/components/finder.rst b/components/finder.rst
@@ -202,7 +202,10 @@ Path
 Restrict files and directories by path with the
 :method:`Symfony\\Component\\Finder\\Finder::path` method::
 
-    $finder->path('some/special/dir');
+    // matches files that contain "data" anywhere in their paths (files or directories)
+    $finder->path('data');
+    // for example this will match data/*.xml and data.xml if they exist
+    $finder->path('data')->name('*.xml');
 
 On all platforms slash (i.e. ``/``) should be used as the directory separator.
 
diff --git a/components/process.rst b/components/process.rst
@@ -43,7 +43,7 @@ The ``getOutput()`` method always returns the whole content of the standard
 output of the command and ``getErrorOutput()`` the content of the error
 output. Alternatively, the :method:`Symfony\\Component\\Process\\Process::getIncrementalOutput`
 and :method:`Symfony\\Component\\Process\\Process::getIncrementalErrorOutput`
-methods returns the new outputs since the last call.
+methods return the new output since the last call.
 
 The :method:`Symfony\\Component\\Process\\Process::clearOutput` method clears
 the contents of the output and
diff --git a/components/yaml/introduction.rst b/components/yaml/introduction.rst
@@ -164,12 +164,15 @@ Array Expansion and Inlining
 ............................
 
 The YAML format supports two kind of representation for arrays, the expanded
-one, and the inline one. By default, the dumper uses the inline
+one, and the inline one. By default, the dumper uses the expanded
 representation:
 
 .. code-block:: yaml
 
-    { foo: bar, bar: { foo: bar, bar: baz } }
+    foo: bar
+    bar:
+        foo: bar
+        bar: baz
 
 The second argument of the :method:`Symfony\\Component\\Yaml\\Yaml::dump`
 method customizes the level at which the output switches from the expanded
diff --git a/cookbook/controller/upload_file.rst b/cookbook/controller/upload_file.rst
@@ -218,7 +218,7 @@ Creating an Uploader Service
 ----------------------------
 
 To avoid logic in controllers, making them big, you can extract the upload
-logic to a seperate service::
+logic to a separate service::
 
     // src/AppBundle/FileUploader.php
     namespace AppBundle;
diff --git a/cookbook/logging/monolog_email.rst b/cookbook/logging/monolog_email.rst
@@ -25,18 +25,20 @@ it is broken down.
                     # action_level: error
                     # excluded_404s:
                     #     - ^/
-                    handler:      buffered
-                buffered:
-                    type:    buffer
+                    handler:      deduplicated
+                deduplicated:
+                    type:    deduplication
                     handler: swift
                 swift:
                     type:       swift_mailer
                     from_email: 'error@example.com'
                     to_email:   'error@example.com'
                     # or list of recipients
                     # to_email:   ['dev1@example.com', 'dev2@example.com', ...]
-                    subject:    An Error Occurred!
+                    subject:    'An Error Occurred! %%message%%'
                     level:      debug
+                    formatter:  monolog.formatter.html
+                    content_type: text/html
 
     .. code-block:: xml
 
@@ -49,8 +51,9 @@ it is broken down.
                                 http://symfony.com/schema/dic/monolog http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
 
             <monolog:config>
-                <!--
-                To also log 400 level errors (but not 404's):
+                <!-- 
+                500 errors are logged at the critical level,
+                to also log 400 level errors (but not 404's):
                 action-level="error"
                 And add this child inside this monolog:handler
                 <monolog:excluded-404>^/</monolog:excluded-404>
@@ -59,23 +62,25 @@ it is broken down.
                     name="mail"
                     type="fingers_crossed"
                     action-level="critical"
-                    handler="buffered"
+                    handler="deduplicated"
                 />
                 <monolog:handler
-                    name="buffered"
-                    type="buffer"
+                    name="deduplicated"
+                    type="deduplication"
                     handler="swift"
-                />
+                >
                 <monolog:handler
                     name="swift"
                     type="swift_mailer"
                     from-email="error@example.com"
-                    subject="An Error Occurred!"
-                    level="debug">
+                    subject="An Error Occurred! %%message%%"
+                    level="debug"
+                    formatter="monolog.formatter.html"
+                    content-type="text/html">
 
                     <monolog:to-email>error@example.com</monolog:to-email>
 
-                    <!-- or multiple to-email elements -->
+                    <!-- or list of recipients -->
                     <!--
                     <monolog:to-email>dev1@example.com</monolog:to-email>
                     <monolog:to-email>dev2@example.com</monolog:to-email>
@@ -92,26 +97,29 @@ it is broken down.
             'handlers' => array(
                 'mail' => array(
                     'type'         => 'fingers_crossed',
+                    // 500 errors are logged at the critical level
                     'action_level' => 'critical',
                     // to also log 400 level errors (but not 404's):
                     // 'action_level' => 'error',
                     // 'excluded_404s' => array(
                     //     '^/',
                     // ),
-                    'handler'      => 'buffered',
+                    'handler'      => 'deduplicated',
                 ),
-                'buffered' => array(
-                    'type'    => 'buffer',
+                'deduplicated' => array(
+                    'type'    => 'deduplication',
                     'handler' => 'swift',
                 ),
                 'swift' => array(
-                    'type'       => 'swift_mailer',
-                    'from_email' => 'error@example.com',
-                    'to_email'   => 'error@example.com',
+                    'type'         => 'swift_mailer',
+                    'from_email'   => 'error@example.com',
+                    'to_email'     => 'error@example.com',
                     // or a list of recipients
                     // 'to_email'   => array('dev1@example.com', 'dev2@example.com', ...),
-                    'subject'    => 'An Error Occurred!',
-                    'level'      => 'debug',
+                    'subject'      => 'An Error Occurred! %%message%%',
+                    'level'        => 'debug',
+                    'formatter'    => 'monolog.formatter.html',
+                    'content_type' => 'text/html',
                 ),
             ),
         ));
@@ -121,20 +129,24 @@ it is only triggered when the action level, in this case ``critical`` is reached
 The ``critical`` level is only triggered for 5xx HTTP code errors. If this level
 is reached once, the ``fingers_crossed`` handler will log all messages
 regardless of their level. The ``handler`` setting means that the output
-is then passed onto the ``buffered`` handler.
+is then passed onto the ``deduplicated`` handler.
 
 .. tip::
 
     If you want both 400 level and 500 level errors to trigger an email,
     set the ``action_level`` to ``error`` instead of ``critical``. See the
     code above for an example.
 
-The ``buffered`` handler simply keeps all the messages for a request and
-then passes them onto the nested handler in one go. If you do not use this
-handler then each message will be emailed separately. This is then passed
-to the ``swift`` handler. This is the handler that actually deals with
-emailing you the error. The settings for this are straightforward, the
-to and from addresses and the subject.
+The ``deduplicated`` handler simply keeps all the messages for a request and
+then passes them onto the nested handler in one go, but only if the records are
+unique over a given period of time (60 seconds by default). If the records are
+duplicates they are simply discarded. Adding this handler reduces the amount of
+notifications to a manageable level, specially in critical failure scenarios.
+
+The messages are then passed to the ``swift`` handler. This is the handler that
+actually deals with emailing you the error. The settings for this are
+straightforward, the to and from addresses, the formatter, the content type 
+and the subject.
 
 You can combine these handlers with other handlers so that the errors still
 get logged on the server as well as the emails being sent:
@@ -152,20 +164,22 @@ get logged on the server as well as the emails being sent:
                     handler:      grouped
                 grouped:
                     type:    group
-                    members: [streamed, buffered]
+                    members: [streamed, deduplicated]
                 streamed:
                     type:  stream
                     path:  '%kernel.logs_dir%/%kernel.environment%.log'
                     level: debug
-                buffered:
-                    type:    buffer
+                deduplicated:
+                    type:    deduplication
                     handler: swift
                 swift:
                     type:       swift_mailer
                     from_email: 'error@example.com'
                     to_email:   'error@example.com'
-                    subject:    An Error Occurred!
+                    subject:    'An Error Occurred! %%message%%'
                     level:      debug
+                    formatter:  monolog.formatter.html
+                    content_type: text/html
 
     .. code-block:: xml
 
@@ -188,25 +202,36 @@ get logged on the server as well as the emails being sent:
                     type="group"
                 >
                     <member type="stream"/>
-                    <member type="buffered"/>
+                    <member type="deduplicated"/>
                 </monolog:handler>
                 <monolog:handler
                     name="stream"
                     path="%kernel.logs_dir%/%kernel.environment%.log"
                     level="debug"
                 />
                 <monolog:handler
-                    name="buffered"
-                    type="buffer"
+                    name="deduplicated"
+                    type="deduplication"
                     handler="swift"
                 />
                 <monolog:handler
                     name="swift"
+                    type="swift_mailer"
                     from-email="error@example.com"
-                    to-email="error@example.com"
-                    subject="An Error Occurred!"
+                    subject="An Error Occurred! %%message%%"
                     level="debug"
-                />
+                    formatter="monolog.formatter.html"
+                    content-type="text/html">
+
+                    <monolog:to-email>error@example.com</monolog:to-email>
+
+                    <!-- or list of recipients -->
+                    <!--
+                    <monolog:to-email>dev1@example.com</monolog:to-email>
+                    <monolog:to-email>dev2@example.com</monolog:to-email>
+                    ...
+                    -->
+                </monolog:handler>
             </monolog:config>
         </container>
 
@@ -222,29 +247,33 @@ get logged on the server as well as the emails being sent:
                 ),
                 'grouped' => array(
                     'type'    => 'group',
-                    'members' => array('streamed', 'buffered'),
+                    'members' => array('streamed', 'deduplicated'),
                 ),
                 'streamed'  => array(
                     'type'  => 'stream',
                     'path'  => '%kernel.logs_dir%/%kernel.environment%.log',
                     'level' => 'debug',
                 ),
-                'buffered'    => array(
-                    'type'    => 'buffer',
-                    'handler' => 'swift',
+                'deduplicated' => array(
+                    'type'     => 'deduplication',
+                    'handler'  => 'swift',
                 ),
                 'swift' => array(
-                    'type'       => 'swift_mailer',
-                    'from_email' => 'error@example.com',
-                    'to_email'   => 'error@example.com',
-                    'subject'    => 'An Error Occurred!',
-                    'level'      => 'debug',
+                    'type'         => 'swift_mailer',
+                    'from_email'   => 'error@example.com',
+                    'to_email'     => 'error@example.com',
+                    // or a list of recipients
+                    // 'to_email'   => array('dev1@example.com', 'dev2@example.com', ...),
+                    'subject'      => 'An Error Occurred! %%message%%',
+                    'level'        => 'debug',
+                    'formatter'    => 'monolog.formatter.html',
+                    'content_type' => 'text/html',
                 ),
             ),
         ));
 
 This uses the ``group`` handler to send the messages to the two
-group members, the ``buffered`` and the ``stream`` handlers. The messages will
+group members, the ``deduplicated`` and the ``stream`` handlers. The messages will
 now be both written to the log file and emailed.
 
 .. _Monolog: https://github.com/Seldaek/monolog
diff --git a/cookbook/security/custom_authentication_provider.rst b/cookbook/security/custom_authentication_provider.rst
@@ -135,7 +135,7 @@ set an authenticated token in the token storage if successful.
         {
             $request = $event->getRequest();
 
-            $wsseRegex = '/UsernameToken Username="([^"]+)", PasswordDigest="([^"]+)", Nonce="([a-zA-Z0-9+/]+={0,2})", Created="([^"]+)"/';
+            $wsseRegex = '/UsernameToken Username="([^"]+)", PasswordDigest="([^"]+)", Nonce="([a-zA-Z0-9+\/]+={0,2})", Created="([^"]+)"/';
             if (!$request->headers->has('x-wsse') || 1 !== preg_match($wsseRegex, $request->headers->get('x-wsse'), $matches)) {
                 return;
             }
diff --git a/reference/forms/types/entity.rst b/reference/forms/types/entity.rst
@@ -200,10 +200,8 @@ Allows you to create a custom query for your choices. See
 The value of this option can either be a ``QueryBuilder`` object, a Closure or
 ``null`` (which will load all entities). When using a Closure, you will be
 passed the ``EntityRepository`` of the entity as the only argument and should
-return a ``QueryBuilder``.
-
-If you'd like to display an empty list of entries, you can return ``null`` in
-the Closure.
+return a ``QueryBuilder``. Returning ``null`` in the Closure will result in
+loading all entities.
 
 Overridden Options
 ------------------

Original file line number	Diff line number	Diff line change
`@@ -135,7 +135,7 @@ set an authenticated token in the token storage if successful.`
`135`	`135`	`{`
`136`	`136`	`$request = $event->getRequest();`
`137`	`137`
`138`		`- $wsseRegex = '/UsernameToken Username="([^"]+)", PasswordDigest="([^"]+)", Nonce="([a-zA-Z0-9+/]+={0,2})", Created="([^"]+)"/';`
	`138`	`+ $wsseRegex = '/UsernameToken Username="([^"]+)", PasswordDigest="([^"]+)", Nonce="([a-zA-Z0-9+\/]+={0,2})", Created="([^"]+)"/';`
`139`	`139`	`if (!$request->headers->has('x-wsse') \|\| 1 !== preg_match($wsseRegex, $request->headers->get('x-wsse'), $matches)) {`
`140`	`140`	`return;`
`141`	`141`	`}`