8000 Merge branch '3.4' · symfony/symfony-docs@faf37e9 · GitHub
[go: up one dir, main page]
Skip to content

Commit faf37e9

Browse files
weaverryanweaverryan
committed
Merge branch '3.4'
* 3.4: tweaks thanks to review Adding second argument to setTrustedProxies() and removing old information replace trusted_proxies reference replace diff code block with PHP code block Remove deprecated trusted_proxies config option Remove deprecated trusted_proxies config option Tweaks after review! Tweaks thanks to Javier's reviews updating example to show class as service id Fixing bad indentation with diff more type changes updating best practices for DI 3.3 changes Minor tweaks for the article that explains the new 3.3 DI features Update some examples using 3.3 features
2 parents 502e333 + f89e2d0 commit faf37e9

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+835
-2002
lines changed

‎_build/redirection_map

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -336,3 +336,6 @@
336336
/components/dependency_injection/autowiring /service_container/autowiring
337337
/event_dispatcher/class_extension /event_dispatcher
338338
/security/target_path /security
339+
/service_container/third_party /service_container
340+
/templating/templating_service /templates
341+
/components/http_foundation/trusting_proxies /request/load_balancer_reverse_proxy

‎best_practices/business-logic.rst

Lines changed: 33 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -84,30 +84,42 @@ Next, define a new service for that class.
8484
8585
# app/config/services.yml
8686
services:
87-
# keep your service names short
88-
app.slugger:
89-
class: AppBundle\Utils\Slugger
87+
# ...
88+
89+
# use the fully-qualified class name as the service id
90+
AppBundle\Utils\Slugger:
91+
public: false
92+
93+
.. note::
9094

91-
Traditionally, the naming convention for a service involved following the
92-
class name and location to avoid name collisions. Thus, the service
93-
*would have been* called ``app.utils.slugger``. But by using short service names,
94-
your code will be easier to read and use.
95+
If you're using the :ref:`default services.yml configuration <service-container-services-load-example>`,
96+
the class is auto-registered as a service.
97+
98+
Traditionally, the naming convention for a service was a short, but unique
99+
snake case key - e.g. ``app.utils.slugger``. But for most services, you should now
100+
use the class name.
95101

96102
.. best-practice::
97103

98-
The name of your application's services should be as short as possible,
99-
but unique enough that you can search your project for the service if
100-
you ever need to.
104+
The id of your application's services should be equal to their class name,
105+
except when you have multiple services configured for the same class (in that
106+
case, use a snake case id).
101107

102108
Now you can use the custom slugger in any controller class, such as the
103109
``AdminController``:
104110

105111
.. code-block:: php
106112
107-
public function createAction(Request $request)
113+
use AppBundle\Utils\Slugger;
114+
115+
public function createAction(Request $request, Slugger $slugger)
108116
{
109117
// ...
110118
119+
// you can also fetch a public service like this
120+
// but fetching services in this way is not considered a best practice
121+
// $slugger = $this->get('app.slugger');
122+
111123
if ($form->isSubmitted() && $form->isValid()) {
112124
$slug = $this->get('app.slugger')->slugify($post->getTitle());
113125
$post->setSlug($slug);
@@ -116,6 +128,16 @@ Now you can use the custom slugger in any controller class, such as the
116128
}
117129
}
118130
131+
Services can also be :ref:`public or private <container-public>`. If you use the
132+
:ref:`default services.yml configuration <service-container-services-load-example>`,
133+
all services are private by default.
134+
135+
.. best-practice::
136+
137+
Services should be ``private`` whenever possible. This will prevent you from
138+
accessing that service via ``$container->get()``. Instead, you will need to use
139+
dependency injection.
140+
119141
Service Format: YAML
120142
--------------------
121143

‎best_practices/controllers.rst

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -97,16 +97,16 @@ for the homepage of our app:
9797
9898
use Symfony\Bundle\FrameworkBundle\Controller\Controller;
9999
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
100+
use Doctrine\ORM\EntityManagerInterface;
100101
101102
class DefaultController extends Controller
102103
{
103104
/**
104105
* @Route("/", name="homepage")
105106
*/
106-
public function indexAction()
107+
public function indexAction(EntityManagerInterface $em)
107108
{
108-
$posts = $this->getDoctrine()
109-
->getRepository('AppBundle:Post')
109+
$posts = $em->getRepository('AppBundle:Post')
110110
->findLatest();
111111
112112
return $this->render('default/index.html.twig', array(
@@ -115,6 +115,22 @@ for the homepage of our app:
115115
}
116116
}
117117
118+
Fetching Services
119+
-----------------
120+
121+
If you extend the base ``Controller`` class, you can access services directly from
122+
the container via ``$this->container->get()`` or ``$this->get()``. But instead, you
123+
should use dependency injection to fetch services: most easily done by
124+
:ref:`type-hinting action method arguments <controller-accessing-services>`:
125+
126+
.. best-practice::
127+
128+
Don't use ``$this->get()`` or ``$this->container->get()`` to fetch services
129+
from the container. Instead, use dependency injection.
130+
131+
By not fetching services directly from the container, you can make your services
132+
*private*, which has :ref:`several advantages <services-why-private>`.
133+
118134
.. _best-practices-paramconverter:
119135

120136
Using the ParamConverter

‎best_practices/security.rst

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -224,9 +224,9 @@ more advanced use-case, you can always do the same security check in PHP:
224224
/**
225225
* @Route("/{id}/edit", name="admin_post_edit")
226226
*/
227-
public function editAction($id)
227+
public function editAction($id, EntityManagerInterface $em)
228228
{
229-
$post = $this->getDoctrine()->getRepository('AppBundle:Post')
229+
$post = $em->getRepository('AppBundle:Post')
230230
->find($id);
231231
232232
if (!$post) {
@@ -328,7 +328,8 @@ the same ``getAuthorEmail()`` logic you used above:
328328
}
329329
}
330330
331-
Your application will :ref:`autoconfigure <services-autoconfigure>` your security
331+
If you're using the :ref:`default services.yml configuration <service-container-services-load-example>`,
332+
your application will :ref:`autoconfigure <services-autoconfigure>` your security
332333
voter and inject a ``AccessDecisionManagerInterface`` instance in it thanks to
333334
:doc:`autowiring </service_container/autowiring>`.
334335

‎bundles/best_practices.rst

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -384,7 +384,14 @@ If the bundle defines services, they must be prefixed with the bundle alias.
384384
For example, AcmeBlogBundle services must be prefixed with ``acme_blog``.
385385

386386
In addition, services not meant to be used by the application directly, should
387-
be :ref:`defined as private <container-private-services>`.
387+
be :ref:`defined as private <container-private-services>`. For public services,
388+
:ref:`aliases should be created <service-autowiring-alias>` from the interface/class
389+
to the service id. For example, in MonologBundle, an alias is created from
390+
``Psr\Log\LoggerInterface`` to ``logger`` so that the ``LoggerInterface`` type-hint
391+
can be used for autowiring.
392+
393+
Services should not use autowiring or autoconfiguration. Instead, all services should
394+
be defined explicitly.
388395

389396
.. seealso::
390397

‎bundles/extension.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,12 @@ read more about it, see the ":doc:`/bundles/configuration`" article.
129129
Adding Classes to Compile
130130
-------------------------
131131

132+
.. note::
133+
134+
The ``addClassesToCompile()`` method was deprecated in Symfony 3.3, and will
135+
be removed in Symfony 4.0. If you want to use this method and be compatible
136+
with Symfony 4.0, check to see if the method exists before calling it.
137+
132138
Symfony creates a big ``classes.php`` file in the cache directory to aggregate
133139
the contents of the PHP classes that are used in every request. This reduces the
134140
I/O operations and increases the application performance.

‎components/http_foundation/trusting_proxies.rst

Lines changed: 0 additions & 65 deletions
This file was deleted.

‎console/command_in_controller.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,12 @@ Run this command from inside your controller via::
3232
use Symfony\Component\Console\Input\ArrayInput;
3333
use Symfony\Component\Console\Output\BufferedOutput;
3434
use Symfony\Component\HttpFoundation\Response;
35+
use Symfony\Component\HttpKernel\KernelInterface;
3536

3637
class SpoolController extends Controller
3738
{
38-
public function sendSpoolAction($messages = 10)
39+
public function sendSpoolAction($messages = 10, KernelInterface $kernel)
3940
{
40-
$kernel = $this->get('kernel');
4141
$application = new Application($kernel);
4242
$application->setAutoExit(false);
4343

0 commit comments

Comments
 (0)
0