📚 Document OPcache with symlinks

lorisleiva · lorisleiva · commit 90e21ef904dd · 2018-03-13T15:11:22.000+01:00
diff --git a/docs/first-deploy.md b/docs/first-deploy.md
@@ -20,7 +20,12 @@ Start by deploying using `php artisan deploy`. Unless you have some folders call
 ## 2️⃣ Point root path to current directory
 Make sure your server's root path points to the `current` symlink. For example if your `deploy_path` is `var/www/domain.com`, your server configurations should point to `var/www/domain.com/current`.
 
-Because the `current` directory is a symlink, you need to allow symlinks on nginx by adding `disable_symlinks off;` to your server block.
+If you're using OPcache, you need to pass the realpath of the application instead of its symbolic link. Otherwise, PHP's OPcache may not properly detect changes to your PHP files. Add the following lines after the rest of your `fastcgi` configurations in the `location` block of your nginx configurations.
+
+```nginx
+fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
+fastcgi_param DOCUMENT_ROOT $realpath_root;
+```
 
 Are you using Laravel Forge? [You can do this directly from the web interface](how-to-forge.md#update-web-directory).
 
diff --git a/docs/how-to-forge.md b/docs/how-to-forge.md
@@ -27,18 +27,21 @@ localhost()
 * Combine with the `-a` (`--all`) option to skip any console interaction whilst using a maximum of features — npm, migrations, horizon, etc.
 
 ## Update web directory
-
 Go to the *Meta* tab of your application page on Forge and change it to the `/current/public` directory.
 
 ![Enter `/current/public` on Meta > Update Web Directory](https://user-images.githubusercontent.com/3642397/37337948-320f3ea0-26b6-11e8-902f-f4b185c609c7.png)
 
-## Allow symlinks on nginx
+## Make OPcache work with symlinks
+Next, you need to pass the real application path instead of the symlink path to PHP FPM. Otherwise, PHP's OPcache may not properly detect changes to your PHP files. Add the following lines after the rest of your `fastcgi` configurations in the `location` block of your nginx configurations.
 
-Because the `current` directory is a symlink, you need to allow symlinks on nginx by adding `disable_symlinks off;` to your server block.
+```nginx
+fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
+fastcgi_param DOCUMENT_ROOT $realpath_root;
+```
 
 ![Edit your nginx configuration file](https://user-images.githubusercontent.com/3642397/37338252-30323c08-26b7-11e8-85d5-db49d5c4abbe.png)
 
-![Add `disable_symlinks off;` to your server block](https://user-images.githubusercontent.com/3642397/37338263-41bb0144-26b7-11e8-9234-fc980198060f.png)
+![Add more fastcgi configs to your location block](https://user-images.githubusercontent.com/3642397/37346220-11785cb2-26cf-11e8-906e-30da2bfbe847.png)
 
 ## Edit your deploy script
 Your deploy script in Forge is now unnecessary since your whole deployment logic is define by Laravel Deployer. Replace it with the following script to deploy using Laravel Deployer when you deloy in Forge.
@@ -52,4 +55,4 @@ Now if you have *Quick Deploy* turned on, every time you push to your repository
 
 ## Extra things to configure
 * If you wish to reload php-fpm after each deployment like Forge does by default, you will need to use the `fpm:reload` task and set up your version of php-fpm within the `php_fpm_service` option. Read more [here](how-to-reload-fpm.md).
-* If you have a Daemon running Horizon in Forge, [read this](how-to-horizon.md) to make sure it restarts after each deployment.
+* If you have a Daemon running Horizon in Forge, [read this](how-to-horizon.md) to make sure it restarts after each deployment.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -17,18 +17,24 @@ Since Deployer uses `acl` by default to set up permissions for writable director
 sudo apt-get install acl
 ```
 
-## My changes don't show after a deployment.
+## My changes don't show up after a deployment.
 
 **Problem:**
 
 You push some new commits and run `php artisan deploy` successfully but the changes don't seem to appear on your application.
 
 **Solution:**
 
-It is likely that your server configurations do not allow symlinks. Since the `current` folder is a symlink, it will not see it as linked to the newest release. To allow symlinks in your nginx configuration, add `disable_symlinks off;` to your server block.
-
+Since we are using symlinks to link the `current` folder to the current release of your application, it is likely that OPcache does not properly detect changes to your PHP files. To fix this, you should pass the real application path instead of the path to the symlink to PHP FPM. Add the following lines after the rest of your `fastcgi` configuration in the `location` block of your nginx configurations.
 
+```nginx
+fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
+fastcgi_param DOCUMENT_ROOT $realpath_root;
 ```
+
+If this doesn't fix the problem, make sure that your nginx configurations allow symbolic links by adding `disable_symlinks off;` to your server block.
+
+```nginx
 server {
     # ...
     disable_symlinks off;
