feat: allow nginx 500 error page to be disabled (#34)

Closes #31 

This PR introduces a new cli command for controlling the visibility of
**all** Valet's custom nginx error pages (**both 404 and 500**), updates
nginx configuration handling to respect this setting, and enable the
error pages by default. Additionally, it includes minor improvements to
configuration management and code quality.

**Nginx error page configurability:**

* Added a new `nginx_error_page` configuration key (default `'on'`) to
control whether Valet's nginx error page is enabled. This key will now
be included for new configs, and for existing configs, it will
automatically be added if it's missing via the Upgrader processes.

* Updated Valet's main nginx config stub, and add logic to use the
`nginx_error_page` setting in the `Nginx::installServer` method,
allowing dynamic enabling or disabling of Valet's error pages.

* Added a new `valet nginx-error-page` CLI command to display or update
the visibility of the nginx error pages, including automatic nginx
reload when changed.

**Configuration and Upgrader:**

* Extracted the "missing default config keys" code from
`writeBaseConfiguration` into a new `addMissingDefaultConfigKeys`
Configuration method for better maintainability and to enable it's usage
in the Upgrader.

* Added new `addMissingConfigKeys` Upgrader method to call the
`addMissingDefaultConfigKeys` Configuration method during upgrades to
add any missing default config keys to existing installations.

Author: yCodeTech

README.md

@@ -138,6 +138,16 @@ composer global require ycodetech/valet-windows
     <td></td>
 		<td align="center"><a href="#parity">parity</a></td>
   </tr>
+  
+  <tr>
+  <th></th>
+    <td></td>
+    <td></td>
+    <td></td>
+		<td></td>
+    <td></td>
+		<td align="center"><a href="#nginx-error-page">nginx-error-page</a></td>
+  </tr>
 </table>
 
 ## Introduction
@@ -1421,6 +1431,23 @@ Parity at 87% out of a total 92% possible parity with the Laravel Valet (macOS)
 
 This command is a way to determine how much parity has been achieved.
 
+##### nginx-error-page
+
+```
+nginx-error-page               Display the current visibility of the nginx error page.
+                 [visibility]  Optionally, set to "on" to enable Valet's nginx error page, or "off" to disable it.
+```
+
+```console
+$ valet nginx-error-page
+Valet's nginx error pages are on.
+
+$ valet nginx-error-page off
+Valet's nginx error pages are now off.
+```
+
+The nginx error pages are `on` (enabled) by default, which means that Valet's custom nginx 404/500 error pages will be shown when an error is encountered. However, for those who prefer to use a framework's error reporting exception pages like that of Symfony or Laravel, Valet's nginx error pages can be turned `off` (disabled).
+
 ---
 
 ### Notes for all `--options`

cli/Valet/Configuration.php

@@ -149,18 +149,31 @@ public function createXdebugDirectory() {
 	 * Write the base, initial configuration for Valet.
 	 */
 	public function writeBaseConfiguration() {
+		// If the configuration file doesn't exist, create it with the base configuration.
 		if (!$this->files->exists($this->path())) {
 			$baseConfig = [
 				'tld' => 'test',
 				'paths' => [$this->valetHomePath('Sites')],
 				'php_port' => PhpCgi::PORT,
 				'php_xdebug_port' => PhpCgiXdebug::PORT,
-				'share-tool' => 'ngrok'
+				'share-tool' => 'ngrok',
+				'nginx_error_page' => 'on'
 			];
 
 			$this->write($baseConfig);
 		}
 
+		// If the configuration file exists, ensure it has all the necessary keys.
+		$this->addMissingDefaultConfigKeys();
+	}
+
+	/**
+	 * Add any missing necessary default configuration keys.
+	 *
+	 * It will not overwrite any existing configuration values,
+	 * only add missing keys with default values.
+	 */
+	public function addMissingDefaultConfigKeys() {
 		$config = $this->read();
 
 		// Add default_php if missing or is null.
@@ -176,6 +189,8 @@ public function writeBaseConfiguration() {
 		$this->updateKey('php_xdebug_port', $config['php_xdebug_port'] ?? PhpCgiXdebug::PORT);
 		// Add share-tool if missing.
 		$this->updateKey('share-tool', $config['share-tool'] ?? 'ngrok');
+		// Add nginx_error_page if missing.
+		$this->updateKey('nginx_error_page', $config['nginx_error_page'] ?? 'on');
 	}
 
 	/**

cli/Valet/Nginx.php

@@ -88,11 +88,14 @@ public function installServer() {
 
 		$valetErrorTemplatePath = $this->files->realpath(valetBinPath() . '../cli/templates');
 
+		// Check if nginx error pages are disabled
+		$interceptErrors = $this->configuration->get('nginx_error_page');
+
 		$this->files->putAsUser(
 			$this->path('valet/valet.conf'),
 			str_replace(
-				['VALET_HOME_PATH', 'VALET_SERVER_PATH', 'VALET_STATIC_PREFIX', 'HOME_PATH', 'VALET_PHP_PORT', 'VALET_ERROR_TEMPLATE_PATH'],
-				[Valet::homePath(), VALET_SERVER_PATH, VALET_STATIC_PREFIX, $_SERVER['HOME'], $defaultPhp['port'], $valetErrorTemplatePath],
+				['VALET_HOME_PATH', 'VALET_SERVER_PATH', 'VALET_STATIC_PREFIX', 'HOME_PATH', 'VALET_PHP_PORT', 'VALET_ERROR_TEMPLATE_PATH', 'VALET_INTERCEPT_ERRORS'],
+				[Valet::homePath(), VALET_SERVER_PATH, VALET_STATIC_PREFIX, $_SERVER['HOME'], $defaultPhp['port'], $valetErrorTemplatePath, $interceptErrors],
 				$this->files->getStub('valet.conf')
 			)
 		);

cli/Valet/Site.php

@@ -309,7 +309,7 @@ public function getPhpVersion($site, $symlink = false) {
 	}
 
 	/**
-	 * Extract PHP version of exising nginx config.
+	 * Extract PHP version of existing nginx config.
 	 *
 	 * @param string $url
 	 *
@@ -1201,4 +1201,4 @@ public function certificatesPath($url = null, $extension = null) {
 	public function caPath($caFile = null) {
 		return $this->valetHomePath() . '/CA' . ($caFile ? '/' . $caFile : '');
 	}
-}
+}

cli/Valet/Upgrader.php

@@ -43,6 +43,7 @@ public function onEveryRun() {
 			$this->upgradeDeprecatedNginxConfigDirectives();
 			$this->fixOldSampleValetDriver();
 			$this->upgradeNginxSitePhpPortOverrides();
+			$this->addMissingConfigKeys();
 		}
 	}
 
@@ -320,4 +321,11 @@ private function migrateSymlinksUpgradeKey() {
 		// Remove the legacy upgrade key to clean up the config.
 		$this->config->removeKey($legacyUpgradeKey);
 	}
+
+	/**
+	 * Add any missing necessary default configuration keys.
+	 */
+	public function addMissingConfigKeys() {
+		$this->config->addMissingDefaultConfigKeys();
+	}
 }

cli/stubs/valet.conf

@@ -45,7 +45,7 @@ server {
         fastcgi_param HOME "HOME_PATH";
         fastcgi_param PATH_INFO $fastcgi_path_info;
 
-        fastcgi_intercept_errors on;
+        fastcgi_intercept_errors VALET_INTERCEPT_ERRORS;
     }
 
     location ~ /\.ht {

cli/valet.php

@@ -404,6 +404,52 @@
 	info('Use <bg=magenta> start </> <bg=magenta> stop </> or <bg=magenta> restart </> commands to change the status, eg. <bg=magenta> valet restart nginx </>');
 })->descriptions('List the installed Valet services.');
 
+/**
+ * Display the current visibility of the nginx error pages, or optionally
+ * update its visibility to enable or disable them.
+ *
+ * Valet's nginx error pages are shown when a site has internal server or PHP errors.
+ * They are enabled by default, but can be disabled to allow any 3rd party error
+ * reporting tools to show instead.
+ *
+ * @param string $visibility Optionally, set to `on` to enable Valet's nginx error pages, or `off` to disable them. Default is `on`.
+ */
+$app->command('nginx-error-page [visibility]', function ($visibility = null) {
+	$key = 'nginx_error_page';
+	$current = Configuration::get($key);
+
+	// If no visibility argument was passed, output the current status of the nginx error pages.
+	if ($visibility == null) {
+		return info("Valet's nginx error pages are $current.");
+	}
+
+	// If the visibility argument is valid...
+	if (in_array($visibility, ['on', 'off'])) {
+		// If the visibility is the same as the current value, output a message and return early.
+		// This avoids unnecessary nginx config rewrites when the user tries to set the visibility
+		// to its current value.
+		if ($visibility === $current) {
+			return info("Valet's nginx error pages are already $visibility.");
+		}
+
+		// Update the configuration value for the nginx error page visibility.
+		Configuration::updateKey($key, $visibility);
+
+		// Re-install nginx server config and restart nginx to apply the change.
+		Nginx::installServer();
+		Nginx::restart();
+
+		return info("Valet's nginx error pages are now $visibility.");
+	}
+	// If the visibility argument is invalid, output an error message.
+	else {
+		return warning("Invalid visibility. Please set to either 'on' or 'off'.");
+	}
+
+})->descriptions("Display the current visibility of Valet's nginx error pages, or optionally update its visibility to enable or disable them.", [
+	'visibility' => "<fg=green>[on = default]</> will show Valet's nginx error pages \n <fg=green>[off]</> will disable them."
+]);
+
 /**
  * Most commands are available only if Valet is installed.
  */
@@ -1482,4 +1528,4 @@
 /**
  * Run the application.
  */
-$app->run();
+$app->run();

phpcs.xml

@@ -13,6 +13,7 @@
 	<exclude-pattern>web/app/plugins</exclude-pattern>
 	<exclude-pattern>web/app/mu-plugins</exclude-pattern>
 	<exclude-pattern>vendor/</exclude-pattern>
+	<exclude-pattern>node_modules/</exclude-pattern>
 	<exclude-pattern>web/app/uploads/</exclude-pattern>
 
 	<!-- Show colors in console -->