Skip to content

[FrameworkBundle] Document the AbstractController #7657

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 2, 2017
Merged

[FrameworkBundle] Document the AbstractController #7657

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cf2ae91
[FrameworkBundle] Document the AbstractController
GuilhemN Mar 19, 2017
88a4806
Fix
GuilhemN Apr 6, 2017
4ac5da7
Fix
GuilhemN Apr 7, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 23 additions & 12 deletions controller.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,19 +116,30 @@ For more information on routing, see :doc:`/routing`.
.. index::
single: Controller; Base controller class

The Base Controller Class & Services
------------------------------------
.. _anchor-name:
:ref:`The Base Controller Classes & Services <the-base-controller-class-services>`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not familiar with this anchor-name thing - were you trying to make sure the old anchor still worked? If so, #7867 for an example. I'll update this in my PR

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes that was a request from @xabbuh.
Thanks for the example, I never did that before and obviously didn't do it well by randomly trying :)


For convenience, Symfony comes with an optional base
:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class.
If you extend it, this won't change anything about how your controller
works, but you'll get access to a number of **helper methods** and the
**service container** (see :ref:`controller-accessing-services`): an
The Base Controller Classes & Services
--------------------------------------

For convenience, Symfony comes with two optional base
:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` and
:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\AbstractController`
classes.
If you extend one or the other, this won't change anything about how your
controller works, but you'll get access to a number of **helper methods**.

The base ``Controller`` also allows you to access the **service container** (see :ref:`controller-accessing-services`): an
array-like object that gives you access to every useful object in the
system. These useful objects are called **services**, and Symfony ships
with a service object that can render Twig templates, another that can
log messages and many more.

On the other hand, the ``AbstractController`` prevents you from accessing the
**service container**. When you need an external dependency, this forces you to
write a code more robust as you have to explicitly define your dependencies by
using :doc:`the controller as a service </controller/service>`.

Add the ``use`` statement atop the ``Controller`` class and then modify
``LuckyController`` to extend it::

Expand All @@ -144,7 +155,7 @@ Add the ``use`` statement atop the ``Controller`` class and then modify

Helper methods are just shortcuts to using core Symfony functionality
that's available to you with or without the use of the base
``Controller`` class. A great way to see the core functionality in
controller classes. A great way to see the core functionality in
action is to look in the
:class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller` class.

Expand Down Expand Up @@ -241,10 +252,9 @@ are used for rendering templates, sending emails, querying the database and
any other "work" you can think of. When you install a new bundle, it probably
brings in even *more* services.

When extending the base controller class, you can access any Symfony service
When extending the base ``Controller`` class, you can access any Symfony service
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we're missing pros of using the new AbstractController, dependencies are explicit either in a constructor or in action signatures, but the controller needs to be configured to get injection.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean we have to tell that the controller has to be configured as a service ? I updated the text to reflect that.

Copy link
Contributor

@HeahDude HeahDude Apr 7, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm it seems I got confused, reading @nicolas-grekas's comment above:

In fact, there is no config to do at all, an AbstractController doesn't need to be a service at all

The injection in this case is relying on an argument value resolver, so the controller does not need any configuration indeed.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I just said is wrong, the getters has nothing to do with action injections, so I don't get it, this must be configured somehow, it's just already done by the bundle.

via the :method:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller::get`
method of the ``Controller`` class. Here are several common services you might
need::
method. Here are several common services you might need::

$templating = $this->get('templating');

Expand Down Expand Up @@ -279,7 +289,8 @@ Managing Errors and 404 Pages

When things are not found, you should play well with the HTTP protocol and
return a 404 response. To do this, you'll throw a special type of exception.
If you're extending the base ``Controller`` class, do the following::
If you're extending the base ``Controller`` or the base ``AbstractController``
class, do the following::

public function indexAction()
{
Expand Down