Skip to content

Commit f24b645

Browse files
weaverryanweaverryan
committed
Merge branch '2.7'
* 2.7: Yet another typo fix Applied fixes Applied comments Typo fix Use new factory syntax link to a bundle's current (not master) docs Documented new tags Documented expressionlanguage extensibility Documented html5 option Renamed empty_value to placeholder
2 parents d6ce29f + 5ec7cd1 commit f24b645

21 files changed

+258
-231
lines changed

Diff for: ‎book/security.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -2327,7 +2327,7 @@ Learn more from the Cookbook
23272327
* :doc:`/cookbook/security/remember_me`
23282328
* :doc:`How to Restrict Firewalls to a Specific Request </cookbook/security/firewall_restriction>`
23292329

2330-
.. _`FrameworkExtraBundle documentation`: http://symfony.com/doc/master/bundles/SensioFrameworkExtraBundle/annotations/security.html
2330+
.. _`FrameworkExtraBundle documentation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
23312331
.. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle
23322332
.. _`implement the \Serializable interface`: http://php.net/manual/en/class.serializable.php
23332333
.. _`Timing attack`: http://en.wikipedia.org/wiki/Timing_attack

Diff for: ‎components/dependency_injection/factories.rst

+53-104
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@
44
Using a Factory to Create Services
55
==================================
66

7+
.. versionadded:: 2.6
8+
The new `Symfony\\Component\\DependencyInjection\\Definition::setFactory`
9+
method was introduced in Symfony 2.6. Refer to older versions for the
10+
syntax for factories prior to 2.6.
11+
712
Symfony's Service Container provides a powerful way of controlling the
813
creation of objects, allowing you to specify arguments passed to the constructor
914
as well as calling methods and setting parameters. Sometimes, however, this
@@ -15,9 +20,9 @@ the class.
1520
Suppose you have a factory that configures and returns a new ``NewsletterManager``
1621
object::
1722

18-
class NewsletterFactory
23+
class NewsletterManagerFactory
1924
{
20-
public function get()
25+
public static function createNewsletterManager()
2126
{
2227
$newsletterManager = new NewsletterManager();
2328

@@ -28,22 +33,17 @@ object::
2833
}
2934

3035
To make the ``NewsletterManager`` object available as a service, you can
31-
configure the service container to use the ``NewsletterFactory`` factory
32-
class:
36+
configure the service container to use the
37+
``NewsletterFactory::createNewsletterManager()`` factory method:
3338

3439
.. configuration-block::
3540

3641
.. code-block:: yaml
3742
38-
parameters:
39-
# ...
40-
newsletter_manager.class: NewsletterManager
41-
newsletter_factory.class: NewsletterFactory
4243
services:
4344
newsletter_manager:
44-
class: "%newsletter_manager.class%"
45-
factory_class: "%newsletter_factory.class%"
46-
factory_method: get
45+
class: NewsletterManager
46+
factory: [NewsletterManagerFactory, createNewsletterManager]
4747
4848
.. code-block:: xml
4949
@@ -52,18 +52,10 @@ class:
5252
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
5353
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
5454
55-
<parameters>
56-
<!-- ... -->
57-
<parameter key="newsletter_manager.class">NewsletterManager</parameter>
58-
<parameter key="newsletter_factory.class">NewsletterFactory</parameter>
59-
</parameters>
60-
6155
<services>
62-
<service
63-
id="newsletter_manager"
64-
class="%newsletter_manager.class%"
65-
factory-class="%newsletter_factory.class%"
66-
factory-method="get" />
56+
<service id="newsletter_manager" class="NewsletterManager">
57+
<factory class="NewsletterManagerFactory" method="createNewsletterManager" />
58+
</service>
6759
</services>
6860
</services>
6961
@@ -72,35 +64,26 @@ class:
7264
use Symfony\Component\DependencyInjection\Definition;
7365
7466
// ...
75-
$container->setParameter('newsletter_manager.class', 'NewsletterManager');
76-
$container->setParameter('newsletter_factory.class', 'NewsletterFactory');
77-
78-
$definition = new Definition('%newsletter_manager.class%');
79-
$definition->setFactoryClass('%newsletter_factory.class%');
80-
$definition->setFactoryMethod('get');
67+
$definition = new Definition('NewsletterManager');
68+
$definition->setFactory(array('NewsletterManagerFactory', 'createNewsletterManager'));
8169
8270
$container->setDefinition('newsletter_manager', $definition);
8371
84-
When you specify the class to use for the factory (via ``factory_class``)
85-
the method will be called statically. If the factory itself should be instantiated
86-
and the resulting object's method called, configure the factory itself as a service.
87-
In this case, the method (e.g. get) should be changed to be non-static:
72+
Now, the method will be called statically. If the factory class itself should
73+
be instantiated and the resulting object's method called, configure the factory
74+
itself as a service. In this case, the method (e.g. get) should be changed to
75+
be non-static.
8876

8977
.. configuration-block::
9078

9179
.. code-block:: yaml
9280
93-
parameters:
94-
# ...
95-
newsletter_manager.class: NewsletterManager
96-
newsletter_factory.class: NewsletterFactory
9781
services:
98-
newsletter_factory:
99-
class: "%newsletter_factory.class%"
82+
newsletter_manager.factory:
83+
class: NewsletterManagerFactory
10084
newsletter_manager:
101-
class: "%newsletter_manager.class%"
102-
factory_service: newsletter_factory
103-
factory_method: get
85+
class: NewsletterManager
86+
factory: ["@newsletter_manager.factory", createNewsletterManager]
10487
10588
.. code-block:: xml
10689
@@ -109,47 +92,29 @@ In this case, the method (e.g. get) should be changed to be non-static:
10992
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
11093
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
11194
112-
<parameters>
113-
<!-- ... -->
114-
<parameter key="newsletter_manager.class">NewsletterManager</parameter>
115-
<parameter key="newsletter_factory.class">NewsletterFactory</parameter>
116-
</parameters>
117-
11895
<services>
119-
<service id="newsletter_factory" class="%newsletter_factory.class%"/>
96+
<service id="newsletter_manager.factory" class="NewsletterManagerFactory" />
12097
121-
<service
122-
id="newsletter_manager"
123-
class="%newsletter_manager.class%"
124-
factory-service="newsletter_factory"
125-
factory-method="get" />
98+
<service id="newsletter_manager" class="NewsletterManager">
99+
<factory service="newsletter_manager.factry" method="createNewsletterManager" />
100+
</service>
126101
</services>
127102
</container>
128103
129104
.. code-block:: php
130105
106+
use Symfony\Component\DependencyInjection\Reference;
131107
use Symfony\Component\DependencyInjection\Definition;
132108
133109
// ...
134-
$container->setParameter('newsletter_manager.class', 'NewsletterManager');
135-
$container->setParameter('newsletter_factory.class', 'NewsletterFactory');
110+
$container->register('newsletter_manager.factory', 'NewsletterManagerFactory');
136111
137-
$container->setDefinition('newsletter_factory', new Definition(
138-
'%newsletter_factory.class%'
112+
$newsletterManager = new Definition();
113+
$newsletterManager->setFactory(array(
114+
new Reference('newsletter_manager.factory'),
115+
'createNewsletterManager'
139116
));
140-
$container->setDefinition('newsletter_manager', new Definition(
141-
'%newsletter_manager.class%'
142-
))->setFactoryService(
143-
'newsletter_factory'
144-
)->setFactoryMethod(
145-
'get'
146-
);
147-
148-
.. note::
149-
150-
The factory service is specified by its id name and not a reference to
151-
the service itself. So, you do not need to use the @ syntax for this in
152-
YAML configurations.
117+
$container->setDefinition('newsletter_manager', $newsletterManager);
153118
154119
Passing Arguments to the Factory Method
155120
---------------------------------------
@@ -162,17 +127,13 @@ in the previous example takes the ``templating`` service as an argument:
162127

163128
.. code-block:: yaml
164129
165-
parameters:
166-
# ...
167-
newsletter_manager.class: NewsletterManager
168-
newsletter_factory.class: NewsletterFactory
169130
services:
170-
newsletter_factory:
171-
class: "%newsletter_factory.class%"
131+
newsletter_manager.factory:
132+
class: NewsletterManagerFactory
133+
172134
newsletter_manager:
173-
class: "%newsletter_manager.class%"
174-
factory_service: newsletter_factory
175-
factory_method: get
135+
class: NewsletterManager
136+
factory: ["@newsletter_manager.factory", createNewsletterManager]
176137
arguments:
177138
- "@templating"
178139
@@ -183,42 +144,30 @@ in the previous example takes the ``templating`` service as an argument:
183144
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
184145
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
185146
186-
<parameters>
187-
<!-- ... -->
188-
<parameter key="newsletter_manager.class">NewsletterManager</parameter>
189-
<parameter key="newsletter_factory.class">NewsletterFactory</parameter>
190-
</parameters>
191-
192147
<services>
193-
<service id="newsletter_factory" class="%newsletter_factory.class%"/>
148+
<service id="newsletter_manager.factory" class="NewsletterManagerFactory"/>
194149
195-
<service
196-
id="newsletter_manager"
197-
class="%newsletter_manager.class%"
198-
factory-service="newsletter_factory"
199-
factory-method="get">
200-
201-
<argument type="service" id="templating" />
150+
<service id="newsletter_manager" class="NewsletterManager">
151+
<factory service="newsletter_manager.factory" method="createNewsletterManager"/>
152+
<argument type="service" id="templating"/>
202153
</service>
203154
</services>
204155
</container>
205156
206157
.. code-block:: php
207158
159+
use Symfony\Component\DependencyInjection\Reference;
208160
use Symfony\Component\DependencyInjection\Definition;
209161
210162
// ...
211-
$container->setParameter('newsletter_manager.class', 'NewsletterManager');
212-
$container->setParameter('newsletter_factory.class', 'NewsletterFactory');
163+
$container->register('newsletter_manager.factory', 'NewsletterManagerFactory');
213164
214-
$container->setDefinition('newsletter_factory', new Definition(
215-
'%newsletter_factory.class%'
216-
));
217-
$container->setDefinition('newsletter_manager', new Definition(
218-
'%newsletter_manager.class%',
165+
$newsletterManager = new Definition(
166+
'NewsletterManager',
219167
array(new Reference('templating'))
220-
))->setFactoryService(
221-
'newsletter_factory'
222-
)->setFactoryMethod(
223-
'get'
224168
);
169+
$newsletterManager->setFactory(array(
170+
new Reference('newsletter_manager.factory'),
171+
'createNewsletterManager'
172+
));
173+
$container->setDefinition('newsletter_manager', $newsletterManager);

Diff for: ‎components/expression_language/extending.rst

+58-14
Original file line numberDiff line numberDiff line change
@@ -51,24 +51,34 @@ an ``arguments`` variable as their first argument, which is equal to the
5151
second argument to ``evaluate()`` or ``compile()`` (e.g. the "values" when
5252
evaluating or the "names" if compiling).
5353

54-
Creating a new ExpressionLanguage Class
55-
---------------------------------------
54+
.. _components-expression-language-provider:
5655

57-
When you use the ``ExpressionLanguage`` class in your library, it's recommend
58-
to create a new ``ExpressionLanguage`` class and register the functions there.
59-
Override ``registerFunctions`` to add your own functions::
56+
Using Expression Providers
57+
--------------------------
6058

61-
namespace Acme\AwesomeLib\ExpressionLanguage;
59+
.. versionadded:: 2.6
60+
Expression providers were introduced in Symfony 2.6.
6261

63-
use Symfony\Component\ExpressionLanguage\ExpressionLanguage as BaseExpressionLanguage;
62+
When you use the ``ExpressionLanguage`` class in your library, you often want
63+
to add custom functions. To do so, you can create a new expression provider by
64+
creating a class that implements
65+
:class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunctionProviderInterface`.
6466

65-
class ExpressionLanguage extends BaseExpressionLanguage
66-
{
67-
protected function registerFunctions()
68-
{
69-
parent::registerFunctions(); // do not forget to also register core functions
67+
This interface requires one method:
68+
:method:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunctionProviderInterface::getFunctions`,
69+
which returns an array of expression functions (instances of
70+
:class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunction`) to
71+
register.
72+
73+
.. code-block:: php
74+
75+
use Symfony\Component\ExpressionLanguage\ExpressionFunction;
76+
use Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface;
7077
71-
$this->register('lowercase', function ($str) {
78+
class StringExpressionLanguageProvider implements ExpressionFunctionProviderInterface
79+
{
80+
return array(
81+
new ExpressionFunction('lowercase', function ($str) {
7282
return sprintf('(is_string(%1$s) ? strtolower(%1$s) : %1$s)', $str);
7383
}, function ($arguments, $str) {
7484
if (!is_string($str)) {
@@ -77,5 +87,39 @@ Override ``registerFunctions`` to add your own functions::
7787
7888
return strtolower($str);
7989
});
80-
}
90+
);
8191
}
92+
93+
You can register providers using
94+
:method:`Symfony\\Component\\ExpressionLanguage\\ExpressionLanguage::registerProvider`
95+
or by using the second argument of the constructor::
96+
97+
use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
98+
99+
// using the constructor
100+
$language = new ExpressionLanguage(null, array(
101+
new StringExpressionLanguageProvider(),
102+
// ...
103+
));
104+
105+
// using registerProvider()
106+
$language->registerProvider(new StringExpressionLanguageProvider());
107+
108+
.. tip::
109+
110+
It is recommended to create your own ``ExpressionLanguage`` class in your
111+
library. Now you can add the extension by overriding the constructor::
112+
113+
use Symfony\Component\ExpressionLanguage\ExpressionLanguage as BaseExpressionLanguage;
114+
use Symfony\Component\ExpressionLanguage\ParserCache\ParserCacheInterface;
115+
116+
class ExpressionLanguage extends BaseExpressionLanguage
117+
{
118+
public function __construct(ParserCacheInterface $parser = null, array $providers = array())
119+
{
120+
// prepend the default provider to let users override it easily
121+
array_unshift($providers, new StringExpressionLanguageProvider());
122+
123+
parent::__construct($parser, $providers);
124+
}
125+
}

Diff for: ‎cookbook/form/create_custom_field_type.rst

+6-2
Original file line numberDiff line numberDiff line change
@@ -240,7 +240,7 @@ new instance of the type in one of your forms::
240240
public function buildForm(FormBuilderInterface $builder, array $options)
241241
{
242242
$builder->add('gender_code', new GenderType(), array(
243-
'empty_value' => 'Choose a gender',
243+
'placeholder' => 'Choose a gender',
244244
));
245245
}
246246
}
@@ -249,6 +249,10 @@ But this only works because the ``GenderType()`` is very simple. What if
249249
the gender codes were stored in configuration or in a database? The next
250250
section explains how more complex field types solve this problem.
251251

252+
.. versionadded:: 2.6
253+
The ``placeholder`` option was introduced in Symfony 2.6 in favor of
254+
``empty_value``, which is available prior to 2.6.
255+
252256
.. _form-cookbook-form-field-service:
253257

254258
Creating your Field Type as a Service
@@ -378,7 +382,7 @@ configuration, using the field is now much easier::
378382
public function buildForm(FormBuilderInterface $builder, array $options)
379383
{
380384
$builder->add('gender_code', 'gender', array(
381-
'empty_value' => 'Choose a gender',
385+
'placeholder' => 'Choose a gender',
382386
));
383387
}
384388
}

0 commit comments

Comments
 (0)