8000 Merge branch '4.2' · symfony/symfony-docs@cd5c7eb · GitHub
[go: up one dir, main page]
Skip to content

Commit cd5c7eb

Browse files
javiereguiluzjaviereguiluz
committed
Merge branch '4.2'
* 4.2: Documented the local Symfony server
2 parents 4ad5103 + d1aec31 commit cd5c7eb

File tree

1 file changed

+299
-0
lines changed

1 file changed

+299
-0
lines changed

‎setup/symfony_server.rst

Lines changed: 299 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,299 @@
1+
Symfony Local Web Server
2+
========================
3+
4+
You can run Symfony applications with any web server (Apache, nginx, the
5+
internal PHP web server, etc.). However, Symfony provides its own web server to
6+
make you more productive while developing your applications.
7+
8+
Although this server is not intended for production use, it supports HTTP/2,
9+
TLS/SSL, automatic generation of security certificates, local domains, and many
10+
other features that sooner or later you'll need when developing web projects.
11+
Moreover, the server is not tied to Symfony and you can also use it with any
12+
PHP application and even with HTML/SPA (single page applications).
13+
14+
Installation
15+
------------
16+
17+
The Symfony server is distributed as a free installable binary without any
18+
dependency and support for Linux, macOS and Windows. Go to `symfony.com/download`_
19+
and follow the instructions for your operating system.
20+
21+
Getting Started
22+
---------------
23+
24+
The Symfony server is started once per project, so you may end up with several
25+
instances (each of them listening to a different port). This is the common
26+
workflow to serve a Symfony project:
27+
28+
.. code-block:: terminal
29+
30+
$ cd my-project/
31+
$ symfony server:start
32+
33+
[OK] Web server listening on http://127.0.0.1:....
34+
...
35+
36+
# Now, browse the given URL, or run this command:
37+
$ symfony open:local
38+
39+
Running the server this way makes it display the log messages in the console, so
40+
you won't be able to run other commands at the same time. If you prefer, you can
41+
run the Symfony server in the background:
42+
43+
.. code-block:: terminal
44+
45+
$ cd my-project/
46+
47+
# start the server in the background
48+
$ symfony server:start -d
49+
50+
# continue working and running other commands...
51+
52+
# show the latest log messages
53+
$ symfony server:log
54+
55+
Enabling TLS
56+
------------
57+
58+
Browsing the secure version of your apps locally is important to detect
59+
problems with mixed content early, and to run libraries that only run in HTTPS.
60+
Traditionally this has been painful and complicated to set up, but the Symfony
61+
server automates everything. First, run this command:
62+
63+
.. code-block:: terminal
64+
65+
$ symfony server:ca:install
66+
67+
This command creates a local certificate authority, registers it in your system
68+
trust store, registers it in Firefox (this is required only for that browser)
69+
and creates a default certificate for ``localhost`` and ``127.0.0.1``. In other
70+
words, it does everything for you.
71+
72+
Before browsing your local application with HTTPS instead of HTTP, restart its
73+
server stopping and starting it again.
74+
75+
Different PHP Settings Per Project
76+
----------------------------------
77+
78+
Selecting a Different PHP Version
79+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80+
81+
If you have multiple PHP versions installed on your computer, you can tell
82+
Symfony which one to use creating a file called ``.php-version`` at the project
83+
root directory:
84+
85+
.. code-block:: terminal
86+
87+
$ cd my-project/
88+
89+
# use a specific PHP version
90+
$ echo "7.2" > .php-version
91+
92+
# use any PHP 7.x version available
93+
$ echo "7" > .php-version
94+
95+
.. tip::
96+
97+
The Symfony server traverses the directory structure up to the root
98+
directory, so you can create a ``.php-version`` file in some parent
99+
directory to set the same PHP version for a group of projects under that
100+
directory.
101+
102+
Run command if you don't remember all the PHP versions installed on your
103+
computer:
104+
105+
.. code-block:: terminal
106+
107+
$ symfony local:php:list
108+
109+
# You'll see all supported SAPIs (CGI, FastCGI, etc.) for each version.
110+
# FastCGI (php-fpm) is used when possible; then CGI (which acts as a FastCGI
111+
# server as well), and finally, the server falls back to plain CGI.
112+
113+
Overriding PHP Config Options Per Project
114+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115+
116+
You can change the value of any PHP runtime config option per project by creating a
117+
file called ``php.ini`` at the project root directory. Add only the options you want
118+
to override:
119+
120+
.. code-block:: terminal
121+
122+
$ cd my-project/
123+
124+
# this project only overrides the default PHP timezone
125+
$ cat php.ini
126+
[Date]
127+
date.timezone = Asia/Tokyo
128+
129+
Running Commands with Different PHP Versions
130+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
131+
132+
When running different PHP versions it's useful to use the main ``symfony``
133+
command as a wrapper for the ``php`` command. This allows you to always select
134+
the most appropriate PHP version according to the project which is running the
135+
commands. It also loads the env vars automatically, which is important when
136+
running non-Symfony commands:
137+
138+
.. code-block:: terminal
139+
140+
# runs the command with the default PHP version
141+
$ php -r "..."
142+
143+
# runs the command with the PHP version selected by the project
144+
# (or the default PHP version if the project didn't select one)
145+
$ symfony php -r "..."
146+
147+
If you are using this wrapper frequently, consider aliasing the ``php`` command
148+
to it:
149+
150+
.. code-block:: terminal
151+
152+
$ cd ~/.symfony/bin
153+
$ cp symfony php
154+
# now you can run "php ..." and the "symfony" command will be executed instead
155+
156+
# other PHP commands can be wrapped too using this trick
157+
$ cp symfony php-config
158+
$ cp symfony pear
159+
$ cp symfony pecl
160+
161+
Local Domain Names
162+
------------------
163+
164+
By default, projects are accessible at some random port of the ``127.0.0.1``
165+
local IP. However, sometimes it is preferable to associate a domain name to them:
166+
167+
* It's more convenient when you work continuously on the same project because
168+
port numbers can change but domains don't;
169+
* The behavior of some applications depend on their domains/subdomains;
170+
* To have stable endpoints, such as the local redirection URL for Oauth2.
171+
172+
Setting up the Local Proxy
173+
~~~~~~~~~~~~~~~~~~~~~~~~~~
174+
175+
Local domains are possible thanks to a local proxy provided by the Symfony
176+
server. First, start the proxy:
177+
178+
.. code-block:: terminal
179+
180+
$ symfony proxy:start
181+
182+
If this is the first time you run the proxy, you must follow these additional steps:
183+
184+
* Open the **network configuration** of your operating system;
10BC0 185+
* Find the **proxy settings** and select the **"Automatic Proxy Configuration"**;
186+
* Set the following URL as its value: ``https://127.0.0.1:7080/proxy.pac``
187+
188+
Defining the Local Domain
189+
~~~~~~~~~~~~~~~~~~~~~~~~~
190+
191+
By default, Symfony proposes ``.wip`` (for *Work in Progress*) for the local
192+
domains. You can define a local domain for your project as follows:
193+
194+
.. code-block:: terminal
195+
196+
$ cd my-project/
197+
$ symfony proxy:domain:attach my-domain
198+
199+
If you have installed the local proxy as explained in the previous section, you
200+
can now browse ``https://my-domain.wip`` to access your local project with the
201+
new custom domain.
202+
203+
.. tip::
204+
205+
Browse the https://127.0.0.1:7080 URL to get the full list of local project
206+
directories, their custom domains, and port numbers.
207+
208+
When running console commands, add the ``HTTPS_PROXY`` env var to make custom
209+
domains work:
210+
211+
.. code-block:: terminal
212+
213+
$ HTTPS_PROXY=https://127.0.0.1:7080 curl https://my-domain.wip
214+
215+
.. tip::
216+
217+
If you prefer to use a different TLD, edit the ``~/.symfony/proxy.json``
218+
file (where ``~`` means the path to your user directory) and change the
219+
value of the ``tld`` option from ``wip`` to any other TLD.
220+
221+
Long-Running Commands
222+
---------------------
223+
224+
Long-running commands, such as the ones that compile front-end web assets, block
225+
the terminal and you can't run other commands at the same time. The Symfony
226+
server provides a ``run`` command to wrap them as follows:
227+
228+
.. code-block:: terminal
229+
230+
# compile Webpack assets using Symfony Encore ... but do that in the
231+
# background to not block the terminal
232+
$ symfony run -d yarn encore dev --watch
233+
234+
# continue working and running other commands...
235+
236+
# from time to time, check the command logs if you want
237+
$ symfony server:log
238+
239+
# and you can also check if the command is still running
240+
$ symfony server:status
241+
Web server listening on ...
242+
Command "yarn ..." running with PID ...
243+
244+
# stop the web server (and all the associated commands) when you are finished
245+
$ symfony server:stop
246+
247+
Bonus Features
248+
--------------
249+
250+
In addition to being a local web server, the Symfony server provides other
251+
useful features:
252+
253+
Looking for Security Vulnerabilities
254+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
255+
256+
Instead of installing the :doc:`Symfony Security Checker </security/security_checker>`
257+
as a dependency of your projects, you can run the following command:
258+
259+
.. code-block 10000 :: terminal
260+
261+
$ symfony security:check
262+
263+
This command uses the same vulnerability database as the Symfony Security
264+
Checker but it does not make HTTP calls to the official API endpoint. Everything
265+
(except cloning the public database) is done locally, which is the best for CI
266+
(*continuous integration*) scenarios.
267+
268+
Creating Symfony Projects
269+
~~~~~~~~~~~~~~~~~~~~~~~~~
270+
271+
In addition to the `different ways of installing Symfony`_, you can use these
272+
commands from the Symfony server:
273+
274+
.. code-block:: terminal
275+
276+
# creates a new project based on symfony/skeleton
277+
$ symfony new my_project_name
278+
279+
# creates a new project based on symfony/website-skeleton
280+
$ symfony new --full my_project_name
281+
282+
# creates a new project based on the Symfony Demo application
283+
$ symfony new --demo my_project_name
284+
285+
SymfonyCloud Integration
286+
------------------------
287+
288+
The local Symfony server provides full, but optional, integration with
289+
`SymfonyCloud`_, a service optimized to run your Symfony applications on the
290+
cloud. It provides features such as creating environments, backups/snapshots,
291+
and even access to a copy of the production data from your local machine to help
292+
debug any issues.
293+
294+
`Read SymfonyCloud technical docs`_.
295+
296+
.. _`symfony.com/download`: https://symfony.com/download
297+
.. _`different ways of installing Symfony`: https://symfony.com/download
298+
.. _`SymfonyCloud`: https://symfony.com/cloud/
299+
.. _`Read SymfonyCloud technical docs`: https://symfony.com/doc/master/cloud/intro.html

0 commit comments

Comments
 (0)
0