A Simple Controller¶

While a controller can be any PHP callable (a function, method on an object, or a Closure), a controller is usually a method inside a controller class:

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

 // src/AppBundle/Controller/LuckyController.php
namespace AppBundle\Controller;
 use Symfony\Component\HttpFoundation\Response;
 use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
 class LuckyController  {
   /**
     * @Route("/lucky/number/{max}")
     */
   public function numberAction($max)  {
     $number = mt_rand(0,  $max);
     return new Response( '
    <
    html>
    <
    body>
    Lucky number: '
    .$number.'
    <
    /body>
    <
    /html>
    '
     );
     
  }
   
}

 

The controller is the numberAction() method, which lives inside a controller class LuckyController.

This controller is pretty straightforward:

• line 2: Symfony takes advantage of PHP's namespace functionality to namespace the entire controller class.
• line 4: Symfony again takes advantage of PHP's namespace functionality: the use keyword imports the Response class, which the controller must return.
• line 7: The class can technically be called anything - but should end in the word Controller (this isn't required, but some shortcuts rely on this).
• line 12: Each action method in a controller class is suffixed with Action (again, this isn't required, but some shortcuts rely on this). This method is allowed to have a $max argument thanks to the { max } wildcard in the route.
• line 16: The controller creates and returns a Response object.

The Base Controller Class & Services¶

For convenience, Symfony comes with an optional base 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 Accessing other 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.

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

1 2 3 4 5 6 7 8 9

 // src/AppBundle/Controller/LuckyController.php
namespace AppBundle\Controller;
 use Symfony\Bundle\FrameworkBundle\Controller\Controller;
 class LuckyController extends Controller  {
    // ...
  
}

 

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 action is to look in the Controller class.

$url = $this->
generateUrl('
blog_show'
,  array('
slug'
 =>
 '
slug-value'
));
 

 1 2 3 4 5 6 7 8 9 10 11 12 13 14

public function indexAction()  {
    // redirect to the "homepage" route
  return $this->
  redirectToRoute('
  homepage'
  );
    // do a permanent - 301 redirect
  return $this->
  redirectToRoute('
  homepage'
  ,  array(),  301);
    // redirect to a route with parameters
  return $this->
  redirectToRoute('
  blog_show'
  ,  array('
  slug'
   =>
   '
  my-page'
  ));
    // redirect externally
  return $this->
  redirect('
  http: //symfony.com/doc');
  
}

 

1 2 3 4 5 6

use Symfony\Component\HttpFoundation\RedirectResponse;
 public function indexAction()  {
   return new RedirectResponse($this->
  generateUrl('
  homepage'
  ));
   
}

 

 // renders app/Resources/views/lucky/number.html.twig
return $this->
render('
lucky/number.html.twig'
,  array('
name'
 =>
 $name));
 

 // renders app/Resources/views/lottery/lucky/number.html.twig
return $this->
render('
lottery/lucky/number.html.twig'
,  array( '
name'
 =>
 $name,  ));
 

1 2 3 4 5

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

1

$ php bin/console debug:container 

$from = $this->
getParameter('
app.mailer.from'
);
 

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:

 1 2 3 4 5 6 7 8 9 10

public function indexAction()  {
    // retrieve the object from database
  $product = ...;
   if (!$product)  {
     throw $this->
    createNotFoundException('
    The product does not exist'
    );
     
  }
   return $this->
  render(...);
   
}

 

The createNotFoundException() method is just a shortcut to create a special NotFoundHttpException object, which ultimately triggers a 404 HTTP response inside Symfony.

Of course, you're free to throw any Exception class in your controller - Symfony will automatically return a 500 HTTP response code.

1

throw new \Exception('
Something went wrong!'
);
 

In every case, an error page is shown to the end user and a full debug error page is shown to the developer (i.e. when you're using the app_dev.php front controller - see The imports Key: Loading other Configuration Files).

You'll want to customize the error page your user sees. To do that, see the How to Customize Error Pages article.

The Request object as a Controller Argument¶

What if you need to read query parameters, grab a request header or get access to an uploaded file? All of that information is stored in Symfony's Request object. To get it in your controller, just add it as an argument and type-hint it with the Request class:

1 2 3 4 5 6 7 8

use Symfony\Component\HttpFoundation\Request;
 public function indexAction(Request $request,  $firstName,  $lastName)  {
   $page = $request->
  query->
  get('
  page'
  ,  1);
    // ...
  
}

 

Keep reading for more information about using the Request object.

Managing the Session¶

Symfony provides a nice session object that you can use to store information about the user between requests. By default, Symfony stores the attributes in a cookie by using native PHP sessions.

To retrieve the session, call getSession() method on the Request object. This method returns a SessionInterface with easy methods for storing and fetching things from the session:

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

use Symfony\Component\HttpFoundation\Request;
 public function indexAction(Request $request)  {
   $session = $request->
  getSession();
    // store an attribute for reuse during a later user request
  $session->
  set('
  foo'
  ,  '
  bar'
  );
    // get the attribute set by another controller in another request
  $foobar = $session->
  get('
  foobar'
  );
    // use a default value if the attribute doesn't exist
  $filters = $session->
  get('
  filters'
  ,  array());
   
}

 

Stored attributes remain in the session for the remainder of that user's session.

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

use Symfony\Component\HttpFoundation\Request;
 public function updateAction(Request $request)  {
    // ...
  if ($form->
  isSubmitted() &
  &
   $form->
  isValid())  {
      // do some sort of processing
    $this->
    addFlash( '
    notice'
    ,  '
    Your changes were saved!'
     );
      // $this->addFlash() is equivalent to $request->getSession()->getFlashBag()->add()
    return $this->
    redirectToRoute(...);
     
  }
   return $this->
  render(...);
   
}

 

The Request and Response Object¶

As mentioned earlier, the framework will pass the Request object to any controller argument that is type-hinted with the Request class:

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

use Symfony\Component\HttpFoundation\Request;
 public function indexAction(Request $request)  {
   $request->
  isXmlHttpRequest();
    // is it an Ajax request?
  $request->
  getPreferredLanguage(array('
  en'
  ,  '
  fr'
  ));
    // retrieve GET and POST variables respectively
  $request->
  query->
  get('
  page'
  );
   $request->
  request->
  get('
  page'
  );
    // retrieve SERVER variables
  $request->
  server->
  get('
  HTTP_HOST'
  );
    // retrieves an instance of UploadedFile identified by foo
  $request->
  files->
  get('
  foo'
  );
    // retrieve a COOKIE value
  $request->
  cookies->
  get('
  PHPSESSID'
  );
    // retrieve an HTTP request header, with normalized, lowercase keys
  $request->
  headers->
  get('
  host'
  );
   $request->
  headers->
  get('
  content_type'
  );
   
}

 

The Request class has several public properties and methods that return any information you need about the request.

Like the Request, the Response object has also a public headers property. This is a ResponseHeaderBag that has some nice methods for getting and setting response headers. The header names are normalized so that using Content-Type is equivalent to content-type or even content_type.

The only requirement for a controller is to return a Response object. The Response class is an abstraction around the HTTP response - the text-based message filled with headers and content that's sent back to the client:

1 2 3 4 5 6 7 8

use Symfony\Component\HttpFoundation\Response;
  // create a simple Response with a 200 status code (the default)
$response = new Response('
Hello '
.$name,  Response::HTTP_OK);
  // create a CSS-response with a 200 status code
$response = new Response('
<
style>
... <
/style>
'
);
 $response->
headers->
set('
Content-Type'
,  '
text/css'
);
 

There are special classes that make certain kinds of responses easier:

• For files, there is BinaryFileResponse. See Serving Files.
• For streamed responses, there is StreamedResponse. See Streaming a Response.

1 2 3 4 5 6 7 8 9

 // ...
public function indexAction()  {
    // returns '{"username":"jane.doe"}' and sets the proper Content-Type header
  return $this->
  json(array('
  username'
   =>
   '
  jane.doe'
  ));
    // the shortcut defines three optional arguments
   // return $this->json($data, $status = 200, $headers = array(), $context = array());
  
}

 

1 2 3 4 5

public function fileAction()  {
    // send the file contents and force the browser to download it
  return $this->
  file('
  /path/to/some_file.pdf'
  );
   
}

 

 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

use Symfony\Component\HttpFoundation\File\File;
 use Symfony\Component\HttpFoundation\ResponseHeaderBag;
 public function fileAction()  {
    // load the file from the filesystem
  $file = new File('
  /path/to/some_file.pdf'
  );
   return $this->
  file($file);
    // rename the downloaded file
  return $this->
  file($file,  '
  custom_name.pdf'
  );
    // display the file contents in the browser instead of downloading it
  return $this->
  file('
  invoice_3241.pdf'
  ,  '
  my_invoice.pdf'
  ,  ResponseHeaderBag: : DISPOSITION_INLINE);
   
}

 

Final Thoughts¶

Whenever you create a page, you'll ultimately need to write some code that contains the logic for that page. In Symfony, this is called a controller, and it's a PHP function where you can do anything in order to return the final Response object that will be returned to the user.

To make life easier, you'll probably extend the base Controller class because this gives two things:

1. Shortcut methods (like render() and redirectToRoute());
2. Access to all of the useful objects (services) in the system via the get() method.

In other articles, you'll learn how to use specific services from inside your controller that will help you persist and fetch objects from a database, process form submissions, handle caching and more.

Keep Going!¶

Next, learn all about rendering templates with Twig.

Learn more about Controllers¶