Using Logical Names in Symfony

The intention of Symfony is to make things easier for developers. One of the big pain points when developing large and complex web applications is keeping track of the physical location of classes, templates and assets within your project. Symfony helps us out here by providing logical names for controllers, templates and files.

Why logical names?

Logical names provide an abstraction layer over the actual storage location of resources. This means we can use a “shortcut” URL that will point to the right location (provided we adhere to the standard file and folder layout).

For example, say you wanted to specify the name of a template file to use when rendering an action in your web application. Without logical naming, we’d need to provide a hard-coded file path such as:

/src/MyCompany/BlogBundle/Resources/views/Demo/post.html.twig

With logical names, we use a shorthand version of the URL that Symfony understands. Using the logical name instead, this becomes:

MyCompanyBlogBundle:Demo:post.html.twig

This is useful because it provides a standard naming convention for all files within our project. By enforcing this standard project layout, it makes it easier for us to work with other people’s Symfony bundles as we’ll always know the correct location for templates, controllers, and so on. This is also more robust than hard-coded paths, as the Symfony engine will dynamically generate the correct URL at run-time, so we if move our project to another location or folder we don’t need to go back and update any references.

Logical Names for Controllers

Because different kinds of files (controllers, templates, assets) are placed in different locations, the logical name we use to access the resource will depend on the kind of resource being accessed. For controllers, the format we’re going to use will look something like the following:

[BUNDLE NAME]:[CONTROLLER NAME]:[ACTION NAME]

In a real Symfony application, we might use the logical name of a controller to perform a redirect. This is illustrated below:

In this case, the user would be redirected to the “show” action in the “Blog” controller for the “MyCompanyBundle” bundle.

Logical Names for Templates

Templates follow a very similar naming convention to that of the controllers. Because there may be multiple templates for a single action however, there are some slight differences. For templates, we’ll use the format:

[BUNDLE NAME]:[CONTROLLER NAME]:[TEMPLATE NAME].[URL EXTENSION].[TEMPLATE EXTENSION]

… or more generally:

[BUNDLE NAME]:[CONTROLLER NAME]:[TEMPLATE NAME]

For example, see a real-world example below where we’re using the logical name of a template to render a blog post:

As with controllers, the file and folder layout for templates is a convention when using logical naming. The example above will end up in the following template being rendered out:

/src/MyCompany/BlogBundle/Resources/views/Blog/show.html.twig

Logical Names for Files

Less commonly, you may need to directly reference files within a bundle. These will typically not be standard assets like JavaScript, images and CSS, as these are usually stored in the publicly accessible “/web” folder. If we need to access a file within the bundle, we use the following format:

@[BUNDLE NAME]/path/to/file

A possible confusion

An important thing to note when using logical names is that a bundle typical resides inside of a namespace folder, so a bundle path is typically two levels deep – not one. Referring to the examples above, the bundle is called “MyCompanyBlogBundle”, which resides in the folder “/src/MyCompany/BlogBundle”, so a call to the logical name “@MyCompanyBlogBundle” resolves to this folder. This bundle name doesn’t come from concatenating the two folder names, but from the name used when creating the bundle.

For more information on logical naming, check out the Symfony documentation.