Movatterモバイル変換

[0]ホーム
URL:

Skip to content
Version:

Symfony CLI

 Edit this page

TheSymfony CLI is a free andopen source developer tool to help you build,run, and manage your Symfony applications directly from your terminal. It's designedto boost your productivity with smart features like:

  • Web server optimized for development, withHTTPS support
  • Docker integration and automatic environment variable management
  • Management of multiplePHP versions
  • Support for backgroundworkers
  • Seamless integration withSymfony Cloud

Installation

The Symfony CLI is available as a standalone executable that supports Linux,macOS, and Windows. Download and install it following the instructions onsymfony.com/download.

Shell Autocompletion

The Symfony CLI supports autocompletion for Bash, Zsh, and Fish shells. Thishelps you type commands faster and discover available options:

12345678
# install autocompletion (do this only once)$symfony completion bash | sudo tee /etc/bash_completion.d/symfony# for Zsh users$symfony completion zsh > ~/.symfony_completion &&echo"source ~/.symfony_completion" >> ~/.zshrc# for Fish users$symfony completion fish |source

After installation, restart your terminal to enable autocompletion. The CLI willalso provide autocompletion forcomposer andconsole commands when itdetects a Symfony project.

Creating New Symfony Applications

The Symfony CLI includes a project creation command that helps you start newprojects quickly:

12345678910111213141516171819
# create a new Symfony project based on the latest stable version$symfony new my_project# create a project with the latest LTS (Long Term Support) version$symfony new my_project --version=lts# create a project based on a specific Symfony version$symfony new my_project --version=6.4# create a project using the development version$symfony new my_project --version=next# all the previous commands create minimal projects with the least# amount of dependencies possible; if you are building a website or# web application, add this option to install all the common dependencies$symfony new my_project --webapp# Create a project based on the Symfony Demo application$symfony new my_project --demo

Tip

Pass the--cloud option to initialize a Symfony Cloud project at the sametime the Symfony project is created.

Running the Local Web Server

The Symfony CLI includes alocal web server designed for development. It'snot intended for production use, but it provides features that improve thedeveloper experience:

  • HTTPS support with automatic certificate generation
  • HTTP/2 support
  • Automatic PHP version selection
  • Integration with Docker services
  • Built-in proxy for custom domain names

Serving Your Application

To serve a Symfony project with the local server:

12345
$cd my-project/$symfony server:start  [OK] Web server listening on http://127.0.0.1:8000  ...

Now browse the given URL or run the following command to open it in the browser:

1
$symfony open:local

Tip

If you work on more than one project, you can run multiple instances of theSymfony server on your development machine. Each instance will find a differentavailable port.

Theserver:start command blocks the current terminal to output the serverlogs. To run the server in the background:

1
$symfony server:start -d

Now you can continue working in the terminal and run other commands:

12345
# view the latest log messages$symfony server:log# stop the background server$symfony server:stop

Tip

On macOS, when starting the Symfony server you might see a warning dialog asking"Do you want the application to accept incoming network connections?".This happens when running unsigned applications that are not listed in thefirewall list. The solution is to run this command to sign the Symfony CLI:

1
$sudo codesign --force --deep --sign - $(whereis -q symfony)

Enabling PHP-FPM

Note

PHP-FPM must be installed locally for the Symfony server to utilize.

When the server starts, it checks forweb/index_dev.php,web/index.php,public/app_dev.php,public/app.php,public/index.php in that order. If one is found, theserver will automatically start with PHP-FPM enabled. Otherwise the server willstart without PHP-FPM and will show aPage not found page when trying toaccess a.php file in the browser.

Tip

When anindex.html and a front controller (e.g.index.php) are bothpresent, the server will still start with PHP-FPM enabled, but theindex.html will take precedence. This means that if anindex.htmlfile is present inpublic/ orweb/, it will be displayed instead oftheindex.php, which would otherwise show, for example, the Symfonyapplication.

Enabling HTTPS/TLS

Running your application over HTTPS locally helps detect mixed content issuesearly and allows using features that require secure connections. Traditionally,this has been painful and complicated to set up, but the Symfony server automateseverything for you:

12345
# install the certificate authority (run this only once on your machine)$symfony server:ca:install# now start (or restart) your server; it will use HTTPS automatically$symfony server:start

Tip

For WSL (Windows Subsystem for Linux), the newly created local certificateauthority needs to be imported manually:

1
$explorer.exe `wslpath -w$HOME/.symfony5/certs`

In the file explorer window that just opened, double-click on the filecalleddefault.p12.

PHP Management

The Symfony CLI provides PHP management features, allowing you to use differentPHP versions and/or settings for different projects.

Selecting PHP Version

If you have multiple PHP versions installed on your computer, you can tellSymfony which one to use creating a file called.php-version at the projectroot directory:

1234567
$cd my-project/# use a specific PHP version$echo 8.2 > .php-version# use any PHP 8.x version available$echo 8 > .php-version

To see all available PHP versions:

1
$symfonylocal:php:list

Tip

You can create a.php-version file in a parent directory to set the samePHP version for multiple projects.

Custom PHP Configuration

Override PHP settings per project by creating aphp.ini file at the projectroot:

123456
; php.ini[Date]date.timezone = Asia/Tokyo[PHP]memory_limit =256M

Using PHP Commands

Usesymfony php to ensure commands run with the correct PHP version:

12345678
# runs with the system's default PHP$php -v# runs with the project's PHP version$symfony php -v# this also works for Composer$symfony composer install

Local Domain Names

By default, projects are accessible at a random port on the127.0.0.1local IP. However, sometimes it is preferable to associate a domain name(e.g.my-app.wip) with them:

  • it's more convenient when working continuously on the same project becauseport numbers can change but domains don't;
  • the behavior of some applications depends on their domains/subdomains;
  • to have stable endpoints, such as the local redirection URL for OAuth2.

Setting up the Local Proxy

The Symfony CLI includes a proxy that allows using custom local domains. Thefirst time you use it, you must configure it as follows:

  1. Open theproxy settings of your operating system:

  2. Set the following URL as the value of theAutomatic Proxy Configuration:

    http://127.0.0.1:7080/proxy.pac

Now run this command to start the proxy:

1
$symfony proxy:start

If the proxy doesn't work as explained in the following sections, check the following:

  • Some browsers (e.g. Chrome) require reapplying proxy settings (clicking onRe-apply settings button on thechrome://net-internals/#proxy page)or a full restart after starting the proxy. Otherwise, you'll see a"This webpage is not available" error (ERR_NAME_NOT_RESOLVED);
  • Some Operating Systems (e.g. macOS) don't apply proxy settings to local hostsand domains by default. You may need to remove*.local and/or otherIP addresses from that list.
  • Windowsrequires usinglocalhost instead of127.0.0.1 whenconfiguring the automatic proxy, otherwise you won't be able to accessyour local domain from your browser running in Windows.

Defining the Local Domain

By default, Symfony uses.wip (forWork in Progress) as the local TLD forcustom domains. You can define a local domain for your project as follows:

12
$cd my-project/$symfony proxy:domain:attach my-app

Your application is now available athttps://my-app.wip

Tip

View all local domains and their configuration athttp://127.0.0.1:7080

You can also use wildcards:

1
$symfony proxy:domain:attach"*.my-app"

This allows accessing subdomains likehttps://api.my-app.wip orhttps://admin.my-app.wip.

When running console commands, set thehttps_proxy environment variableto make custom domains work:

12345678
# example with cURL$https_proxy=$(symfony proxy:url) curl https://my-domain.wip# example with Blackfire and cURL$https_proxy=$(symfony proxy:url) blackfire curl https://my-domain.wip# example with Cypress$https_proxy=$(symfony proxy:url) ./node_modules/bin/cypress open

Warning

Although environment variable names are typically uppercase, thehttps_proxyvariableis treated differently and must be written in lowercase.

Tip

If you prefer to use a different TLD, edit the~/.symfony5/proxy.jsonfile (where~ means the path to your user directory) and change thevalue of thetld option fromwip to any other TLD.

Docker Integration

The Symfony CLI provides fullDocker integration for projects thatuse it. To learn more about Docker and Symfony, seeUsing Docker with Symfony.The local server automatically detects Docker services and exposes theirconnection information as environment variables.

Automatic Service Detection

With thiscompose.yaml:

1234
services:database:image:mysql:8ports:[3306]

The web server detects that a service exposing port3306 is running for theproject. It understands that this is a MySQL service and creates environmentvariables accordingly, using the service name (database) as a prefix:

  • DATABASE_URL
  • DATABASE_HOST
  • DATABASE_PORT

Here is a list of supported services with their ports and default Symfony prefixes:

ServicePortSymfony default prefix
MySQL3306DATABASE_
PostgreSQL5432DATABASE_
Redis6379REDIS_
Memcached11211MEMCACHED_
RabbitMQ5672RABBITMQ_ (set user and pass via DockerRABBITMQ_DEFAULT_USER andRABBITMQ_DEFAULT_PASS env var)
Elasticsearch9200ELASTICSEARCH_
MongoDB27017MONGODB_ (set the database via a DockerMONGO_DATABASE env var)
Kafka9092KAFKA_
MailCatcher1025/1080or 25/80MAILER_
Blackfire8707BLACKFIRE_
Mercure80Always exposesMERCURE_PUBLIC_URL andMERCURE_URL (only works with thedunglas/mercure Docker image)

If the service is not supported, generic environment variables are set:PORT,IP, andHOST.

You can open web management interfaces for the services that expose themby clicking on the links in the "Server" section of the web debug toolbaror by running these commands:

12
$ symfony open:local:webmail$ symfony open:local:rabbitmq

Tip

To debug and list all exported environment variables, run:symfony var:export --debug.

Tip

For some services, the local web server also exposes environment variablesunderstood by CLI tools related to the service. For instance, runningsymfony run psql will connect you automatically to the PostgreSQL serverrunning in a container without having to specify the username, password, ordatabase name.

When Docker services are running, browse a page of your Symfony application andcheck the "Symfony Server" section in the web debug toolbar. You'll see that"Docker Compose" is marked as "Up".

Note

If you don't want environment variables to be exposed for a service, setthecom.symfony.server.service-ignore label totrue:

123456
# compose.yamlservices:db:ports:[3306]labels:com.symfony.server.service-ignore:true

If your Docker Compose file is not at the root of the project, use theCOMPOSE_FILE andCOMPOSE_PROJECT_NAME environment variables to defineits location, same as fordocker-compose:

12345
# start your containers:COMPOSE_FILE=docker/compose.yaml COMPOSE_PROJECT_NAME=project_name docker-compose up -d# run any Symfony CLI command:COMPOSE_FILE=docker/compose.yaml COMPOSE_PROJECT_NAME=project_name symfony var:export

Note

If you have more than one Docker Compose file, you can provide them all,separated by:, as explained in theDocker Compose CLI env var reference.

Warning

When using the Symfony CLI withphp bin/console (symfony console ...),it willalways use environment variables detected via Docker, ignoringany local environment variables. For example, if you set up a different databasename in your.env.test file (DATABASE_URL=mysql://db_user:db_password@127.0.0.1:3306/test)and runsymfony console doctrine:database:drop --force --env=test,the command will drop the database defined in your Docker configuration and not the "test" one.

Warning

Similar to other web servers, this tool automatically exposes all environmentvariables available in the CLI context. Ensure that this local server is notaccessible on your local network without your explicit consent, to avoidpotential security issues.

Service Naming

If your service names don't match Symfony conventions, use labels:

123456
services:db:image:postgres:15ports:[5432]labels:com.symfony.server.service-prefix:'DATABASE'

In this example, the service is nameddb, so environment variables would beprefixed withDB_, but as thecom.symfony.server.service-prefix is settoDATABASE, the web server creates environment variables starting withDATABASE_ instead as expected by the default Symfony configuration.

Managing Long-Running Processes

Use therun command provided by the Symfony CLI to manage long-runningprocesses like Webpack watchers:

12345678910
# start webpack watcher in the background to not block the terminal$symfony run -d npx encore dev --watch# continue working and running other commands...# view logs$symfony server:log# check status$symfony server:status

Configuring Workers

Define processes that should start automatically with the server in.symfony.local.yaml:

12345678910111213141516
# .symfony.local.yamlworkers:# Built-in Encore integrationnpm_encore_watch:~# Messenger consumer with file watchingmessenger_consume_async:cmd:['symfony','console','messenger:consume','async']watch:['config','src','templates','vendor']# Custom commandsbuild_spa:cmd:['npm','run','watch']# Auto-start Docker Composedocker_compose:~

Advanced Configuration

The.symfony.local.yaml file provides advanced configuration options:

12345678910111213141516171819202122232425262728
# sets app.wip and admin.app.wip for the current projectproxy:domains:-app-admin.app# HTTP server settingshttp:document_root:public/passthru:index.php# forces the port that will be used to run the serverport:8000# sets the HTTP port you prefer for this project [default: 8000]# (only will be used if it's available; otherwise a random port is chosen)preferred_port:8001# used to disable the default auto-redirection from HTTP to HTTPSallow_http:true# force the use of HTTP instead of HTTPSno_tls:false# path to the file containing the TLS certificate to use in p12 formatp12:path/to/custom-cert.p12# toggle GZIP compressionuse_gzip:true# enable Cross-origin resource sharing (CORS) for all requestallow_cors:true# run the server in the backgrounddaemon:true

Warning

Setting domains in this configuration file will override any domains you setusing theproxy:domain:attach command for the current project when you startthe server.

Symfony Cloud Integration

The Symfony CLI provides seamless integration withSymfony Cloud (powered byPlatform.sh):

12345678
# open Platform.sh web UI$symfony cloud:web# deploy your project to production$symfony cloud:deploy# create a new environment$symfony cloud:env:create feature-xyz

For more features, see theSymfony Cloud documentation.

Troubleshooting

Server doesn't start: Check if the port is already in use:

12
$symfony server:status$symfony server:stop# If a server is already running

HTTPS not working: Ensure the CA is installed:

1
$symfony server:ca:install

Docker services not detected: Check that Docker is running and environmentvariables are properly exposed:

12
$docker compose ps$symfony var:export --debug

Proxy domains not working:

  • Clear your browser cache
  • Check proxy settings in your system
  • For Chrome, visitchrome://net-internals/#proxy and click "Re-apply settings"
This work, including the code samples, is licensed under aCreative Commons BY-SA 3.0 license.
TOC
    Version

    Symfony 7.3backers

    [8]ページ先頭
    ©2009-2025 Movatter.jp