Rendering a Template

A template is the file that produces the HTML a browser receives. Keeping that markup inside a controller mixes two jobs. Moving it to a template separates them. Symfony renders templates with Twig, a template language with its own syntax.

Twig is not PHP wearing a costume. Each template is compiled once into a PHP class under var/cache, and that generated class is what runs on later requests. A template therefore cannot call arbitrary PHP; it can use only what Twig exposes. That constraint is the point, because it keeps logic out of the view.

Where templates live

Templates live in templates/ at the project root. That directory is the twig.default_path setting, whose default value is %kernel.project_dir%/templates. Names are relative to it, so article/index.html.twig means templates/article/index.html.twig. Two extensions is the convention: the first names the output format, the second is always twig.

Rendering from a controller

render() comes from AbstractController. Its first argument is the template name. Its second is an array whose keys become variable names inside the template, so 'articles' => $articles makes {{ articles }} available. It returns a Response, which a controller returns directly. In the example below, GET /articles returns 200 with the rendered page.

The short form and the long form are the same thing. return $this->render($name, $vars); is return new Response($this->renderView($name, $vars));. renderView() hands back the string, which is what you want for an email body or a fragment you intend to store.

// src/Controller/ArticleController.php
declare(strict_types=1);

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class ArticleController extends AbstractController
{
    // GET /articles returns 200 with the rendered HTML of
    // templates/article/index.html.twig
    #[Route('/articles', name: 'app_article_index', methods: ['GET'])]
    public function index(): Response
    {
        // Plain PHP values for now. Nothing here reads a database.
        $articles = [
            ['title' => 'Routing', 'minutes' => 6],
            ['title' => 'Templates', 'minutes' => 9],
        ];

        // First argument: the file templates/article/index.html.twig
        // Second argument: every key becomes a variable in the template
        return $this->render('article/index.html.twig', [
            'page_title' => 'Articles',
            'articles' => $articles,
        ]);
    }
}

{# templates/article/index.html.twig #}
<h1>{{ page_title }}</h1>

<ul>
{% for article in articles %}
    <li>{{ article.title }} - {{ article.minutes }} min</li>
{% else %}
    <li>Nothing published yet.</li>
{% endfor %}
</ul>

// src/Controller/ArticleController.php (a second action on the same class)
#[Route('/articles/{slug}/card', name: 'app_article_card', methods: ['GET'])]
public function card(string $slug): Response
{
    // renderView() returns the rendered template as a string.
    $html = $this->renderView('article/_card.html.twig', [
        'slug' => $slug,
    ]);

    // A controller must return a Response, so build one around the string.
    return new Response($html, Response::HTTP_OK, [
        'Content-Type' => 'text/html; charset=UTF-8',
    ]);
}

# config/packages/twig.yaml
twig:
    # Where template names are resolved from. This is the default value.
    default_path: '%kernel.project_dir%/templates'

    # Unknown variables raise an error instead of rendering nothing.
    # The default is %kernel.debug%, so it is on in dev and off in prod.
    strict_variables: '%kernel.debug%'