From 01161e984187e837db72a63bc5b3781d8853e6d3 Mon Sep 17 00:00:00 2001 From: Oskar Stark Date: Tue, 1 Jul 2025 11:24:50 +0200 Subject: [PATCH] Rename and refocus Symfony Local Web Server docs to Symfony CLI - Rename `symfony_server.rst` to `symfony_cli.rst` - Refocus documentation on the Symfony CLI as a comprehensive tool - Add new sections for project creation and PHP management - Reorganize content with better structure and flow - Update all references throughout the documentation - Add redirect from old URL to maintain backward compatibility - Improve troubleshooting section - Keep all existing anchors for backward compatibility --- _build/redirection_map | 1 + configuration/micro_kernel_trait.rst | 4 +- console.rst | 2 +- contributing/code/reproducer.rst | 2 +- create_framework/front_controller.rst | 2 +- create_framework/introduction.rst | 2 +- frontend/encore/dev-server.rst | 2 +- mailer.rst | 2 +- mercure.rst | 2 +- page_creation.rst | 2 +- quick_tour/the_big_picture.rst | 2 +- setup.rst | 2 +- setup/symfony_cli.rst | 431 ++++++++++++++++++++ setup/symfony_server.rst | 563 -------------------------- setup/web_server_configuration.rst | 2 +- 15 files changed, 445 insertions(+), 576 deletions(-) create mode 100644 setup/symfony_cli.rst delete mode 100644 setup/symfony_server.rst diff --git a/_build/redirection_map b/_build/redirection_map index 896c58a3022..184ec11aa1f 100644 --- a/_build/redirection_map +++ b/_build/redirection_map @@ -435,6 +435,7 @@ /setup/composer /setup /security/security_checker /setup /setup/built_in_web_server /setup/symfony_server +/setup/symfony_server /setup/symfony_cli /service_container/parameters /configuration /routing/generate_url_javascript /routing /routing/slash_in_parameter /routing diff --git a/configuration/micro_kernel_trait.rst b/configuration/micro_kernel_trait.rst index 20b6544181c..71a4a94e596 100644 --- a/configuration/micro_kernel_trait.rst +++ b/configuration/micro_kernel_trait.rst @@ -131,7 +131,7 @@ Next, create an ``index.php`` file that defines the kernel class and runs it: options inside the ``configureContainer()`` method). That's it! To test it, start the :doc:`Symfony Local Web Server -`: +`: .. code-block:: terminal @@ -470,7 +470,7 @@ this: └─ composer.lock As before you can use the :doc:`Symfony Local Web Server -`: +`: .. code-block:: terminal diff --git a/console.rst b/console.rst index 82bafd4d640..a3e1abbf34b 100644 --- a/console.rst +++ b/console.rst @@ -109,7 +109,7 @@ completion (by default, by pressing the Tab key). .. tip:: If you are using the :doc:`Symfony local web server - `, it is recommended to use the built-in completion + `, it is recommended to use the built-in completion script that will ensure the right PHP version and configuration are used when running the Console Completion. Run ``symfony completion --help`` for the installation instructions for your shell. The Symfony CLI will provide diff --git a/contributing/code/reproducer.rst b/contributing/code/reproducer.rst index 3392ca87035..914ab2fd3f2 100644 --- a/contributing/code/reproducer.rst +++ b/contributing/code/reproducer.rst @@ -65,7 +65,7 @@ to a route definition. Then, after creating your project: of controllers, actions, etc. as in your original application. #. Create a small controller and add your routing definition that shows the bug. #. Don't create or modify any other file. -#. Install the :doc:`local web server ` provided by Symfony +#. Install the :doc:`local web server ` provided by Symfony and use the ``symfony server:start`` command to browse to the new route and see if the bug appears or not. #. If you can see the bug, you're done and you can already share the code with us. diff --git a/create_framework/front_controller.rst b/create_framework/front_controller.rst index fded71a7b1c..f2843b9067a 100644 --- a/create_framework/front_controller.rst +++ b/create_framework/front_controller.rst @@ -154,7 +154,7 @@ Now, configure your web server root directory to point to ``web/`` and all other files will no longer be accessible from the client. To test your changes in a browser (``http://localhost:4321/hello?name=Fabien``), -run the :doc:`Symfony Local Web Server `: +run the :doc:`Symfony Local Web Server `: .. code-block:: terminal diff --git a/create_framework/introduction.rst b/create_framework/introduction.rst index 7a1e6b2ad50..d65bb4fe85e 100644 --- a/create_framework/introduction.rst +++ b/create_framework/introduction.rst @@ -101,7 +101,7 @@ start with the simplest web application we can think of in PHP:: printf('Hello %s', $name); -You can use the :doc:`Symfony Local Web Server ` to test +You can use the :doc:`Symfony Local Web Server ` to test this great application in a browser (``http://localhost:8000/index.php?name=Fabien``): diff --git a/frontend/encore/dev-server.rst b/frontend/encore/dev-server.rst index 01501178caf..c3287a7bc2f 100644 --- a/frontend/encore/dev-server.rst +++ b/frontend/encore/dev-server.rst @@ -53,7 +53,7 @@ method in your ``webpack.config.js`` file: Enabling HTTPS using the Symfony Web Server ------------------------------------------- -If you're using the :doc:`Symfony web server ` locally with HTTPS, +If you're using the :doc:`Symfony web server ` locally with HTTPS, you'll need to also tell the dev-server to use HTTPS. To do this, you can reuse the Symfony web server SSL certificate: diff --git a/mailer.rst b/mailer.rst index 5ba85056d27..30e50fbd359 100644 --- a/mailer.rst +++ b/mailer.rst @@ -1825,7 +1825,7 @@ Enabling an Email Catcher When developing locally, it is recommended to use an email catcher. If you have enabled Docker support via Symfony recipes, an email catcher is automatically configured. In addition, if you are using the :doc:`Symfony local web server -`, the mailer DSN is automatically exposed via the +`, the mailer DSN is automatically exposed via the :ref:`symfony binary Docker integration `. Sending Test Emails diff --git a/mercure.rst b/mercure.rst index ed89fe034f7..fd32d01c01f 100644 --- a/mercure.rst +++ b/mercure.rst @@ -72,7 +72,7 @@ Thanks to :doc:`the Docker integration of Symfony `, :ref:`Flex ` proposes to install a Mercure hub for development. Run ``docker-compose up`` to start the hub if you have chosen this option. -If you use the :doc:`Symfony Local Web Server `, +If you use the :doc:`Symfony Local Web Server `, you must start it with the ``--no-tls`` option to prevent mixed content and invalid TLS certificate issues: diff --git a/page_creation.rst b/page_creation.rst index 8ab89baa9f6..ce7a2b1a935 100644 --- a/page_creation.rst +++ b/page_creation.rst @@ -80,7 +80,7 @@ metadata to code): } } -That's it! If you are using :doc:`the Symfony web server `, +That's it! If you are using :doc:`the Symfony web server `, try it out by going to: http://localhost:8000/lucky/number .. tip:: diff --git a/quick_tour/the_big_picture.rst b/quick_tour/the_big_picture.rst index b069cb4f716..997bb05904e 100644 --- a/quick_tour/the_big_picture.rst +++ b/quick_tour/the_big_picture.rst @@ -42,7 +42,7 @@ Symfony application: Can we already load the project in a browser? Yes! You can set up :doc:`Nginx or Apache ` and configure their document root to be the ``public/`` directory. But, for development, it's better -to :doc:`install the Symfony local web server ` and run +to :doc:`install the Symfony local web server ` and run it as follows: .. code-block:: terminal diff --git a/setup.rst b/setup.rst index 889df729466..b2b184114d0 100644 --- a/setup.rst +++ b/setup.rst @@ -121,7 +121,7 @@ development. .. _symfony-binary-web-server: However for local development, the most convenient way of running Symfony is by -using the :doc:`local web server ` provided by the +using the :doc:`local web server ` provided by the ``symfony`` binary. This local server provides among other things support for HTTP/2, concurrent requests, TLS/SSL and automatic generation of security certificates. diff --git a/setup/symfony_cli.rst b/setup/symfony_cli.rst new file mode 100644 index 00000000000..6bd6e047341 --- /dev/null +++ b/setup/symfony_cli.rst @@ -0,0 +1,431 @@ +.. _symfony-server: +.. _symfony-local-web-server: + +Symfony CLI +=========== + +The Symfony CLI is a developer tool to help you build, run, and manage your +Symfony applications directly from your terminal. It's designed to boost your +productivity with smart features like: + +* Local web server optimized for development +* Seamless integration with Platform.sh services +* Docker support with automatic environment variable management +* Multiple PHP version management +* Background worker management +* And much more! + +Installation +------------ + +The Symfony CLI is available as a standalone executable that supports Linux, +macOS, and Windows. + +Download and install it following the instructions on `symfony.com/download`_. + +Shell Autocompletion +~~~~~~~~~~~~~~~~~~~~ + +The Symfony CLI supports autocompletion for Bash, Zsh, and Fish shells. This +helps you type commands faster and discover available options: + +.. code-block:: terminal + + # 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 will +also provide autocompletion for ``composer`` and ``console`` commands when it +detects a Symfony project. + +.. note:: + + You can view and contribute to the Symfony CLI source in the + `symfony-cli/symfony-cli GitHub repository`_. + +Creating New Symfony Applications +--------------------------------- + +The Symfony CLI includes a powerful project creation command that helps you +start new projects quickly: + +.. code-block:: terminal + + # Create a new Symfony project (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 + + # Create a minimal project (microkernel) + $ symfony new my_project --version=6.4 + + # Create a demo application + $ symfony new my_project --demo + +.. tip:: + + Pass the ``--cloud`` option to initialize a Platform.sh project at the same + time the Symfony project is created. Pass the ``--webapp`` option if you + prefer a project where Twig is already configured. + +Running the Local Web Server +---------------------------- + +The Symfony CLI includes a powerful local web server for development. This +server is not intended for production use but provides features that make +development more productive: + +* HTTPS support with automatic certificate generation +* HTTP/2 support +* Automatic PHP version selection +* Integration with Docker services +* Built-in proxy for custom domain names + +Getting Started +~~~~~~~~~~~~~~~ + +To serve a Symfony project with the local server: + +.. code-block:: terminal + + $ cd my-project/ + $ symfony server:start + + [OK] Web server listening on http://127.0.0.1:8000 + ... + + # Browse the site using your default browser + $ symfony open:local + +Running the server this way displays log messages in the console. To run it in +the background: + +.. code-block:: terminal + + $ symfony server:start -d + + # Continue working and running other commands... + + # View the latest log messages + $ symfony server:log + + # Stop the background server + $ symfony server:stop + +.. tip:: + + On macOS, you might see a warning about accepting incoming network + connections. To fix this, sign the Symfony binary: + + .. code-block:: terminal + + $ sudo codesign --force --deep --sign - $(whereis -q symfony) + +Enabling HTTPS/TLS +~~~~~~~~~~~~~~~~~~ + +Running your application over HTTPS locally helps detect mixed content issues +early and allows using features that require secure connections: + +.. code-block:: terminal + + # Install the certificate authority (only once) + $ symfony server:ca:install + + # Now start your server - it will use HTTPS automatically + $ symfony server:start + +.. tip:: + + For WSL (Windows Subsystem for Linux) users, manually import the certificate + authority in Windows: + + .. code-block:: terminal + + $ explorer.exe `wslpath -w $HOME/.symfony5/certs` + + Then double-click on ``default.p12`` to import it. + +PHP Management +-------------- + +The Symfony CLI provides powerful PHP management features, allowing you to use +different PHP versions for different projects. + +Selecting PHP Version +~~~~~~~~~~~~~~~~~~~~~ + +Create a ``.php-version`` file at your project root: + +.. code-block:: terminal + + $ 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: + +.. code-block:: terminal + + $ symfony local:php:list + +.. tip:: + + You can create a ``.php-version`` file in a parent directory to set the same + PHP version for multiple projects. + +Custom PHP Configuration +~~~~~~~~~~~~~~~~~~~~~~~~ + +Override PHP settings per project by creating a ``php.ini`` file at the project +root: + +.. code-block:: ini + + ; php.ini + [Date] + date.timezone = Europe/Paris + + [PHP] + memory_limit = 256M + +Using PHP Commands +~~~~~~~~~~~~~~~~~~ + +Use ``symfony php`` to ensure commands run with the correct PHP version: + +.. code-block:: terminal + + # 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 +------------------ + +Instead of using ``127.0.0.1:8000``, you can use custom domain names like +``https://my-app.wip``. + +Setting up the Local Proxy +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Configure your system to use the Symfony proxy: + + * Open your system's proxy settings + * Set ``http://127.0.0.1:7080/proxy.pac`` as the automatic proxy configuration URL + +2. Start the proxy: + + .. code-block:: terminal + + $ symfony proxy:start + +3. Attach a domain to your project: + + .. code-block:: terminal + + $ cd my-project/ + $ symfony proxy:domain:attach my-app + + Your application is now available at ``https://my-app.wip`` + +.. tip:: + + View all local domains and their configuration at http://127.0.0.1:7080 + +You can also use wildcards: + +.. code-block:: terminal + + $ symfony proxy:domain:attach "*.my-app" + +This allows accessing subdomains like ``https://api.my-app.wip`` or +``https://admin.my-app.wip``. + +.. _symfony-server-docker: + +Docker Integration +------------------ + +The local server automatically detects Docker services and exposes their +connection information as environment variables. + +Automatic Service Detection +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +With this ``compose.yaml``: + +.. code-block:: yaml + + services: + database: + image: mysql:8 + ports: [3306] + +The server automatically creates these environment variables: + +* ``DATABASE_URL`` +* ``DATABASE_HOST`` +* ``DATABASE_PORT`` + +Supported services include MySQL, PostgreSQL, Redis, RabbitMQ, Elasticsearch, +MongoDB, and more. + +.. tip:: + + Run ``symfony var:export`` to see all exposed environment variables. + +Service Naming +~~~~~~~~~~~~~~ + +If your service names don't match Symfony conventions, use labels: + +.. code-block:: yaml + + services: + db: + image: postgres:15 + ports: [5432] + labels: + com.symfony.server.service-prefix: 'DATABASE' + +Managing Long-Running Processes +------------------------------- + +Use the Symfony CLI to manage long-running processes like Webpack watchers: + +.. code-block:: terminal + + # Start webpack watcher in the background + $ symfony run -d npx encore dev --watch + + # View logs + $ symfony server:log + + # Check status + $ symfony server:status + +.. _symfony-server_configuring-workers: + +Configuring Workers +~~~~~~~~~~~~~~~~~~~ + +Define processes that should start automatically with the server in +``.symfony.local.yaml``: + +.. code-block:: yaml + + # .symfony.local.yaml + workers: + # Built-in Encore integration + npm_encore_watch: ~ + + # Messenger consumer with file watching + messenger_consume_async: + cmd: ['symfony', 'console', 'messenger:consume', 'async'] + watch: ['config', 'src', 'templates', 'vendor'] + + # Custom commands + build_spa: + cmd: ['npm', 'run', 'watch'] + + # Auto-start Docker Compose + docker_compose: ~ + +Advanced Configuration +---------------------- + +The ``.symfony.local.yaml`` file provides advanced configuration options: + +.. code-block:: yaml + + # Custom domains + proxy: + domains: + - app + - admin.app + + # HTTP server settings + http: + document_root: public/ + passthru: index.php + port: 8000 + preferred_port: 8001 + allow_http: false + no_tls: false + p12: path/to/custom-cert.p12 + +Platform.sh Integration +----------------------- + +The Symfony CLI provides seamless integration with `Platform.sh`_: + +.. code-block:: terminal + + # Open Platform.sh web UI + $ symfony cloud:web + + # Deploy to Platform.sh + $ symfony cloud:deploy + + # Create a new environment + $ symfony cloud:env:create feature-xyz + +For more Platform.sh features, see the `Platform.sh documentation`_. + +Troubleshooting +--------------- + +**Server doesn't start**: Check if the port is already in use: + +.. code-block:: terminal + + $ symfony server:status + $ symfony server:stop # If a server is already running + +**HTTPS not working**: Ensure the CA is installed: + +.. code-block:: terminal + + $ symfony server:ca:install + +**Docker services not detected**: Check that Docker is running and environment +variables are properly exposed: + +.. code-block:: terminal + + $ docker compose ps + $ symfony var:export --debug + +**Proxy domains not working**: + +* Clear your browser cache +* Check proxy settings in your system +* For Chrome, visit ``chrome://net-internals/#proxy`` and click "Re-apply settings" + +.. _`symfony.com/download`: https://symfony.com/download +.. _`symfony-cli/symfony-cli GitHub repository`: https://github.com/symfony-cli/symfony-cli +.. _`Platform.sh`: https://symfony.com/cloud/ +.. _`Platform.sh documentation`: https://docs.platform.sh/frameworks/symfony.html \ No newline at end of file diff --git a/setup/symfony_server.rst b/setup/symfony_server.rst deleted file mode 100644 index 2ea4da543fe..00000000000 --- a/setup/symfony_server.rst +++ /dev/null @@ -1,563 +0,0 @@ -Symfony Local Web Server -======================== - -You can run Symfony applications with any web server (Apache, nginx, the -internal PHP web server, etc.). However, Symfony provides its own web server to -make you more productive while developing your applications. - -Although this server is not intended for production use, it supports HTTP/2, -TLS/SSL, automatic generation of security certificates, local domains, and many -other features that sooner or later you'll need when developing web projects. -Moreover, the server is not tied to Symfony and you can also use it with any -PHP application and even with HTML or single page applications. - -Installation ------------- - -The Symfony server is part of the ``symfony`` binary created when you -`install Symfony`_ and has support for Linux, macOS and Windows. - -.. tip:: - - The Symfony CLI supports auto completion for Bash, Zsh, or Fish shells. You - have to install the completion script *once*. Run ``symfony completion - --help`` for the installation instructions for your shell. After installing - and restarting your terminal, you're all set to use completion (by default, - by pressing the Tab key). - - The Symfony CLI will also provide completion for the ``composer`` command - and for the ``console`` command if it detects a Symfony project. - -.. note:: - - You can view and contribute to the Symfony CLI source in the - `symfony-cli/symfony-cli GitHub repository`_. - -Getting Started ---------------- - -The Symfony server is started once per project, so you may end up with several -instances (each of them listening to a different port). This is the common -workflow to serve a Symfony project: - -.. code-block:: terminal - - $ cd my-project/ - $ symfony server:start - - [OK] Web server listening on http://127.0.0.1:.... - ... - - # Now, browse the given URL, or run this command: - $ symfony open:local - -Running the server this way makes it display the log messages in the console, so -you won't be able to run other commands at the same time. If you prefer, you can -run the Symfony server in the background: - -.. code-block:: terminal - - $ cd my-project/ - - # start the server in the background - $ symfony server:start -d - - # continue working and running other commands... - - # show the latest log messages - $ symfony server:log - -.. 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 the - firewall list. The solution is to run this command that signs the Symfony binary: - - .. code-block:: terminal - - $ 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 for ``web/index_dev.php``, ``web/index.php``, -``public/app_dev.php``, ``public/app.php`` in that order. If one is found, the -server will automatically start with PHP-FPM enabled. Otherwise the server will -start without PHP-FPM and will show a ``Page not found`` page when trying to -access a ``.php`` file in the browser. - -.. tip:: - - When an ``index.html`` and a front controller like e.g. ``index.php`` are - both present the server will still start with PHP-FPM enabled but the - ``index.html`` will take precedence over the front controller. This means - when an ``index.html`` file is present in ``public`` or ``web``, it will be - displayed instead of the ``index.php`` which would show e.g. the Symfony - application. - -Enabling TLS ------------- - -Browsing the secure version of your applications locally is important to detect -problems with mixed content early, and to run libraries that only run in HTTPS. -Traditionally this has been painful and complicated to set up, but the Symfony -server automates everything. First, run this command: - -.. code-block:: terminal - - $ symfony server:ca:install - -This command creates a local certificate authority, registers it in your system -trust store, registers it in Firefox (this is required only for that browser) -and creates a default certificate for ``localhost`` and ``127.0.0.1``. In other -words, it does everything for you. - -.. tip:: - - If you are doing this in WSL (Windows Subsystem for Linux), the newly created - local certificate authority needs to be manually imported in Windows. The file - is located in ``wsl`` at ``~/.symfony5/certs/default.p12``. The easiest way to - do so is to run the following command from ``wsl``: - - .. code-block:: terminal - - $ explorer.exe `wslpath -w $HOME/.symfony5/certs` - - In the file explorer window that just opened, double-click on the file - called ``default.p12``. - -Before browsing your local application with HTTPS instead of HTTP, restart its -server stopping and starting it again. - -Different PHP Settings Per Project ----------------------------------- - -Selecting a Different PHP Version -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you have multiple PHP versions installed on your computer, you can tell -Symfony which one to use creating a file called ``.php-version`` at the project -root directory: - -.. code-block:: terminal - - $ cd my-project/ - - # use a specific PHP version - $ echo 7.4 > .php-version - - # use any PHP 8.x version available - $ echo 8 > .php-version - -.. tip:: - - The Symfony server traverses the directory structure up to the root - directory, so you can create a ``.php-version`` file in some parent - directory to set the same PHP version for a group of projects under that - directory. - -Run the command below if you don't remember all the PHP versions installed on your -computer: - -.. code-block:: terminal - - $ symfony local:php:list - - # You'll see all supported SAPIs (CGI, FastCGI, etc.) for each version. - # FastCGI (php-fpm) is used when possible; then CGI (which acts as a FastCGI - # server as well), and finally, the server falls back to plain CGI. - -Overriding PHP Config Options Per Project -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can change the value of any PHP runtime config option per project by creating a -file called ``php.ini`` at the project root directory. Add only the options you want -to override: - -.. code-block:: terminal - - $ cd my-project/ - - # this project only overrides the default PHP timezone - $ cat php.ini - [Date] - date.timezone = Asia/Tokyo - -Running Commands with Different PHP Versions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When running different PHP versions, it is useful to use the main ``symfony`` -command as a wrapper for the ``php`` command. This allows you to always select -the most appropriate PHP version according to the project which is running the -commands. It also loads the env vars automatically, which is important when -running non-Symfony commands: - -.. code-block:: terminal - - # runs the command with the default PHP version - $ php -r "..." - - # runs the command with the PHP version selected by the project - # (or the default PHP version if the project didn't select one) - $ symfony php -r "..." - -Local Domain Names ------------------- - -By default, projects are accessible at some random port of the ``127.0.0.1`` -local IP. However, sometimes it is preferable to associate a domain name to them: - -* It's more convenient when you work continuously on the same project because - port numbers can change but domains don't; -* The behavior of some applications depend on their domains/subdomains; -* To have stable endpoints, such as the local redirection URL for OAuth2. - -Setting up the Local Proxy -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Local domains are possible thanks to a local proxy provided by the Symfony server. -If this is the first time you run the proxy, you must configure it as follows: - -#. Open the **proxy settings** of your operating system: - - * `Proxy settings in Windows`_; - * `Proxy settings in macOS`_; - * `Proxy settings in Ubuntu`_. - -#. Set the following URL as the value of the **Automatic Proxy Configuration**: - - ``http://127.0.0.1:7080/proxy.pac`` - -Now run this command to start the proxy: - -.. code-block:: terminal - - $ symfony proxy:start - -If the proxy doesn't work as explained in the following sections, check these: - -* Some browsers (e.g. Chrome) require to re-apply proxy settings (clicking on - ``Re-apply settings`` button on the ``chrome://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 by default the proxy settings - to local hosts and domains. You may need to remove ``*.local`` and/or other - IP addresses from that list. -* Windows Operating System **requires** ``localhost`` instead of ``127.0.0.1`` - when configuring the automatic proxy, otherwise you won't be able to access - your local domain from your browser running in Windows. - -Defining the Local Domain -~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, Symfony proposes ``.wip`` (for *Work in Progress*) for the local -domains. You can define a local domain for your project as follows: - -.. code-block:: terminal - - $ cd my-project/ - $ symfony proxy:domain:attach my-domain - -If you have installed the local proxy as explained in the previous section, you -can now browse ``https://my-domain.wip`` to access your local project with the -new custom domain. - -.. tip:: - - Browse the http://127.0.0.1:7080 URL to get the full list of local project - directories, their custom domains, and port numbers. - -You can also add a wildcard domain: - -.. code-block:: terminal - - $ symfony proxy:domain:attach "*.my-domain" - -So it will match all subdomains like ``https://admin.my-domain.wip``, ``https://other.my-domain.wip``... - -When running console commands, add the ``https_proxy`` env var to make custom -domains work: - -.. code-block:: terminal - - # 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 env var names are always defined in uppercase, the ``https_proxy`` - env var `is treated differently`_ than other env vars and its name must be - spelled in lowercase. - -.. tip:: - - If you prefer to use a different TLD, edit the ``~/.symfony5/proxy.json`` - file (where ``~`` means the path to your user directory) and change the - value of the ``tld`` option from ``wip`` to any other TLD. - -Long-Running Commands ---------------------- - -Long-running commands, such as the ones that compile front-end web assets, block -the terminal and you can't run other commands at the same time. The Symfony -server provides a ``run`` command to wrap them as follows: - -.. code-block:: terminal - - # compile Webpack assets using Symfony Encore ... but do that in the - # background to not block the terminal - $ symfony run -d npx encore dev --watch - - # continue working and running other commands... - - # from time to time, check the command logs if you want - $ symfony server:log - - # and you can also check if the command is still running - $ symfony server:status - Web server listening on ... - Command "npx ..." running with PID ... - - # stop the web server (and all the associated commands) when you are finished - $ symfony server:stop - -Configuration file ------------------- - -There are several options that you can set using a ``.symfony.local.yaml`` config file: - -.. code-block:: yaml - - # Sets domain1.wip and domain2.wip for the current project - proxy: - domains: - - domain1 - - domain2 - - http: - document_root: public/ # Path to the project document root - passthru: index.php # Project passthru index - port: 8000 # Force the port that will be used to run the server - preferred_port: 8001 # Preferred HTTP port [default: 8000] - p12: path/to/p12_cert # Name of the file containing the TLS certificate to use in p12 format - allow_http: true # Prevent auto-redirection from HTTP to HTTPS - no_tls: true # Use HTTP instead of HTTPS - daemon: true # Run the server in the background - use_gzip: true # Toggle GZIP compression - no_workers: true # Do not start workers - -.. warning:: - - Setting domains in this configuration file will override any domains you set - using the ``proxy:domain:attach`` command for the current project when you start - the server. - -.. _symfony-server_configuring-workers: - -Configuring Workers -~~~~~~~~~~~~~~~~~~~ - -If you like some processes to start automatically, along with the webserver -(``symfony server:start``), you can set them in the YAML configuration file: - -.. code-block:: yaml - - # .symfony.local.yaml - workers: - # built-in command that builds and watches front-end assets - # npm_encore_watch: - # cmd: ['npx', 'encore', 'dev', '--watch'] - npm_encore_watch: ~ - - # built-in command that starts messenger consumer - # messenger_consume_async: - # cmd: ['symfony', 'console', 'messenger:consume', 'async'] - # watch: ['config', 'src', 'templates', 'vendor'] - messenger_consume_async: ~ - - # you can also add your own custom commands - build_spa: - cmd: ['npm', '--cwd', './spa/', 'dev'] - - # auto start Docker compose when starting server (available since Symfony CLI 5.7.0) - docker_compose: ~ - -.. tip:: - - You may want to not start workers on some environments like CI. You can use the - ``--no-workers`` option to start the server without starting workers. - -.. _symfony-server-docker: - -Docker Integration ------------------- - -The local Symfony server provides full `Docker`_ integration for projects that -use it. To learn more about Docker & Symfony, see :doc:`docker`. - -When the web server detects that Docker Compose is running for the project, it -automatically exposes some environment variables. - -Via the ``docker-compose`` API, it looks for exposed ports used for common -services. When it detects one it knows about, it uses the service name to -expose environment variables. - -Consider the following configuration: - -.. code-block:: yaml - - # compose.yaml - services: - database: - ports: [3306] - -The web server detects that a service exposing port ``3306`` is running for the -project. It understands that this is a MySQL service and creates environment -variables accordingly with the service name (``database``) as a prefix: -``DATABASE_URL``, ``DATABASE_HOST``, ... - -If the service is not in the supported list below, generic environment -variables are set: ``PORT``, ``IP``, and ``HOST``. - -If the ``compose.yaml`` names do not match Symfony's conventions, add a -label to override the environment variables prefix: - -.. code-block:: yaml - - # compose.yaml - services: - db: - ports: [3306] - labels: - com.symfony.server.service-prefix: 'DATABASE' - -In this example, the service is named ``db``, so environment variables would be -prefixed with ``DB_``, but as the ``com.symfony.server.service-prefix`` is set -to ``DATABASE``, the web server creates environment variables starting with -``DATABASE_`` instead as expected by the default Symfony configuration. - -Here is the list of supported services with their ports and default Symfony -prefixes: - -============= ========= ====================== -Service Port Symfony default prefix -============= ========= ====================== -MySQL 3306 ``DATABASE_`` -PostgreSQL 5432 ``DATABASE_`` -Redis 6379 ``REDIS_`` -Memcached 11211 ``MEMCACHED_`` -RabbitMQ 5672 ``RABBITMQ_`` (set user and pass via Docker ``RABBITMQ_DEFAULT_USER`` and ``RABBITMQ_DEFAULT_PASS`` env var) -Elasticsearch 9200 ``ELASTICSEARCH_`` -MongoDB 27017 ``MONGODB_`` (set the database via a Docker ``MONGO_DATABASE`` env var) -Kafka 9092 ``KAFKA_`` -MailCatcher 1025/1080 ``MAILER_`` - or 25/80 -Blackfire 8707 ``BLACKFIRE_`` -Mercure 80 Always exposes ``MERCURE_PUBLIC_URL`` and ``MERCURE_URL`` (only works with the ``dunglas/mercure`` Docker image) -============= ========= ====================== - -You can open web management interfaces for the services that expose them: - -.. code-block:: bash - - $ symfony open:local:webmail - $ symfony open:local:rabbitmq - -Or click on the links in the "Server" section of the web debug toolbar. - -.. tip:: - - To debug and list all exported environment variables, run ``symfony - var:export --debug``. - -.. tip:: - - For some services, the web server also exposes environment variables - understood by CLI tools related to the service. For instance, running - ``symfony run psql`` will connect you automatically to the PostgreSQL server - running in a container without having to specify the username, password, or - database name. - -When Docker services are running, browse a page of your Symfony application and -check the "Symfony Server" section in the web debug toolbar; you'll see that -"Docker Compose" is "Up". - -.. note:: - - If you don't want environment variables to be exposed for a service, set - the ``com.symfony.server.service-ignore`` label to ``true``: - - .. code-block:: yaml - - # compose.yaml - services: - db: - ports: [3306] - labels: - com.symfony.server.service-ignore: true - -If your Docker Compose file is not at the root of the project, use the -``COMPOSE_FILE`` and ``COMPOSE_PROJECT_NAME`` environment variables to define -its location, same as for ``docker-compose``: - -.. code-block:: bash - - # 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 the `Docker compose CLI env var reference`_. - -.. warning:: - - When using the Symfony binary with ``php bin/console`` (``symfony console ...``), - the binary will **always** use environment variables detected via Docker and will - ignore local environment variables. - For example if you set up a different database name in your ``.env.test`` file - (``DATABASE_URL=mysql://db_user:db_password@127.0.0.1:3306/test``) and if you run - ``symfony 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 environment - variables available in the CLI context. Ensure that this local server is not - accessible on your local network without consent to avoid security issues. - -Platform.sh Integration ------------------------ - -The local Symfony server provides full, but optional, integration with -`Platform.sh`_, a service optimized to run your Symfony applications on the -cloud. It provides features such as creating environments, backups/snapshots, -and even access to a copy of the production data from your local machine to -help debug any issues. - -`Read Platform.sh for Symfony technical docs`_. - -.. _`install Symfony`: https://symfony.com/download -.. _`symfony-cli/symfony-cli GitHub repository`: https://github.com/symfony-cli/symfony-cli -.. _`Docker`: https://en.wikipedia.org/wiki/Docker_(software) -.. _`Platform.sh`: https://symfony.com/cloud/ -.. _`Read Platform.sh for Symfony technical docs`: https://symfony.com/doc/current/cloud/index.html -.. _`Proxy settings in Windows`: https://www.dummies.com/computers/operating-systems/windows-10/how-to-set-up-a-proxy-in-windows-10/ -.. _`Proxy settings in macOS`: https://support.apple.com/guide/mac-help/enter-proxy-server-settings-on-mac-mchlp2591/mac -.. _`Proxy settings in Ubuntu`: https://help.ubuntu.com/stable/ubuntu-help/net-proxy.html.en -.. _`is treated differently`: https://superuser.com/a/1799209 -.. _`Docker compose CLI env var reference`: https://docs.docker.com/compose/reference/envvars/ diff --git a/setup/web_server_configuration.rst b/setup/web_server_configuration.rst index 43bd79c10dd..b202adc2443 100644 --- a/setup/web_server_configuration.rst +++ b/setup/web_server_configuration.rst @@ -2,7 +2,7 @@ Configuring a Web Server ======================== The preferred way to develop your Symfony application is to use -:doc:`Symfony Local Web Server `. +:doc:`Symfony Local Web Server `. However, when running the application in the production environment, you'll need to use a fully-featured web server. This article describes how to use Symfony