Symfony for frontend developers #1 – where are my files?!

This article is part of a series; see Symfony for frontend developers for more.

Update 30/10/2014 The new Symfony Best Practices recommend various different locations for files.  If your project follows those recommendations, check out What do the new Symfony “Best Practices” mean for frontend developers?

Introduction

When I work with the frontend developers who are styling the pages I’ve made in Symfony, one question I’m often asked starts “Where is… ?”  This article is an attempt to answer that question.

Caveat

A lot of the folder structure in Symfony is convention rather than rule.  So your project might be different to what’s described here.  However, the conventions are very widely followed, and many of the principles will still apply even if you’re working on an unusually-structured project.

Your files are probably in one of three places

The template, CSS, script or image you’re looking for is probably in one of three places:

  • In a bundle’s Resources folder

  • In a vendor bundle

  • In app/Resources

Don’t worry if some of these terms don’t mean much – we’ll look at each of these places in turn.

In a bundle’s Resources folder

Files in a Symfony application are grouped into “Bundles”.  The idea here is partly to make code-reuse easier and partly just to provide structure to make code easier to find.

You’ll find your application’s bundles under src/ProjectName/.  The names of bundles’ folders will end in the word “Bundle”.

Ask yourself:  Which bundle looks as though it will have the files I need?  For login, for instance, you might find a bundle called “AuthenticationBundle”, “AccessBundle”, “CoreBundle” or maybe even “LoginBundle”.  It’s up to the backend developers what names they use, but hopefully there will be some system to it!  Get them to explain the bundle structure and how that relates to the site’s functionality.

Within each bundle, templates, CSS, javascripts and images live in subfolders of the Resources folder, typically as follows:

  • Templates — Resources/views

  • CSS — Resources/public/css

  • Javascript — Resources/public/js

  • Images — Resources/public/images

Tip: There’s more about tracking down template files in post 3 in this series.

If you can’t find the file there, it may be from a third-party library, which leads us to…

Vendor bundles and app/Resources

Symfony makes it really easy to use third-party functionality (“vendor dependencies”).  (In fact, Symfony itself is treated as a set of vendor dependencies for your project!)  Like your application’s code, this third-party code is grouped into Bundles too.  They live in the vendor folder.

Don’t look in vendor just yet, though!  Code from vendor dependencies can be overridden by your project itself, so check and see whether the application you’re styling has done this.

Remember how you looked in a bundle’s Resources folder earlier?  Well, there’s also the folder app/Resources at the root of your project.  This folder can be used to allow your application to override templates, javascript etc from third-party bundles.  This folder should be your next port-of-call when looking for files.

Ask yourself:  Which third-party bundle might provide the functionality I’m trying to style or the page I’m trying to mark up?

Within app/Resources you’ll find folders relating to each vendor bundle which is having something overridden (assuming there are any).  For example, if your project is overriding something from the the common “FriendsOfSymfony User Bundle”, you’ll see a folder app/Resources/FOSUserBundle.

Within these folders, you’ll see the same folder structure as for your app’s resources — the views folder and the public folder (or just one of these, depending on what’s being overridden).  And within these, there may also be subfolders.  The folder structure here has to match the structure used in the third-party bundle.  For example, your project could override the FOSUserBundle login template by putting it in app/Resources/FOSUserBundle/views/Security/login.html.twig

If your application isn’t already overriding the file you want, head on over to the vendor folder and see if you can find it in there.  If you do find it, don’t edit it directly!  Instead, you’ll need to override it in app/Resources.  Either read this guide to the overriding process, or get your backend developer to do it for you!

I still can’t find it!

If you’ve tried the folders discussed above and still can’t find the file you want, then take heart.  It may be so hard to find because it doesn’t actually exist!  Some asset files, and some bits of page content to do with forms, are dynamically created by Symfony.  You can read more in the articles in this series about Assets and about Symfony Forms — coming soon!

What about the web folder??

When trawling through files in Symfony projects, you may often find that a file is in two places — somewhere in src and also somewhere in the web folder.  In general, the simple rule-of-thumb is to ignore the web folder.

Basically, Symfony allows for logically structured folders for the files that you edit (in src) and then for a more website-friendly folder structure when the application is actually running (the files in web, which are automatically copied or linked there from src).  You can read more about this in article #5 in this series.

One tip may help you, though, which is that files can be renamed and combined as part of the process whereby Symfony moves them from src into web.  So, if you track down the file you want in web, don’t assume that it’ll have the same name in src (though it often will).  But there should be a sensible correspondence between its path under web and its path under src, so it’s not as bad as it sounds!

Up next

The next article in this series covers templating with Twig.  Check it out!

Post a Comment

Your email address is never published nor shared. Required fields are marked *

Ready to talk?

Whether you want to create a new digital product or make an existing one even better, we'd love to talk it through.

Get in touch