@@ -337,48 +337,49 @@ time and again, you can have just one (or several) listeners deal with them.
337
337
and takes measures like redirecting the user to the login page, logging them
338
338
out and other things.
339
339
340
- Dumping error pages in static HTML files
340
+ Dumping Error Pages as Static HTML Files
341
341
----------------------------------------
342
342
343
- When a web server cannot handle a request or when it triggers an error without
344
- calling the PHP application, it will return its default error pages, instead of
345
- rendering the errors as defined in your application (whether it's Symfony's
346
- default "Oops" error page or the pages you customized in your application).
343
+ .. versionadded :: 7.3
347
344
348
- To avoid that and always have your web server rendering your application's error
349
- pages, you can dump each HTTP status error in a their own static HTML files:
345
+ The feature to dump error pages into static HTML files was introduced in Symfony 7.3.
350
346
351
- .. code-block :: terminal
347
+ If an error occurs before reaching your Symfony application, web servers display
348
+ their own default error pages instead of your custom ones. Dumping your application's
349
+ error pages to static HTML ensures users always see your defined pages and improves
350
+ performance by allowing the server to deliver errors instantly without calling
351
+ your application.
352
352
353
- $ php bin/console error:dump [--force] var/cache/prod/error_pages
353
+ Symfony provides the following command to turn your error pages into static HTML files:
354
354
355
- .. note ::
355
+ .. code-block :: terminal
356
356
357
- By default, it will dump HTML files for each HTTP status error.
358
- You can restrict that to dump only some HTTP status code by passing them as
359
- in the second argument of the command.
357
+ # the first argument is the path where the HTML files are stored
358
+ $ APP_ENV=prod php bin/console error:dump var/cache/prod/error_pages/
360
359
361
- Once the static pages are generated, you can now configure your web server to use
362
- them instead of their default error page. Here is an example configuration with
363
- nginx:
360
+ # by default, it generates the pages of all 4xx and 5xx errors, but you can
361
+ # pass a list of HTTP status codes to only generate those
362
+ $ APP_ENV=prod php bin/console error:dump var/cache/prod/error_pages/ 401 403 404 500
363
+
364
+ You must also configure your web server to use these generated pages. For example,
365
+ if you use Nginx:
364
366
365
367
.. code-block :: nginx
366
368
367
369
# /etc/nginx/conf.d/example.com.conf
368
370
server {
369
- # Your existing serverconfiguration
371
+ # Existing server configuration
370
372
# ...
371
373
372
-
373
- # Configure nginx to serve your application's error pages
374
+ # Serve static error pages
374
375
error_page 400 /error_pages/400.html;
375
376
error_page 401 /error_pages/401.html;
376
377
# ...
377
378
error_page 510 /error_pages/510.html;
378
379
error_page 511 /error_pages/511.html;
379
380
380
381
location ^~ /error_pages/ {
381
- root /path/to/your/symfony/var/cache/error_pages;
382
- internal; # allows this location block to not be triggered when a user manually call these /error_pages/.* urls
382
+ root /path/to/your/symfony/var/cache/error_pages;
383
+ internal; # prevent direct URL access
383
384
}
384
385
}
0 commit comments