feat: implement centralized override management for compose files

mstrhakr · mstrhakr · commit 52a7666305d3 · 2026-02-21T23:07:05.000-05:00
diff --git a/source/compose.manager/php/compose_list.php b/source/compose.manager/php/compose_list.php
@@ -44,6 +44,7 @@
 $stackCount = 0;
 
 foreach ($composeProjects as $project) {
+    // Skip if not a directory or if it doesn't contain a compose file (either directly or via indirect)
     if (!hasComposeFile("$compose_root/$project") &&
         (! is_file("$compose_root/$project/indirect"))
     ) {
@@ -64,15 +65,17 @@
         ? trim(file_get_contents("$compose_root/$project/indirect"))
         : "$compose_root/$project";
     $composeFile = findComposeFile($basePath) ?: "$basePath/docker-compose.yml";
-    $overrideFile = "$compose_root/$project/docker-compose.override.yml";
+    // Resolve override via centralized helper (prefer correctly-named indirect override)
+    require_once("/usr/local/emhttp/plugins/compose.manager/php/util.php");
+    $overridePath = OverrideInfo::fromStack($compose_root, $project)->getOverridePath();
 
     // Use docker compose config --services to get accurate service count
     // This properly parses YAML, handles overrides, extends, etc.
     $definedServices = 0;
     if (is_file($composeFile)) {
         $files = "-f " . escapeshellarg($composeFile);
-        if (is_file($overrideFile)) {
-            $files .= " -f " . escapeshellarg($overrideFile);
+        if (is_file($overridePath)) {
+            $files .= " -f " . escapeshellarg($overridePath);
         }
 
         // Get env file if specified
diff --git a/source/compose.manager/php/compose_util_functions.php b/source/compose.manager/php/compose_util_functions.php
@@ -91,10 +91,11 @@ function echoComposeCommand($action, $recreate = false)
             $composeCommand[] = "-f$composeFile";
         }
 
-        if (is_file("$path/docker-compose.override.yml")) {
-            $composeOverride = "-f$path/docker-compose.override.yml";
-            $composeCommand[] = $composeOverride;
-        }
+        // Resolve override using centralized helper
+        $stackName = basename($path);
+        require_once("/usr/local/emhttp/plugins/compose.manager/php/util.php");
+        $overridePath = OverrideInfo::fromStack($compose_root, $stackName)->getOverridePath();
+        $composeCommand[] = "-f" . escapeshellarg($overridePath);
 
         if (is_file("$path/envpath")) {
             $envPath = "-e" . trim(file_get_contents("$path/envpath"));
@@ -205,11 +206,10 @@ function echoComposeCommandMultiple($action, $paths)
             $composeCommand[] = "-f$composeFile";
         }
 
-        if (is_file("$path/docker-compose.override.yml")) {
-            $composeOverride = "-f$path/docker-compose.override.yml";
-            $composeCommand[] = $composeOverride;
-        }
-
+        // Resolve override using centralized helper
+        require_once("/usr/local/emhttp/plugins/compose.manager/php/util.php");
+        $overridePath = OverrideInfo::fromStack($compose_root, $stackName)->getOverridePath();
+        $composeCommand[] = "-f" . escapeshellarg($overridePath);
         if (is_file("$path/envpath")) {
             $envPath = "-e" . trim(file_get_contents("$path/envpath"));
             $composeCommand[] = $envPath;
diff --git a/source/compose.manager/php/exec.php b/source/compose.manager/php/exec.php
@@ -72,43 +72,18 @@ function getPostScript(): string
         if ($indirect != "") {
             file_put_contents("$folder/indirect", $indirect);
             if (!findComposeFile($indirect)) {
-                file_put_contents("$indirect/compose.yaml", "services:\n");
+                file_put_contents("$indirect/" . COMPOSE_FILE_NAMES[0], "services:\n");
                 clientDebug("[stack] Indirect compose file not found at path: $indirect. Created stack with empty compose file.", null, 'daemon', 'warning');
             }
         } else {
-            file_put_contents("$folder/compose.yaml", "services:\n");
+            file_put_contents("$folder/" . COMPOSE_FILE_NAMES[0], "services:\n");
             clientDebug("[$stackName] Compose file not found at path: $folder. Created stack with empty compose file.", null, 'daemon', 'warning');
         }
 
-        // Create initial override file if it doesn't exist (for UI labels)
-        // Override filename must match the compose filename (e.g. compose.yaml -> compose.override.yaml)
-        // Overrides are stored in the project folder ($folder) even for indirect stacks.
-        $composeSource = $indirect != "" ? $indirect : $folder;
-        $foundCompose = findComposeFile($composeSource);
-        $composeBaseName = $foundCompose !== false ? basename($foundCompose) : 'docker-compose.yml';
-        $overrideName = preg_replace('/(\.[^.]+)$/', '.override$1', $composeBaseName);
-        $overrideFile = "$folder/$overrideName";
-
-        // Migrate legacy override filename if present in either project folder or indirect path
-        $legacyInProject = "$folder/docker-compose.override.yml";
-        $legacyInIndirect = ($indirect != "") ? "$indirect/docker-compose.override.yml" : null;
-        if (!is_file($overrideFile)) {
-            if (is_file($legacyInProject) && realpath($legacyInProject) !== realpath($overrideFile)) {
-                @rename($legacyInProject, $overrideFile);
-                clientDebug("[override] Migrated legacy override $legacyInProject -> $overrideFile", null, 'daemon', 'info');
-            } elseif ($legacyInIndirect && is_file($legacyInIndirect) && realpath($legacyInIndirect) !== realpath($overrideFile)) {
-                @rename($legacyInIndirect, $overrideFile);
-                clientDebug("[override] Migrated legacy override $legacyInIndirect -> $overrideFile", null, 'daemon', 'info');
-            }
-        }
-
-        if (!is_file($overrideFile)) {
-            $overrideContent = "# Override file for UI labels (icon, webui, shell)\n";
-            $overrideContent .= "# This file is managed by Compose Manager\n";
-            $overrideContent .= "services: {}\n";
-            file_put_contents($overrideFile, $overrideContent);
-        }
+        // Init override info to ensure override file is created for new stack (if not indirect) and to avoid errors when accessing settings before the override file is created
+        OverrideInfo::fromStack($compose_root, $stackName);
 
+        // Save stack name (which may differ from folder name) for display purposes
         file_put_contents("$folder/name", $stackName);
 
         // Save description if provided
@@ -172,7 +147,7 @@ function getPostScript(): string
         $script = getPostScript();
         $basePath = getPath("$compose_root/$script");
         $foundComposeFile = findComposeFile($basePath);
-        $composeFilePath = $foundComposeFile !== false ? $foundComposeFile : "$basePath/docker-compose.yml";
+        $composeFilePath = $foundComposeFile !== false ? $foundComposeFile : "$basePath/compose.yaml";
         $fileName = basename($composeFilePath);
 
         if ($foundComposeFile !== false) {
@@ -221,36 +196,8 @@ function getPostScript(): string
         $script = getPostScript();
         $projectPath = "$compose_root/$script";
 
-        // If indirect exists, use it to discover the compose filename, but
-        // overrides are stored in the project folder ($projectPath).
-        $indirectPath = is_file("$projectPath/indirect") ? file_get_contents("$projectPath/indirect") : "";
-        $indirectPath = str_replace("\r", "", $indirectPath);
-        $composeSource = $indirectPath !== "" ? $indirectPath : $projectPath;
-
-        $foundCompose = findComposeFile($composeSource);
-        $composeBaseName = $foundCompose !== false ? basename($foundCompose) : 'docker-compose.yml';
-        $fileName = preg_replace('/(\.[^.]+)$/', '.override$1', $composeBaseName);
-
-        $overridePath = "$projectPath/$fileName";
-        $legacyProject = "$projectPath/docker-compose.override.yml";
-        $legacyIndirect = ($indirectPath !== "") ? "$indirectPath/docker-compose.override.yml" : null;
-
-        // Prefer correctly-named indirect override if present (do NOT move/rename indirect files)
-        if ($indirectPath !== "" && is_file("$indirectPath/$fileName")) {
-            $overridePath = "$indirectPath/$fileName";
-        } else {
-            // If indirect has a legacy-named override, warn the user and fall back to project override
-            if ($indirectPath !== "" && $legacyIndirect && is_file($legacyIndirect)) {
-                clientDebug("[override] Indirect override exists with non-matching name ($legacyIndirect). Using project fallback.", null, 'daemon', 'warning');
-            }
-
-            // Migrate legacy project override to computed name if present (project-only migration)
-            if (!is_file($projectPath.'/'.$fileName) && is_file($legacyProject) && realpath($legacyProject) !== realpath($projectPath.'/'.$fileName)) {
-                @rename($legacyProject, $projectPath.'/'.$fileName);
-                clientDebug("[override] Migrated legacy project override $legacyProject -> $projectPath/$fileName", null, 'daemon', 'info');
-            }
-            $overridePath = "$projectPath/$fileName";
-        }
+        // Get Override file path and ensure project override exists (create blank if not)
+        $overridePath = OverrideInfo::fromStack($compose_root, $script)->getOverridePath();
 
         $scriptContents = is_file($overridePath) ? file_get_contents($overridePath) : "";
         $scriptContents = str_replace("\r", "", $scriptContents);
@@ -287,38 +234,8 @@ function getPostScript(): string
         $scriptContents = isset($_POST['scriptContents']) ? $_POST['scriptContents'] : "";
         $projectPath = "$compose_root/$script";
 
-        // Determine compose source (indirect or project) for filename, but
-        // always store override in project folder.
-        $indirectPath = is_file("$projectPath/indirect") ? file_get_contents("$projectPath/indirect") : "";
-        $indirectPath = str_replace("\r", "", $indirectPath);
-        $composeSource = $indirectPath !== "" ? $indirectPath : $projectPath;
-
-        $foundCompose = findComposeFile($composeSource);
-        $composeBaseName = $foundCompose !== false ? basename($foundCompose) : 'docker-compose.yml';
-        $fileName = preg_replace('/(\.[^.]+)$/', '.override$1', $composeBaseName);
-
-        // Determine where to save: if indirect has a correctly-named override, save there (do NOT rename/move indirect files).
-        $indirectOverridePath = ($indirectPath !== "") ? "$indirectPath/$fileName" : null;
-        $legacyIndirect = ($indirectPath !== "") ? "$indirectPath/docker-compose.override.yml" : null;
-        $legacyProject = "$projectPath/docker-compose.override.yml";
-
-        if ($indirectOverridePath && is_file($indirectOverridePath)) {
-            // Save back to the indirect override file the user provided (preserve external file)
-            $overridePath = $indirectOverridePath;
-        } else {
-            // If an indirect legacy-named override exists, warn and save to project fallback (do not move it)
-            if ($legacyIndirect && is_file($legacyIndirect)) {
-                clientDebug("[override] Indirect override exists with non-matching name ($legacyIndirect). Saving to project override instead.", null, 'daemon', 'warning');
-            }
-
-            // Migrate legacy project override to computed name if present (project-only migration)
-            if (!is_file("$projectPath/$fileName") && is_file($legacyProject) && realpath($legacyProject) !== realpath("$projectPath/$fileName")) {
-                @rename($legacyProject, "$projectPath/$fileName");
-                clientDebug("[override] Migrated legacy project override $legacyProject -> $projectPath/$fileName", null, 'daemon', 'info');
-            }
-
-            $overridePath = "$projectPath/$fileName";
-        }
+        // Get Override file path and ensure project override exists (create blank if not)
+        $overridePath = OverrideInfo::fromStack($compose_root, $script)->getOverridePath();
 
         file_put_contents($overridePath, $scriptContents);
         echo "$overridePath saved";
diff --git a/source/compose.manager/php/exec_functions.php b/source/compose.manager/php/exec_functions.php
@@ -79,13 +79,15 @@ function buildComposeArgs(string $stack): array {
     $projectName = sanitizeStr($projectName);
 
     $basePath = getPath("$compose_root/$stack");
-    $composeFile = findComposeFile($basePath) ?: "$basePath/docker-compose.yml";
-    $overrideFile = "$compose_root/$stack/docker-compose.override.yml";
+    $composeFile = findComposeFile($basePath) ?: "$basePath/compose.yaml";
 
     $files = "-f " . escapeshellarg($composeFile);
-    if (is_file($overrideFile)) {
-        $files .= " -f " . escapeshellarg($overrideFile);
-    }
+
+    // Resolve override selection: prefer correctly-named indirect override if present,
+    // otherwise use project override (migrating legacy project override when applicable).
+    require_once("/usr/local/emhttp/plugins/compose.manager/php/util.php");
+    $overridePath = OverrideInfo::fromStack($compose_root, $stack)->getOverridePath();
+    $files .= " -f " . escapeshellarg($overridePath);
 
     $envFile = "";
     if (is_file("$compose_root/$stack/envpath")) {
diff --git a/source/compose.manager/php/util.php b/source/compose.manager/php/util.php
@@ -110,6 +110,136 @@ function hasComposeFile($dir)
     return findComposeFile($dir) !== false;
 }
 
+class OverrideInfo
+{
+    /**
+     * @var string Computed override filename (e.g. compose.override.yaml)
+     */
+    public string $computedName = '';
+    /**
+     * @var string|null Path to project override file
+     */
+    public ?string $projectOverride = null;
+    /**
+     * @var string|null Path to indirect override file
+     */
+    public ?string $indirectOverride = null;
+    /**
+     * @var bool True if indirect override should be used
+     */
+    public bool $useIndirect = false;
+    /**
+     * @var bool True if indirect contains legacy-named override but not correctly-named one
+     */
+    public bool $mismatchIndirectLegacy = false;
+
+    /**
+     * @var string Compose root directory
+     */
+    private string $composeRoot;
+
+    /**
+     * @var string Stack name (folder name under compose root) - used for generating override template path
+     */
+    private string $stack;
+
+    /**
+     * Constructor
+     * @param string $composeRoot Compose root directory
+     */
+    private function __construct(string $composeRoot)
+    {
+        $this->composeRoot = rtrim($composeRoot, "/");
+    }
+
+    /**
+     * Static factory to create and resolve an OverrideInfo for a stack.
+     * @param string $composeRoot
+     * @param string $stack
+     * @return OverrideInfo
+     */
+    public static function fromStack(string $composeRoot, string $stack): OverrideInfo
+    {
+        $info = new self($composeRoot);
+        $info->resolve($stack);
+        return $info;
+    }
+
+    /**
+     * Resolve override information for a given stack and populate this instance.
+     * @param string $stack
+     * @return void
+     */
+    private function resolve(string $stack): void
+    {
+        $this->stack = $stack;
+        $projectPath = $this->getProjectPath($stack);
+        $indirectPath = is_file("$projectPath/indirect") ? trim(file_get_contents("$projectPath/indirect")) : null;
+        $composeSource = $indirectPath !== "" ? $indirectPath : $projectPath;
+
+        $foundCompose = findComposeFile($composeSource);
+        $composeBaseName = $foundCompose !== false ? basename($foundCompose) : COMPOSE_FILE_NAMES[0];
+        $this->computedName = preg_replace('/(\.[^.]+)$/', '.override$1', $composeBaseName);
+
+        $this->projectOverride = $projectPath . '/' . $this->computedName;
+        $this->indirectOverride = $indirectPath !== "" ? ($indirectPath . '/' . $this->computedName) : null;
+
+        $legacyProject = $projectPath . '/docker-compose.override.yml';
+        $legacyIndirect = $indirectPath !== "" ? ($indirectPath . '/docker-compose.override.yml') : null;
+
+        $this->useIndirect = ($this->indirectOverride && is_file($this->indirectOverride));
+        $this->mismatchIndirectLegacy = ($indirectPath !== "" && $legacyIndirect && is_file($legacyIndirect) && !($this->indirectOverride && is_file($this->indirectOverride)));
+
+        // Migrate legacy project override to computed project override (project-only migration)
+        if (!is_file($this->projectOverride) && is_file($legacyProject) && realpath($legacyProject) !== @realpath($this->projectOverride)) {
+            @rename($legacyProject, $this->projectOverride);
+            clientDebug("[override] Migrated legacy project override $legacyProject -> $this->projectOverride", null, 'daemon', 'info');
+        }
+
+        if (is_file($this->projectOverride) && is_file($legacyProject) && realpath($legacyProject) !== @realpath($this->projectOverride)) {
+            @rename($legacyProject, $legacyProject . ".bak");
+            clientDebug("[override] Removed stale legacy project override $legacyProject (mismatch with computed override)", null, 'daemon', 'info');
+        }
+
+        if ($this->mismatchIndirectLegacy) {
+            clientDebug("[override] Indirect override exists with non-matching name; using project fallback.", null, 'daemon', 'warning');
+        }
+
+        if (!is_file($this->projectOverride) && !$this->useIndirect) {
+            $overrideContent = "# Override file for UI labels (icon, webui, shell)\n";
+            $overrideContent .= "# This file is managed by Compose Manager\n";
+            $overrideContent .= "services: {}\n";
+            file_put_contents($this->projectOverride, $overrideContent);
+            clientDebug("[override] Created missing project override template at $this->projectOverride", null, 'daemon', 'info');
+        }
+    }
+
+    /**
+     * Get the override file to use (indirect if present, else project override)
+     * @return string|null
+     */
+    public function getOverridePath(): ?string
+    {
+        return $this->useIndirect ? $this->indirectOverride : $this->projectOverride;
+    }
+
+    /**
+     * Get the project path for a stack
+     * @param string $stack
+     * @return string
+     */
+    private function getProjectPath(string $stack): string
+    {
+        return $this->composeRoot . '/' . $stack;
+    }
+}
+
+
+
+
+
+
+
 /**
  * Stack operation locking functions
  * Prevents concurrent operations on the same stack
