diff --git a/docs/best-practices/deployment.md b/docs/best-practices/deployment.md index 04d03f8..60495be 100644 --- a/docs/best-practices/deployment.md +++ b/docs/best-practices/deployment.md @@ -15,22 +15,96 @@ This means that if you've already used PHP before, X will *just work*. * Any other web server using FastCGI to talk to PHP-FPM * Linux, Mac and Windows operating systems (LAMP, MAMP, WAMP) -*We've got you covered.* +*We've got you covered!* -For example, if you've followed the [quickstart guide](../getting-started/quickstart.md), you can run this using PHP's built-in development web -server for testing purposes like this: +### PHP development web server + +For example, if you've followed the [quickstart guide](../getting-started/quickstart.md), +you can run this using PHP's built-in development web server for testing +purposes like this: ```bash $ php -S 0.0.0.0:8080 public/index.php ``` -In order to check your web application responds as expected, you can use your favorite webbrowser or command line tool: +In order to check your web application responds as expected, you can use your +favorite web browser or command-line tool: ```bash $ curl http://localhost:8080/ Hello wörld! ``` +### Apache + +The Apache HTTP server (httpd) is one of the most popular web servers. In +particular, it is a very common choice for hosts that run multiple web +applications (such as shared hosting providers) due to its ease of use and +support for dynamic configuration through `.htaccess` files. + +X supports Apache out of the box. If you've used Apache before to run any PHP +application, using Apache with X is as simple as dropping the project files in +the right directory. Accordingly, this guide assumes you want to process a +number of [dynamic routes](../api/app.md#routing) through X and optionally +include some public assets (such as style sheets and images). + +Assuming you've followed the [quickstart guide](../getting-started/quickstart.md), +all you need to do is to point the Apache's [`DocumentRoot`](http://httpd.apache.org/docs/2.4/de/mod/core.html#documentroot) +("docroot") to the `public/` directory of your project. On top of this, you'll need +to instruct Apache to rewrite dynamic requests so they will be processed by X. +Inside your `public/` directory, create an `.htaccess` file (note the leading `.` which +makes this a hidden file) with the following contents: + +``` +# public/.htaccess +RewriteEngine On + +RewriteCond %{REQUEST_FILENAME} !-d +RewriteCond %{REQUEST_FILENAME} !-f +RewriteRule .* index.php +``` + +> ℹ️ **New to mod_rewrite?** +> +> We recommend using the above `.htaccess` file as a starting point if you're +> unsure. In this basic form, it instructs Apache to rewrite any requests for +> files that do not exist to your `public/index.php` which then processes any +> requests by checking your [registered routes](../api/app.md#routing). This +> requires the [`mod_rewrite`](https://httpd.apache.org/docs/2.4/mod/mod_rewrite.html) +> Apache module, which should be enabled by default on most platforms. On Ubuntu- +> or Debian-based systems, you may enable it like this: +> +> ```bash +> $ sudo a2enmod rewrite +> ``` + +Once done, your project directory should now look like this: + +``` +acme/ +├── public/ +│ ├── .htaccess +│ └── index.php +├── vendor/ +├── composer.json +└── composer.lock +``` + +If you're not already running an Apache server, you can run your X project with +Apache in a temporary Docker container like this: + +```bash +$ docker run -it --rm -p 80:80 -v "$PWD":/srv php:8.0-apache sh -c "rmdir /var/www/html;ln -s /srv/public /var/www/html;ln -s /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled; apache2-foreground" +``` + +In order to check your web application responds as expected, you can use your +favorite web browser or command-line tool: + +```bash +$ curl http://localhost/ +Hello wörld! +``` + ## Built-in web server But there's more!