refactor: restructure upgrade keys (#37)

This pull request refactors how upgrade state is tracked in the
configuration, consolidating upgrade keys under a single `upgrades`
array and improving configuration key management. The changes also add
helper methods for manipulating nested configuration keys using
Laravel's array helpers.

Configuration management improvements:

* Added `removeKey` method in `Configuration.php` to remove nested
configuration values using Laravel's `Arr::forget` helper, allowing for
dot notation.

* Changed `updateKey` method in `Configuration.php` to use Laravel's
`Arr::set` helper, allowing for dot notation and more flexible
configuration updates.

Upgrade state tracking refactor:

* Consolidated upgrade keys (such as `symlinks_upgraded` and
`php_port_overrides_upgraded`) under a new `upgrades` array in the
configuration, with new names `symlinks` and
`nginx_site_php_port_overrides`.

* Added new helper methods `isUpgraded` and `markAsUpgraded` to access
the new `upgrades` config format and improve upgrade tracking
consistency.

* Added a migration method (`migrateSymlinksUpgradeKey`) to move the
legacy `symlinks_upgraded` key to the new `upgrades.symlinks` key and
clean up the old key, ensuring backward compatibility and config
cleanliness. This prevents the breaking change from being a _breaking
change_.

**Note**: The `symlinks_upgraded` is the only legacy key that needs to
be migrated. The `php_port_overrides_upgraded` key wasn't released in a
stable version, so it doesn't need migrating.
  
* Replaced the `shouldUpgradeNginxSitePhpPortOverrides` and
`shouldUpgradeSymbolicLinks` method calls with a direct call to
`isUpgraded` method.

* Removed the now unused `shouldUpgradeNginxSitePhpPortOverrides` and
`shouldUpgradeSymbolicLinks` methods.


These changes make the upgrade process more robust and future proof and
the configuration file easier to maintain.

Author: yCodeTech

cli/Valet/Configuration.php

@@ -431,7 +431,10 @@ public function read(): array {
 	}
 
 	/**
-	 * Get an item from the configuration file using "dot" notation.
+	 * Get an item from the configuration file.
+	 *
+	 * @uses Arr:get Gets a value from a nested array using "dot" notation.
+	 * @link https://laravel.com/docs/13.x/helpers#method-array-get
 	 *
 	 * @param string|int|null $key
 	 * @param mixed $default
@@ -445,14 +448,35 @@ public function get($key, $default = null) {
 	/**
 	 * Update a specific key in the configuration file.
 	 *
+	 * @uses Arr:set Sets a value within a nested array using "dot" notation.
+	 * @link https://laravel.com/docs/13.x/helpers#method-array-set
+	 *
 	 * @param string $key
 	 * @param mixed $value
 	 *
 	 * @return array
 	 */
 	public function updateKey(string $key, $value): array {
 		return tap($this->read(), function (&$config) use ($key, $value) {
-			$config[$key] = $value;
+			Arr::set($config, $key, $value);
+
+			$this->write($config);
+		});
+	}
+
+	/**
+	 * Remove a specific key from the configuration file.
+	 *
+	 * @uses Arr:forget Removes a value within a nested array using "dot" notation.
+	 * @link https://laravel.com/docs/13.x/helpers#method-array-forget
+	 *
+	 * @param string $key
+	 *
+	 * @return array
+	 */
+	public function removeKey(string $key): array {
+		return tap($this->read(), function (&$config) use ($key) {
+			Arr::forget($config, $key);
 
 			$this->write($config);
 		});

cli/Valet/Upgrader.php

@@ -72,41 +72,22 @@ private function pruneSymbolicLinks() {
 	 * This is a one-time upgrade that will be run when Valet is first installed.
 	 */
 	private function upgradeSymbolicLinks() {
-		if ($this->shouldUpgradeSymbolicLinks()) {
+		// Migrate legacy symlinks upgrade key to the new format.
+		$this->migrateSymlinksUpgradeKey();
+
+		// Check if the symlinks have NOT been upgraded yet AND the sites directory is NOT empty.
+		if (!$this->isUpgraded('symlinks') && !$this->files->isDirEmpty($this->site->sitesPath())) {
 			info("Upgrading your linked sites from the old junction links to symbolic links...");
 			// Convert all junction links to symbolic links.
 			$this->files->convertJunctionsToSymlinks($this->site->sitesPath());
 
-			// Add a new key to the config file to indicate that the symlinks have been upgraded.
-			// This will prevent the upgrade from running again, since it is a one-time upgrade.
-			$this->config->updateKey("symlinks_upgraded", true);
+			// Mark this upgrade as complete so it will not run again.
+			$this->markAsUpgraded('symlinks');
 
 			info("Successfully upgraded junction links to symbolic links.");
 		}
 	}
 
-	/**
-	 * Check if the symbolic links should be upgraded.
-	 *
-	 * @return bool Returns a boolean indicating whether the symlinks should be upgraded.
-	 *
-	 * The symlinks should be upgraded if:
-	 *
-	 * 1. The symlinks have not been upgraded yet (`$symlinksUpgraded` is `false`).
-	 * 2. The sites directory is not empty (`$isDirEmpty` is `false`).
-	 */
-	private function shouldUpgradeSymbolicLinks() {
-		// Get the value of the "symlinks_upgraded" key from the config.
-		// If the key doesn't exist, it will return false.
-		$symlinksUpgraded = $this->config->get("symlinks_upgraded", false);
-
-		// Check if the sites directory is empty.
-		$isDirEmpty = $this->files->isDirEmpty($this->site->sitesPath());
-
-		// Check if the symlinks have not been upgraded yet AND the sites directory is not empty.
-		return !$symlinksUpgraded && !$isDirEmpty;
-	}
-
 	/**
 	 * Lint the Nginx configuration files.
 	 *
@@ -226,7 +207,7 @@ private function upgradeDeprecatedNginxConfigDirectives() {
 	 * If the user has the old `SampleValetDriver` without the Valet namespace,
 	 * replace it with the new `SampleValetDriver` that uses the namespace.
 	 */
-	public function fixOldSampleValetDriver(): void {
+	public function fixOldSampleValetDriver() {
 		$samplePath = Valet::homePath() . '/Drivers/SampleValetDriver.php';
 
 		if ($this->files->exists($samplePath)) {
@@ -256,14 +237,14 @@ public function fixOldSampleValetDriver(): void {
 	 */
 	private function upgradeNginxSitePhpPortOverrides() {
 		// If the PHP port definitions have already been upgraded, skip.
-		if (!$this->shouldUpgradeNginxSitePhpPortOverrides()) {
+		if ($this->isUpgraded('nginx_site_php_port_overrides')) {
 			return;
 		}
 
 		// If the Nginx config directory doesn't exist, skip and mark it as upgraded to prevent
 		// this from running again.
 		if (!$this->files->exists($this->site->nginxPath())) {
-			$this->config->updateKey('php_port_overrides_upgraded', true);
+			$this->markAsUpgraded('nginx_site_php_port_overrides');
 			return;
 		}
 
@@ -293,15 +274,50 @@ private function upgradeNginxSitePhpPortOverrides() {
 			info("Upgraded {$upgraded} Nginx site config(s) to the new PHP port override format.");
 		}
 
-		$this->config->updateKey('php_port_overrides_upgraded', true);
+		$this->markAsUpgraded('nginx_site_php_port_overrides');
 	}
 
 	/**
-	 * Determine whether Nginx site PHP port overrides should be upgraded.
+	 * Determine if a named upgrade has already been completed.
+	 *
+	 * @param string $upgradeId
 	 *
 	 * @return bool
 	 */
-	private function shouldUpgradeNginxSitePhpPortOverrides() {
-		return !$this->config->get('php_port_overrides_upgraded', false);
+	private function isUpgraded(string $upgradeId): bool {
+		return $this->config->get("upgrades.{$upgradeId}", false);
+	}
+
+	/**
+	 * Mark a named upgrade as completed in the configuration.
+	 *
+	 * @param string $upgradeId
+	 */
+	private function markAsUpgraded(string $upgradeId) {
+		$this->config->updateKey("upgrades.{$upgradeId}", true);
+	}
+
+	/**
+	 * Migrate legacy `symlinks_upgraded` upgrade key to the new `symlinks` key under
+	 * the `upgrades` array in the configuration (`upgrades.symlinks`).
+	 *
+	 * If the legacy key exists but the new key doesn't, it marks the upgrade as completed,
+	 * and removes legacy key from configuration.
+	 */
+	private function migrateSymlinksUpgradeKey() {
+		$legacyUpgradeKey = 'symlinks_upgraded';
+		$newUpgradeKey = 'symlinks';
+
+		$hasNewKey = $this->isUpgraded($newUpgradeKey);
+		$hasLegacyKey = $this->config->get($legacyUpgradeKey, false);
+
+		// If the legacy key exists AND the new key doesn't,
+		// mark the new upgrade key as upgraded.
+		if ($hasLegacyKey && !$hasNewKey) {
+			$this->markAsUpgraded($newUpgradeKey);
+		}
+
+		// Remove the legacy upgrade key to clean up the config.
+		$this->config->removeKey($legacyUpgradeKey);
 	}
 }