@@ -337,48 +337,49 @@ time and again, you can have just one (or several) listeners deal with them.
337337 and takes measures like redirecting the user to the login page, logging them
338338 out and other things.
339339
340- Dumping error pages in static HTML files
340+ Dumping Error Pages as Static HTML Files
341341----------------------------------------
342342
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
347344
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.
350346
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.
352352
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:
354354
355- .. note ::
355+ .. code-block :: terminal
356356
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/
360359
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:
364366
365367.. code-block :: nginx
366368
367369 # /etc/nginx/conf.d/example.com.conf
368370 server {
369- # Your existing serverconfiguration
371+ # Existing server configuration
370372 # ...
371373
372-
373- # Configure nginx to serve your application's error pages
374+ # Serve static error pages
374375 error_page 400 /error_pages/400.html;
375376 error_page 401 /error_pages/401.html;
376377 # ...
377378 error_page 510 /error_pages/510.html;
378379 error_page 511 /error_pages/511.html;
379380
380381 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
383384 }
384385 }
0 commit comments