8000 Merge branch '3.2' into 3.3 · symfony/symfony-docs@53c1e20 · GitHub
[go: up one dir, main page]
Skip to content

Commit 53c1e20

Browse files
xabbuhxabbuh
committed
Merge branch '3.2' into 3.3
* 3.2: [#8048] some minor tweaks [#8013] revert wrong data provider change correct PHP code Added a missing <script> tag in an example clarify workflow events minor tweak Fix comment to be consistent with the example Reworded the article about slashes in routing placeholders Minor reword of code contribution standards
2 parents d7fce7c + 1cd1950 commit 53c1e20

File tree

6 files changed

+64
-31
lines changed

6 files changed

+64
-31
lines changed

‎contributing/code/standards.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@ Naming Conventions
186186
* Use camelCase, not underscores, for variable, function and method
187187
names, arguments;
188188

189-
* Use underscores for option names and parameter names;
189+
* Use underscores for configuration options and parameters;
190190

191191
* Use namespaces for all classes;
192192

‎form/type_guesser.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ With this knowledge, you can easily implement the ``guessType()`` method of the
136136
$phpdoc = $reflectionProperty->getDocComment();
137137

138138
// parse the $phpdoc into an array like:
139-
// array('type' => 'string', 'since' => '1.0')
139+
// array('var' => 'string', 'since' => '1.0')
140140
$phpdocTags = ...;
141141

142142
return $phpdocTags;

‎form/unit_testing.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -191,7 +191,7 @@ allows you to return a list of extensions to register::
191191
$this->validator
192192
->method('validate')
193193
->will($this->returnValue(new ConstraintViolationList()));
194-
$validator
194+
$this->validator
195195
->method('getMetadataFor')
196196
->will($this->returnValue(new ClassMetadata(Form::class)));
197197

‎routing/generate_url_javascript.rst

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,12 @@ variables. The ``escape()`` function helps escape any non-JavaScript-safe values
2626
But if you *actually* need to generate routes in pure JavaScript, consider using
2727
the `FOSJsRoutingBundle`_. It makes the following possible:
2828

29-
.. code-block:: javascript
29+
.. code-block:: html+twig
3030

31+
<script>
3132
var url = Routing.generate('blog_show', {
3233
'slug': 'my-blog-post'
3334
});
35+
</script>
3436

3537
.. _`FOSJsRoutingBundle`: https://github.com/FriendsOfSymfony/FOSJsRoutingBundle

‎routing/slash_in_parameter.rst

Lines changed: 32 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -5,47 +5,47 @@ How to Allow a "/" Character in a Route Parameter
55
=================================================
66

77
Sometimes, you need to compose URLs with parameters that can contain a slash
8-
``/``. For example, take the classic ``/hello/{username}`` route. By default,
9-
``/hello/Fabien`` will match this route but not ``/hello/Fabien/Kris``. This
10-
is because Symfony uses this character as separator between route parts.
8+
``/``. For example, consider the ``/share/{token}`` route. If the ``token``
9+
value contains a ``/`` character this route won't match. This is because Symfony
10+
uses this character as separator between route parts.
1111

12-
This guide covers how you can modify a route so that ``/hello/Fabien/Kris``
13-
matches the ``/hello/{username}`` route, where ``{username}`` equals ``Fabien/Kris``.
12+
This article explains how you can modify a route definition so that placeholders
13+
can contain the ``/`` character too.
1414

1515
Configure the Route
1616
-------------------
1717

18-
By default, the Symfony Routing component requires that the parameters
19-
match the following regex path: ``[^/]+``. This means that all characters
20-
are allowed except ``/``.
18+
By default, the Symfony Routing component requires that the parameters match
19+
the following regular expression: ``[^/]+``. This means that all characters are
20+
allowed except ``/``.
2121

22-
You must explicitly allow ``/`` to be part of your parameter by specifying
23-
a more permissive regex path.
22+
You must explicitly allow ``/`` to be part of your placeholder by specifying
23+
a more permissive regular expression for it:
2424

2525
.. configuration-block::
2626

2727
.. code-block:: php-annotations
2828
2929
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
3030
31-
class DemoController
31+
class DefaultController
3232
{
3333
/**
34< A3E2 code>-
* @Route("/hello/{username}", name="_hello", requirements={"username"=".+"})
34+
* @Route("/share/{token}", name="share", requirements={"token"=".+"})
3535
*/
36-
public function helloAction($username)
36+
public function shareAction($token)
3737
{
3838
// ...
3939
}
4040
}
4141
4242
.. code-block:: yaml
4343
44-
_hello:
45-
path: /hello/{username}
46-
defaults: { _controller: AppBundle:Demo:hello }
44+
share:
45+
path: /share/{token}
46+
defaults: { _controller: AppBundle:Default:share }
4747
requirements:
48-
username: .+
48+
token: .+
4949
5050
.. code-block:: xml
5151
@@ -55,9 +55,9 @@ a more permissive regex path.
5555
xsi:schemaLocation="http://symfony.com/schema/routing
5656
http://symfony.com/schema/routing/routing-1.0.xsd">
5757
58-
<route id="_hello" path="/hello/{username}">
59-
<default key="_controller">AppBundle:Demo:hello</default>
60-
<requirement key="username">.+</requirement>
58+
<route id="share" path="/share/{token}">
59+
<default key="_controller">AppBundle:Default:share</default>
60+
<requirement key="token">.+</requirement>
6161
</route>
6262
</routes>
6363
@@ -67,12 +67,20 @@ a more permissive regex path.
6767
use Symfony\Component\Routing\Route;
6868
6969
$collection = new RouteCollection();
70-
$collection->add('_hello', new Route('/hello/{username}', array(
71-
'_controller' => 'AppBundle:Demo:hello',
70+
$collection->add('share', new Route('/share/{token}', array(
71+
'_controller' => 'AppBundle:Default:share',
7272
), array(
73-
'username' => '.+',
73+
'token' => '.+',
7474
)));
7575
7676
return $collection;
7777
78-
That's it! Now, the ``{username}`` parameter can contain the ``/`` character.
78+
That's it! Now, the ``{token}`` parameter can contain the ``/`` character.
79+
80+
.. note::
81+
82+
If the route defines several placeholders and you apply this permissive
83+
regular expression to all of them, the results won't be the expected. For
84+
example, if the route definition is ``/share/{path}/{token}`` and both
85+
``path`` and ``token`` accept ``/``, then ``path`` will contain its contents
86+
and the token, and ``token`` will be empty.

‎workflow/usage.rst

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -177,10 +177,23 @@ what actions are allowed on a blog post::
177177
Using Events
178178
------------
179179

180-
To make your workflows even more powerful you could construct the ``Workflow``
180+
To make your workflows more flexible, you can construct the ``Workflow``
181181
object with an ``EventDispatcher``. You can now create event listeners to
182-
block transitions (i.e. depending on the data in the blog post). The following
183-
events are dispatched:
182+
block transitions (i.e. depending on the data in the blog post) and do
183+
additional actions when a workflow operation happened (e.g. sending
184+
announcements).
185+
186+
Each step has three events that are fired in order:
187+
188+
* An event for every workflow;
189+
* An event for the workflow concerned;
190+
* An event for the workflow concerned with the specific transition or place name.
191+
192+
The following events are dispatched:
193+
194+
* ``workflow.guard``
195+
* ``workflow.[workflow name].guard``
196+
* ``workflow.[workflow name].guard.[transition name]``
184197

185198
* ``workflow.leave``
186199
* ``workflow.[workflow name].leave``
@@ -202,6 +215,14 @@ events are dispatched:
202215
* ``workflow.[workflow name].announce``
203216
* ``workflow.[workflow name].announce.[transition name]``
204217

218+
When a state transition is initiated, the events are fired in the following order:
219+
220+
- guard: Validate whether the transition is allowed at all (:ref:`see below <workflow-usage-guard-events>`);
221+
- leave: The object is about to leave a place;
222+
- transition: The object is going through this transition;
223+
- enter: The object entered a new place. This is the first event where the object' is marked as being in the new place;
224+
- announce: Triggered once for each workflow that now is available for the object.
225+
205226
Here is an example how to enable logging for every time a the "blog_publishing" workflow leaves a place::
206227

207228
use Psr\Log\LoggerInterface;
@@ -234,6 +255,8 @@ Here is an example how to enable logging for every time a the "blog_publishing"
234255
}
235256
}
236257

258+
.. _workflow-usage-guard-events:
259+
237260
Guard events
238261
~~~~~~~~~~~~
239262

0 commit comments

Comments
 (0)
0