Skip to content

Commit a68ff44

Browse files
weaverryanweaverryan
committed
Merge branch '2.8'
* 2.8: (24 commits) [#5331] Tiny typo [#5373] Small tweak per Stof's comment Added depreciation note for the cascade_validation constraint and updated position of depreciation notes [PSR-7] Bridge documentation Fix after install URL and new photo since AcmeDemoBundle is not part of 2.7 Fixed a minor grammar issue Fixed typos Link to the official repository of the bundle. Added mentions to some popular (and useful) Symfony bundles [#5095] Fixing a typo and updating to a more realistic example [Components][ClassLoader] remove DebugClassLoader [#4228] Move synthetic services to its own recipe clarify bundle installation instructions Implemented the suggestions made by Christian and Wouter Replace phpDocumentor by the standard PHPDoc Implemented the changes suggested by reviewers Fixed an internal link reference Reviewed the Bundles cookbook articles Updated the list of reserved domains and the URL reference Use the reserved domains example.com and example.org ...
2 parents 078bb2d + bfea184 commit a68ff44

29 files changed

+319
-181
lines changed

‎book/installation.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -169,7 +169,8 @@ browsing the project directory and executing this command:
169169
$ cd my_project_name/
170170
$ php app/console server:run
171171
172-
Then, open your browser and access the ``http://localhost:8000`` URL to see the
172+
Then, open your browser and access the ``http://localhost:8000/app/example``
173+
URL to see the
173174
Welcome page of Symfony:
174175

175176
.. image:: /images/quick_tour/welcome.png

‎book/security.rst

+7-1
Original file line numberDiff line numberDiff line change
@@ -280,6 +280,11 @@ But who can you login as? Where do users come from?
280280
What other methods are supported? See the :doc:`Configuration Reference </reference/configuration/security>`
281281
or :doc:`build your own </cookbook/security/custom_authentication_provider>`.
282282

283+
.. tip::
284+
285+
If your application logs users in via a third-party service such as Google,
286+
Facebook or Twitter, check out the `HWIOAuthBundle`_ community bundle.
287+
283288
.. _security-user-providers:
284289
.. _where-do-users-come-from-user-providers:
285290

@@ -485,7 +490,7 @@ else, you'll want to encode their passwords. The best algorithm to use is
485490
<encoder class="Symfony\Component\Security\Core\User\User"
486491
algorithm="bcrypt"
487492
cost="12" />
488-
493+
489494
<!-- ... -->
490495
</config>
491496
</srv:container>
@@ -1381,3 +1386,4 @@ Learn More from the Cookbook
13811386
.. _`online tool`: https://www.dailycred.com/blog/12/bcrypt-calculator
13821387
.. _`frameworkextrabundle documentation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
13831388
.. _`security advisories database`: https://github.com/FriendsOfPHP/security-advisories
1389+
.. _`HWIOAuthBundle`: https://github.com/hwi/HWIOAuthBundle

‎components/class_loader/class_loader.rst

+1-2
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,7 @@ load all of your project's classes.
1212

1313
You can use both the ``ApcClassLoader`` and the ``XcacheClassLoader`` to
1414
:doc:`cache </components/class_loader/cache_class_loader>` a ``ClassLoader``
15-
instance or the ``DebugClassLoader`` to :doc:`debug </components/class_loader/debug_class_loader>`
16-
it.
15+
instance.
1716

1817
Usage
1918
-----

‎components/class_loader/debug_class_loader.rst

-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
1-
.. index::
2-
single: ClassLoader; DebugClassLoader
3-
41
Debugging a Class Loader
52
========================
63

‎components/class_loader/index.rst

+5-1
Original file line numberDiff line numberDiff line change
@@ -9,5 +9,9 @@ ClassLoader
99
psr4_class_loader
1010
map_class_loader
1111
cache_class_loader
12-
debug_class_loader
1312
class_map_generator
13+
14+
.. toctree::
15+
:hidden:
16+
17+
debug_class_loader

‎components/class_loader/introduction.rst

+8-6
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,14 @@ the class. Symfony provides three autoloaders, which are able to load your class
2323
* :doc:`/components/class_loader/map_class_loader`: loads classes using
2424
a static map from class name to file path.
2525

26-
Additionally, the Symfony ClassLoader component ships with a set of wrapper
27-
classes which can be used to add additional functionality on top of existing
28-
autoloaders:
29-
30-
* :doc:`/components/class_loader/cache_class_loader`
31-
* :doc:`/components/class_loader/debug_class_loader`
26+
Additionally, the Symfony ClassLoader component ships with a wrapper class
27+
which makes it possible
28+
:doc:`to cache the results of a class loader </components/class_loader/cache_class_loader>`.
29+
30+
When using the :doc:`Debug component </components/debug/introduction>`, you
31+
can also use a special :doc:`DebugClassLoader </components/debug/class_loader>`
32+
that eases debugging by throwing more helpful exceptions when a class could
33+
not be found by a class loader.
3234

3335
Installation
3436
------------

‎components/dependency_injection/advanced.rst

-96
Original file line numberDiff line numberDiff line change
@@ -73,61 +73,6 @@ below) to access this service (via the alias).
7373

7474
Services are by default public.
7575

76-
Synthetic Services
77-
------------------
78-
79-
Synthetic services are services that are injected into the container instead
80-
of being created by the container.
81-
82-
For example, if you're using the :doc:`HttpKernel </components/http_kernel/introduction>`
83-
component with the DependencyInjection component, then the ``request``
84-
service is injected in the
85-
:method:`ContainerAwareHttpKernel::handle() <Symfony\\Component\\HttpKernel\\DependencyInjection\\ContainerAwareHttpKernel::handle>`
86-
method when entering the request :doc:`scope </cookbook/service_container/scopes>`.
87-
The class does not exist when there is no request, so it can't be included in
88-
the container configuration. Also, the service should be different for every
89-
subrequest in the application.
90-
91-
To create a synthetic service, set ``synthetic`` to ``true``:
92-
93-
.. configuration-block::
94-
95-
.. code-block:: yaml
96-
97-
services:
98-
request:
99-
synthetic: true
100-
101-
.. code-block:: xml
102-
103-
<?xml version="1.0" encoding="UTF-8" ?>
104-
<container xmlns="http://symfony.com/schema/dic/services"
105-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
106-
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
107-
108-
<services>
109-
<service id="request" synthetic="true" />
110-
</services>
111-
</container>
112-
113-
.. code-block:: php
114-
115-
use Symfony\Component\DependencyInjection\Definition;
116-
117-
$container
118-
->setDefinition('request', new Definition())
119-
->setSynthetic(true);
120-
121-
As you see, only the ``synthetic`` option is set. All other options are only used
122-
to configure how a service is created by the container. As the service isn't
123-
created by the container, these options are omitted.
124-
125-
Now, you can inject the class by using
126-
:method:`Container::set <Symfony\\Component\\DependencyInjection\\Container::set>`::
127-
128-
// ...
129-
$container->set('request', new MyRequest(...));
130-
13176
Aliasing
13277
--------
13378

@@ -183,47 +128,6 @@ service by asking for the ``bar`` service like this::
183128
class: Example\Foo
184129
bar: "@foo"
185130
186-
187-
Requiring Files
188-
---------------
189-
190-
There might be use cases when you need to include another file just before
191-
the service itself gets loaded. To do so, you can use the ``file`` directive.
192-
193-
.. configuration-block::
194-
195-
.. code-block:: yaml
196-
197-
services:
198-
foo:
199-
class: Example\Foo\Bar
200-
file: "%kernel.root_dir%/src/path/to/file/foo.php"
201-
202-
.. code-block:: xml
203-
204-
<?xml version="1.0" encoding="UTF-8" ?>
205-
<container xmlns="http://symfony.com/schema/dic/services"
206-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
207-
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
208-
209-
<services>
210-
<service id="foo" class="Example\Foo\Bar">
211-
<file>%kernel.root_dir%/src/path/to/file/foo.php</file>
212-
</service>
213-
</services>
214-
</container>
215-
216-
.. code-block:: php
217-
218-
use Symfony\Component\DependencyInjection\Definition;
219-
220-
$definition = new Definition('Example\Foo\Bar');
221-
$definition->setFile('%kernel.root_dir%/src/path/to/file/foo.php');
222-
$container->setDefinition('foo', $definition);
223-
224-
Notice that Symfony will internally call the PHP statement ``require_once``,
225-
which means that your file will be included only once per request.
226-
227131
Decorating Services
228132
-------------------
229133

‎components/dependency_injection/definitions.rst

+12
Original file line numberDiff line numberDiff line change
@@ -125,3 +125,15 @@ You can also replace any existing method calls with an array of new ones with::
125125
the container is compiled. Once the container is compiled you cannot
126126
manipulate service definitions further. To learn more about compiling
127127
the container see :doc:`/components/dependency_injection/compilation`.
128+
129+
Requiring Files
130+
~~~~~~~~~~~~~~~
131+
132+
There might be use cases when you need to include another file just before
133+
the service itself gets loaded. To do so, you can use the
134+
:method:`Symfony\\Component\\DependencyInjection\\Definition::setFile` method::
135+
136+
$definition->setFile('/src/path/to/file/foo.php');
137+
138+
Notice that Symfony will internally call the PHP statement ``require_once``,
139+
which means that your file will be included only once per request.

‎components/dependency_injection/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
types
99
parameters
1010
definitions
11+
synthetic_services
1112
compilation
1213
tags
1314
factories

‎components/dependency_injection/synthetic_services.rst

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
.. index::
2+
single: DependencyInjection; Synthetic Services
3+
4+
How to Inject Instances into the Container
5+
------------------------------------------
6+
7+
When using the container in your application, you sometimes need to inject an
8+
instance instead of configuring the container to create a new instance.
9+
10+
For instance, if you're using the :doc:`HttpKernel </components/http_kernel/introduction>`
11+
component with the DependencyInjection component, then the ``kernel``
12+
service is injected into the container from within the ``Kernel`` class::
13+
14+
// ...
15+
abstract class Kernel implements KernelInterface, TerminableInterface
16+
{
17+
// ...
18+
protected function initializeContainer()
19+
{
20+
// ...
21+
$this->container->set('kernel', $this);
22+
23+
// ...
24+
}
25+
}
26+
27+
The ``kernel`` service is called a synthetic service. This service has to be
28+
configured in the container, so the container knows the service does exist
29+
during compilation (otherwise, services depending on this ``kernel`` service
30+
will get a "service does not exists" error).
31+
32+
In order to do so, you have to use
33+
:method:`Definition::setSynthetic() <Symfony\\Component\\DependencyInjection\\Definition::setSynthetic>`::
34+
35+
use Symfony\Component\DependencyInjectino\Definition;
36+
37+
// synthetic services don't specify a class
38+
$kernelDefinition = new Definition();
39+
$kernelDefinition->setSynthetic(true);
40+
41+
$container->setDefinition('your_service', $kernelDefinition);
42+
43+
Now, you can inject the instance in the container using
44+
:method:`Container::set() <Symfony\\Component\\DependencyInjection\\Container::set>`::
45+
46+
$yourService = new YourObject();
47+
$container->set('your_service', $yourService);
48+
49+
``$container->get('your_service')`` will now return the same instance as
50+
``$yourService``.

‎components/map.rst.inc

+1-1
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@
1111
* :doc:`/components/class_loader/psr4_class_loader`
1212
* :doc:`/components/class_loader/map_class_loader`
1313
* :doc:`/components/class_loader/cache_class_loader`
14-
* :doc:`/components/class_loader/debug_class_loader`
1514
* :doc:`/components/class_loader/class_map_generator`
1615

1716
* :doc:`/components/config/index`
@@ -47,6 +46,7 @@
4746
* :doc:`/components/dependency_injection/types`
4847
* :doc:`/components/dependency_injection/parameters`
4948
* :doc:`/components/dependency_injection/definitions`
49+
* :doc:`/components/dependency_injection/synthetic_services`
5050
* :doc:`/components/dependency_injection/compilation`
5151
* :doc:`/components/dependency_injection/tags`
5252
* :doc:`/components/dependency_injection/factories`

‎contributing/documentation/standards.rst

+4
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,9 @@ Code Examples
5757
Unless the example requires a custom bundle, make sure to always use the
5858
``AppBundle`` bundle to store your code;
5959
* Use ``Acme`` when the code requires a vendor name;
60+
* Use ``example.com`` as the domain of sample URLs and ``example.org`` and
61+
``example.net`` when additional domains are required. All of these domains are
62+
`reserved by the IANA`_.
6063
* To avoid horizontal scrolling on code blocks, we prefer to break a line
6164
correctly if it crosses the 85th character;
6265
* When you fold one or more lines of code, place ``...`` in a comment at the point
@@ -174,6 +177,7 @@ In addition, documentation follows these rules:
174177

175178
.. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
176179
.. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html
180+
.. _`reserved by the IANA`: http://tools.ietf.org/html/rfc2606#section-3
177181
.. _`American English`: http://en.wikipedia.org/wiki/American_English
178182
.. _`American English Oxford Dictionary`: http://www.oxforddictionaries.com/definition/american_english/
179183
.. _`headings and titles`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles

‎cookbook/assetic/asset_management.rst

+8
Original file line numberDiff line numberDiff line change
@@ -183,6 +183,12 @@ To include an image you can use the ``image`` tag.
183183
You can also use Assetic for image optimization. More information in
184184
:doc:`/cookbook/assetic/jpeg_optimize`.
185185

186+
.. tip::
187+
188+
Instead of using Assetic to include images, you may consider using the
189+
`LiipImagineBundle`_ community bundle, which allows to compress and
190+
manipulate images (rotate, resize, watermark, etc.) before serving them.
191+
186192
.. _cookbook-assetic-cssrewrite:
187193

188194
Fixing CSS Paths with the ``cssrewrite`` Filter
@@ -572,3 +578,5 @@ some isolated directory (e.g. ``/js/compiled``), to keep things organized:
572578
) as $url): ?>
573579
<script src="<?php echo $view->escape($url) ?>"></script>
574580
<?php endforeach ?>
581+
582+
.. _`LiipImagineBundle`: https://github.com/liip/LiipImagineBundle

‎cookbook/assetic/jpeg_optimize.rst

+6
Original file line numberDiff line numberDiff line change
@@ -250,4 +250,10 @@ file:
250250
),
251251
));
252252
253+
.. tip::
254+
255+
For uploaded images, you can compress and manipulate them using the
256+
`LiipImagineBundle`_ community bundle.
257+
253258
.. _`Jpegoptim`: http://www.kokkonen.net/tjko/projects.html
259+
.. _`LiipImagineBundle`: http://knpbundles.com/liip/LiipImagineBundle

0 commit comments

Comments
 (0)