Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 62 ยท Getting Started

Project Structure

Tour every folder of a Symfony project: bin, config, public, src, templates, var and vendor, plus the .env files, composer.json and the front controller.

A new Symfony project looks busy at first: a dozen folders, several hidden files and a config directory full of YAML. But the layout follows one simple idea. Folders are split by who writes the files and what happens to them. You write the code in src/ and templates/; Symfony and Composer generate var/ and vendor/; the web server only ever sees public/.

This lesson walks through every top-level folder of a standard --webapp project, explains the .env files and composer.json, and then reads the front controller line by line. Once you understand this map, you will know where to put every new file for the rest of the tutorial.

The map

TEXT
my_project/
โ”œโ”€โ”€ assets/          front-end JavaScript and CSS (webapp)
โ”œโ”€โ”€ bin/
โ”‚   โ””โ”€โ”€ console      the command-line entry point
โ”œโ”€โ”€ config/
โ”‚   โ”œโ”€โ”€ packages/    one config file per package
โ”‚   โ”œโ”€โ”€ routes/      route-loading config
โ”‚   โ”œโ”€โ”€ bundles.php  which bundles are enabled
โ”‚   โ”œโ”€โ”€ routes.yaml
โ”‚   โ””โ”€โ”€ services.yaml
โ”œโ”€โ”€ migrations/      database migrations
โ”œโ”€โ”€ public/
โ”‚   โ””โ”€โ”€ index.php    the front controller
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ Controller/
โ”‚   โ”œโ”€โ”€ Entity/
โ”‚   โ”œโ”€โ”€ Repository/
โ”‚   โ””โ”€โ”€ Kernel.php
โ”œโ”€โ”€ templates/       Twig files
โ”œโ”€โ”€ tests/
โ”œโ”€โ”€ translations/
โ”œโ”€โ”€ var/             cache and logs (generated)
โ”œโ”€โ”€ vendor/          Composer packages (generated)
โ”œโ”€โ”€ .env             default environment variables
โ”œโ”€โ”€ composer.json
โ””โ”€โ”€ symfony.lock

A skeleton project has fewer of these (no templates/, migrations/ or assets/ until you install the matching packages). Here the same map as a diagram of responsibilities:

flowchart LR
    subgraph You["You write and commit"]
        SRC["src/"]
        TPL["templates/"]
        CFG["config/"]
        ENV[".env"]
    end
    subgraph Gen["Generated, not committed"]
        VAR["var/"]
        VEN["vendor/"]
    end
    PUB["public/<br/>(the only folder the web server exposes)"]
    PUB --> SRC
    SRC --> VEN
    SRC --> VAR

Your code lives in src/, templates/ and config/; var/ and vendor/ are generated; public/ is the only folder visitors can reach.

The folders one by one

bin/ holds console, the script you run as php bin/console .... It boots the same kernel as the web, so your commands can use every service of the application.

config/ is the configuration. config/packages/ has one file per installed package (framework.yaml, twig.yaml, doctrine.yaml...), config/routes.yaml tells Symfony where to find routes, config/services.yaml configures the container, and config/bundles.php lists enabled bundles. A subfolder named after an environment (for example config/packages/dev/) applies only in that environment.

public/ is the document root: the web server points here. It contains index.php and static files such as images and compiled assets. Nothing outside public/ can be requested by URL, which is why your source code and .env are safe.

src/ is your PHP code, in the App\ namespace. The PSR-4 rule is simple: src/Controller/HomeController.php holds the class App\Controller\HomeController. Kernel.php is the application kernel, and the rest is yours to organize. Typical subfolders are Controller, Entity, Repository, Form, Security and EventListener. Symfony does not force them: the container loads every class under src/ as a service (you will see how in Services and the Service Container).

templates/ contains Twig templates. base.html.twig is the layout the others extend.

tests/ holds PHPUnit tests, in the App\Tests\ namespace.

migrations/ stores Doctrine migrations, created by make:migration.

translations/ contains translation catalogues for multilingual sites.

var/ is written by the application at run time: var/cache/ (compiled container, routes, templates) and var/log/. It is safe to delete and is never committed to Git. Symfony needs to be able to write here.

vendor/ is created by Composer and holds every third-party package, including Symfony itself. Never edit files in it and never commit it.

The .env files

Configuration that changes between machines (database URLs, secrets, API keys) lives in environment variables. For convenience, Symfony reads them from files, in a fixed order:

File Committed? Purpose
.env Yes Defaults for every environment, safe values only
.env.local No Your machine's overrides and real secrets
.env.dev, .env.test, .env.prod Yes Defaults for one environment
.env.dev.local and similar No Your overrides for one environment

Later files override earlier ones, and a real environment variable (set by the server, Docker or the shell) beats every file. The .env.local file is skipped in the test environment, so your local settings cannot make tests unpredictable. On production servers it is common to avoid .env files entirely and set real variables, or to run composer dump-env prod once at deploy time to compile them into a PHP file. You will cover this in Environment Variables and Secrets.

This stand-in merges layers the same way. It is plain PHP, using strings instead of files so it is fully self-contained:

PHP Layering .env files (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

composer.json

composer.json declares what your project needs. A trimmed example:

JSON
{
    "type": "project",
    "require": {
        "php": ">=8.2",
        "symfony/framework-bundle": "7.4.*",
        "symfony/console": "7.4.*",
        "symfony/runtime": "7.4.*"
    },
    "autoload": {
        "psr-4": { "App\\": "src/" }
    },
    "extra": {
        "symfony": { "require": "7.4.*" }
    }
}

The important parts: require lists packages, autoload maps the App\ namespace to src/ so classes load without require statements, and extra.symfony.require pins every Symfony package to the same minor line, so Composer never mixes versions. Composer writes the exact versions it installed to composer.lock; commit it so every machine installs identical code.

The front controller

Every web request enters through one file, public/index.php:

PHP
<?php

use App\Kernel;

require_once dirname(__DIR__).'/vendor/autoload_runtime.php';

return function (array $context) {
    return new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
};

It is short on purpose. The Runtime component reads the environment (including the .env files) and calls your closure with a $context array. You return a kernel, and the runtime takes care of creating the Request, sending it through the kernel, and sending the Response back. The same pattern is used by bin/console, which returns a console application instead. Because every request goes through this single entry point, you can add behaviour (security, caching, logging) in one place instead of in every page script. The inside of the kernel is the topic of From Request to Response.

The next stand-in draws the project tree from a nested array, marking which folders you write and which are generated, a habit worth building when you explore a new codebase:

PHP Where do files belong? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which folder is the document root that the web server should expose?

    Only public/ is reachable by URL. Keeping src/, config/ and .env outside it protects your code and secrets.
  2. 2. Where are the compiled container and cache stored?

    var/ holds generated runtime files (cache and logs). It is safe to delete and is not committed.
  3. 3. Which value wins if DATABASE_URL is set in .env, in .env.local and as a real server environment variable?

    Real environment variables override every .env file, and .env.local overrides .env.
  4. 4. What does the autoload section with "App\\": "src/" in composer.json do?

    PSR-4 autoloading means App\Controller\HomeController is loaded from src/Controller/HomeController.php.

Summary

  • You write code in src/, templates/, config/ and tests/; Composer and Symfony generate vendor/ and var/.
  • public/ is the only folder the web server exposes, and public/index.php is the single front controller.
  • .env holds safe defaults, .env.local holds your private overrides, and real environment variables win.
  • composer.json declares dependencies and the PSR-4 mapping of App\ to src/; commit composer.lock.
  • bin/console and public/index.php both boot the same kernel through the Runtime component.

Next up: Flex, Recipes and Bundles.