feat: support feature branch names containing slashes

Branch names like "feature/ABC-12" were used verbatim as the instance
directory and url segment, which nested the instance and broke listing,
cleanup and deletion, while the database name silently dropped the slash.
Normalize path separators to hyphens in one place and route every consumer
through it. Names consisting of allowed characters only stay unchanged, so
existing instances and databases remain reachable.

Author: konradmichalik

deployer/dev/task/sync.php

@@ -38,7 +38,8 @@
     if ($target !== 'prod' && $target !== 'stage') {
         $dbSyncToolSync = get('dev_db_sync_tool_default_sync');
 
-        $dbSyncToolOriginPath = str_replace('<feature>', $target, get('dev_db_sync_tool_origin_path'));
+        // the remote path carries the instance name, not the raw branch name
+        $dbSyncToolOriginPath = str_replace('<feature>', getFeatureName($target), get('dev_db_sync_tool_origin_path'));
         $additionalOptions = "--origin-path $dbSyncToolOriginPath";
     } else {
         $dbSyncToolSync = $target === 'prod' ? get('dev_db_sync_tool_prod_sync') : get('dev_db_sync_tool_default_sync');

deployer/feature/task/feature_init.php

@@ -55,6 +55,8 @@ function initFeature(?string $feature = null): ?string
             return $array[2];
         }, listFeatureInstances()));
     }
+    // branch names may contain path separators ("feature/ABC-12"), the instance name must stay flat
+    $feature = getFeatureName($feature);
     set('feature', $feature);
 
     if (isUrlShortener()) {

deployer/feature/task/feature_setup.php

@@ -67,7 +67,8 @@ function renderRemoteTemplates(): void
 {
     debug('Rendering remote template');
     $databaseName = DbUtility::getDatabaseManager()->getDatabaseName();
-    $feature = input()->getOption('feature');
+    // the normalized name, matching the instance directory and url segment
+    $feature = get('feature');
     $templates = get('feature_templates');
 
     if (!$templates) {
@@ -144,13 +145,3 @@ function uploadTemplate($localTemplate, $remoteTarget, $arguments): void {
     upload($temporaryFileName,get('deploy_path') . $remoteTarget);
     unlink($temporaryFileName);
 }
-
-/**
- * @param ?string $feature
- * @return array|string|string[]|null
- */
-function getFeatureName(?string $feature = null) {
-    $feature = $feature ?: input()->getOption('feature');
-
-    return preg_replace('/[^A-Za-z0-9\_\-.]/', '', $feature);
-}

deployer/feature/task/feature_stop.php

@@ -33,7 +33,7 @@
  */
 function deleteFeature(?string $feature = null, $needConfirmation = false): void
 {
-    $feature = $feature ?: input()->getOption('feature');
+    $feature = getFeatureName($feature);
 
     $filesRemoveCommand = "rm -rf " . get('deploy_path');
 

deployer/functions.php

@@ -3,6 +3,7 @@
 namespace Deployer;
 
 use Deployer\Exception\RunException;
+use MoveElevator\DeployerTools\Utility\FeatureUtility;
 use Symfony\Component\Console\Output\OutputInterface;
 
 /**
@@ -55,6 +56,26 @@ function featureRequested(): bool
     return null !== $feature && '' !== trim((string)$feature);
 }
 
+/**
+ * Normalize a feature identifier into the flat instance name used for the deploy
+ * directory, the public url segment, the url shortener symlink and the database name.
+ *
+ * Branch names may carry path separators ("feature/ABC-12"), which would otherwise
+ * nest the instance directory and break listing, cleanup and deletion. Identifiers
+ * that already consist of allowed characters only are returned unchanged.
+ *
+ * @param ?string $feature
+ * @return string
+ */
+function getFeatureName(?string $feature = null): string
+{
+    if (null === $feature || '' === trim($feature)) {
+        $feature = featureRequested() ? (string)input()->getOption('feature') : '';
+    }
+
+    return FeatureUtility::normalize($feature);
+}
+
 /**
  * Extend the deployer configuration with available environment variables (starting with "DEPLOYER_CONFIG_"):
  *

docs/FEATURE.md

@@ -55,6 +55,17 @@ The `feature:setup` command represent the initialization of a new feature branch
 $ vendor/bin/dep feature:setup stage --feature=TEST-01
 ```
 
+The `--feature=` value may be a full branch name. Path separators are replaced by a hyphen so the instance stays a single flat directory, url segment and database suffix:
+
+| `--feature=`         | instance name        |
+|----------------------|----------------------|
+| `TEST-01`            | `TEST-01`            |
+| `feature/TEST-01`    | `feature-TEST-01`    |
+| `bugfix/TEST-01`     | `bugfix-TEST-01`     |
+| `release/1.2.0`      | `release-1.2.0`      |
+
+Names that already consist of letters, digits, `_`, `-` and `.` are used unchanged, so existing instances and their databases stay reachable. Since the branch prefix is kept, `feature/TEST-01` and `bugfix/TEST-01` remain two separate instances. The same normalization is applied by `feature:cleanup` when it compares remote git branches with the deployed instances.
+
 The recipe already wires this task into the deploy flow, together with a `feature:init` before `deploy:info`. That ordering matters: `deploy:info` resolves `{{release_name}}` and deployer caches the result for the rest of the run, so the feature instance has to be known before it runs. Do not hook `feature:setup` any earlier yourself.
 
 > Upgrading: if your `deploy.php` carries a `before('deploy:info', 'feature:init')` (or an equivalent `feature:setup` hook) as a workaround for that ordering, remove it — the recipe registers it now and the hook would otherwise run twice.
@@ -75,7 +86,7 @@ This configuration defines the local template file as well as the remote target
 | `DEPLOYER_CONFIG_DATABASE_PORT` | default is `3306`, overwrite with deployer `set('database_port', '3306');`           |
 | `DEPLOYER_CONFIG_DATABASE_USER` | should be defined with `database_user` in the host configuration                     |
 | `DEPLOYER_CONFIG_DATABASE_NAME` | will be dynamically generated                                                        |
-| `DEPLOYER_CONFIG_FEATURE_NAME`  | will be provide with the `--feature=` command line argument                          |
+| `DEPLOYER_CONFIG_FEATURE_NAME`  | the normalized instance name derived from the `--feature=` command line argument     |
 | `DEPLOYER_CONFIG_FEATURE_URL`   | will be dynamically generated                                                        |
 | `DEPLOYER_CONFIG_FEATURE_PATH`  | will be dynamically generated                                                        |
 

src/Database/Manager/AbstractManager.php

@@ -5,6 +5,7 @@
 namespace MoveElevator\DeployerTools\Database\Manager;
 
 use MoveElevator\DeployerTools\Database\Exception\DatabaseException;
+use MoveElevator\DeployerTools\Utility\FeatureUtility;
 use MoveElevator\DeployerTools\Utility\VarUtility;
 
 use function Deployer\get;
@@ -41,16 +42,18 @@ public function run(string $command, bool $useDoubleQuotes = true): string
      */
     public function getDatabaseName(?string $feature = null): string
     {
-        $feature = $feature ?: input()->getOption('feature');
-        $project = get('project');
-        return substr($this->getFeatureName("{$project}--{$feature}"), 0, 63);
+        // both parts are normalized separately, so the "--" separator survives
+        $project = FeatureUtility::normalize((string) get('project'));
+        $feature = $this->getFeatureName($feature);
+
+        return substr($project . '--' . $feature, 0, 63);
     }
 
 
     public function getFeatureName(?string $feature = null): string
     {
         $feature = $feature ?: input()->getOption('feature');
 
-        return preg_replace('/[^A-Za-z0-9\_\-.]/', '', (string) $feature);
+        return FeatureUtility::normalize((string) $feature);
     }
 }

src/Database/Manager/Simple.php

@@ -11,7 +11,6 @@
 use function Deployer\set;
 use function Deployer\has;
 use function Deployer\run;
-use function Deployer\input;
 use function Deployer\upload;
 use function Deployer\runExtended;
 use function Deployer\test;
@@ -50,7 +49,7 @@ public function delete(string $feature): void
         debug('Deleting database');
         $this->ensureDatabasePoolExists();
         $this->initDatabaseConfiguration(feature: $feature);
-        $this->assignmentManager->removeAssignment($feature);
+        $this->assignmentManager->removeAssignment($this->getFeatureName($feature));
         $this->run($this->generateDropTablesQuery($this->getDatabaseName($feature)));
     }
 
@@ -78,8 +77,7 @@ public function exists(?string $feature = null): bool
 
     public function getDatabaseName(?string $feature = null): string
     {
-        $feature = $feature ?: input()->getOption('feature');
-        $databaseAssignment = $this->assignmentManager->getAssignment($feature);
+        $databaseAssignment = $this->assignmentManager->getAssignment($this->getFeatureName($feature));
 
         if (!$databaseAssignment) {
             return '';
@@ -115,7 +113,7 @@ private function initDatabaseConfiguration(?string $database = null, ?string $fe
     {
         $pool = get('database_pool');
         if (!$database) {
-            $database = $this->assignmentManager->getAssignment($feature ?: $this->getFeatureName());
+            $database = $this->assignmentManager->getAssignment($this->getFeatureName($feature));
         }
 
         if (!isset($pool[$database])) {

src/Utility/FeatureUtility.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MoveElevator\DeployerTools\Utility;
+
+/**
+ * Normalizes feature identifiers into a name that is safe to use as a directory,
+ * URL segment, symlink and database name suffix.
+ */
+final class FeatureUtility
+{
+    /**
+     * Turn a feature identifier (typically a git branch name) into a flat instance name.
+     *
+     * Path separators become hyphens instead of being dropped, so "feature/ABC-12" and
+     * "bugfix/ABC-12" stay distinct instances. Names that already consist of allowed
+     * characters only are returned unchanged, which keeps existing instances and their
+     * databases reachable.
+     *
+     * @throws \InvalidArgumentException if a non-blank identifier normalizes to an empty
+     *                                   name, which would silently address the base instance
+     */
+    public static function normalize(?string $feature): string
+    {
+        $feature = trim((string) $feature);
+
+        if ('' === $feature) {
+            return '';
+        }
+
+        $normalized = str_replace(['/', '\\'], '-', $feature);
+        $normalized = (string) preg_replace('/[^A-Za-z0-9_\-.]/', '', $normalized);
+        $normalized = trim($normalized, '-.');
+
+        if ('' === $normalized) {
+            throw new \InvalidArgumentException(
+                sprintf('The feature name "%s" contains no usable characters.', $feature)
+            );
+        }
+
+        return $normalized;
+    }
+}