Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 62 ยท Getting Started

Installing Symfony and the CLI

Install Symfony step by step: PHP requirements, Composer, the Symfony CLI, symfony new with skeleton or webapp, and the local development server.

Installing Symfony is mostly installing PHP and two command-line tools. After that, a single command creates a working project and another starts a local web server with HTTPS. This lesson shows the whole path on your own machine and explains the one choice you have to make at the start: a minimal skeleton project or a feature-rich webapp.

All the commands below run in a terminal on your computer, so they are shown as read-only blocks. The runnable examples on this page are stand-ins: a requirements checker and a generator that shows what each project template would create.

What you need

  • PHP at the version your Symfony release requires. Symfony 7.x needs PHP 8.2 or newer; Symfony 8 needs a newer PHP, so always check the release page for the exact figure. Run php -v to see what you have.
  • PHP extensions. The ones every project needs (ctype, iconv, mbstring, xml and a few others) are included in almost every PHP build. Doctrine adds a database extension such as pdo_mysql, pdo_pgsql or pdo_sqlite. The Symfony CLI can tell you what is missing.
  • Composer, the PHP package manager. Symfony is installed as Composer packages; see Composer if you have never used it.
  • The Symfony CLI (optional, but strongly recommended). It creates projects, runs the local server and checks requirements.
  • Git (optional) for version control. The CLI works with or without it.

You do not need Apache or nginx for development. The Symfony CLI includes a web server, and PHP itself can serve a project too.

Installing the Symfony CLI

The Symfony CLI is a single binary that you install once per machine. Use the installer for your system from the official download page (Homebrew on macOS, Scoop on Windows, a package or script on Linux). Afterwards, check that it works:

Terminal
symfony -V
symfony check:requirements

symfony check:requirements reads your PHP configuration and reports every missing extension or setting, with a hint on how to fix it. Run it before you blame Symfony for an odd error.

PHP A requirements checker (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.

Creating a project

You have two ways to start: with the Symfony CLI or with plain Composer. They create exactly the same files.

Terminal
# Symfony CLI: a minimal project (the default)
symfony new my_project

# Symfony CLI: a full website with Twig, Doctrine, Mailer and more
symfony new my_project --webapp

# Pin a version, for example the LTS line
symfony new my_project --version="7.4.*" --webapp

# The same with Composer only
composer create-project symfony/skeleton my_project
cd my_project
composer require webapp

Skeleton or webapp?

The skeleton is deliberately tiny. It contains the framework, the console, the runtime and Flex, and little else. It has no Twig, no database layer and no mailer, which makes it the right start for a microservice or a pure JSON API: you add exactly the packages you need.

The webapp starts from the same skeleton and then installs a bundle of packages (the webapp pack) that a traditional website needs: Twig for templates, Doctrine for the database, the Security component, forms, the Mailer, Messenger and the debugging tools. It is the best choice while you learn, because the later lessons use all of those parts.

flowchart LR
    S["symfony new my_project"] --> K["skeleton<br/>kernel, console, config"]
    S -- "--webapp" --> W["skeleton + webapp pack<br/>Twig, Doctrine, Security, Mailer, Forms"]
    K --> A["add packages later<br/>composer require ..."]
    W --> A

Both templates produce a normal project; the webapp simply starts with more packages installed.

The next example is a stand-in that models the two templates as lists of packages and shows the files a project would receive. The real command also creates a Git repository (unless you pass --no-git) and installs the packages with Composer, which this stand-in does not do.

PHP What does each template contain? (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.

Starting the local server

From the project folder, start the server:

Terminal
cd my_project
symfony server:start        # runs in the foreground, press Ctrl+C to stop
symfony server:start -d     # runs in the background
symfony server:stop
symfony open:local          # opens the site in your browser

The server picks a free port (usually 8000), serves public/ and prints the URL. The CLI can also create a local certificate authority so that https://127.0.0.1:8000 works without browser warnings:

Terminal
symfony server:ca:install

If you cannot or do not want to install the CLI, php -S 127.0.0.1:8000 -t public starts PHP's built-in server. It is fine for a first look, but it has no HTTPS and no clever routing for extra features. Use it for experiments only, never in production.

Two commands to remember

Once a project exists, you will use these constantly:

Terminal
php bin/console list      # every console command available in the project
php bin/console about     # Symfony version, PHP version, environment, debug mode

bin/console is the front door to the Console component. You will meet it in nearly every lesson, for example make:controller in Your First Page.

Common installation problems

  • "Your PHP version is too old." Composer refuses to install a Symfony release that needs a newer PHP. Install a newer PHP, or pick an older Symfony line with --version.
  • A missing extension. Run symfony check:requirements and enable the extension in php.ini. On Windows and Linux there is a different php.ini for the CLI and for the web server; check the one that Symfony uses.
  • Composer is slow or times out. Network problems are common on shared connections. Run composer diagnose, and try again with a different network or mirror.
  • The wrong PHP is on your PATH. If you have several PHP versions installed, php -v and the server may use different ones. The Symfony CLI can pin a version per project with a .php-version file.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command checks that your PHP configuration meets Symfony's needs?

    The Symfony CLI command reports missing extensions and settings. Composer only checks versions of the packages it installs.
  2. 2. What is the difference between the skeleton and the --webapp option?

    Both are the same framework. The webapp pack simply installs the packages a typical website needs.
  3. 3. Which project type is the better starting point for a small JSON-only microservice?

    The skeleton keeps dependencies small. You add the serializer, Doctrine or others when you need them.
  4. 4. Which command starts Symfony's local development server in the background?

    symfony server:start -d runs the server as a background process; symfony server:stop stops it.

Summary

  • You need a recent PHP, Composer and (optionally but recommended) the Symfony CLI.
  • symfony check:requirements tells you what is missing; php bin/console about shows what a project runs on.
  • symfony new my_project creates a minimal skeleton; add --webapp for Twig, Doctrine, Security, Mailer and more.
  • symfony server:start serves the project locally, with HTTPS after symfony server:ca:install.
  • The built-in PHP server works for quick experiments only.

Next up: Project Structure.