fix: generate valid sample URIs for custom route placeholders

system/Commands/Utilities/Routes/SampleURIGenerator.php

@@ -62,7 +62,10 @@ public function get(string $routeKey): string
         }
 
         foreach ($this->routes->getPlaceholders() as $placeholder => $regex) {
-            $sample = $this->samples[$placeholder] ?? '::unknown::';
+            // Priority: 1) user-provided sample, 2) built-in sample, 3) placeholder name
+            $sample = $this->routes->getPlaceholderSamples()[$placeholder]
+                ?? $this->samples[$placeholder]
+                ?? $placeholder;
 
             $sampleUri = str_replace('(' . $regex . ')', $sample, $sampleUri);
         }

system/Router/RouteCollection.php

@@ -114,6 +114,14 @@ class RouteCollection implements RouteCollectionInterface
         'hash'     => '[^/]+',
     ];
 
+    /**
+     * Sample values for custom placeholders, used by SampleURIGenerator
+     * to produce valid sample URIs for 'php spark routes'.
+     *
+     * @var array<string, string>
+     */
+    protected $placeholderSamples = [];
+
     /**
      * An array of all routes and their mappings.
      *
@@ -384,16 +392,29 @@ protected function discoverRoutes()
      * You can pass an associative array as $placeholder, and have
      * multiple placeholders added at once.
      *
+     * The $sample parameter provides a representative value for the
+     * placeholder, used by 'php spark routes' to generate valid sample URIs.
+     * When omitted, the system attempts to infer a sample from the pattern.
+     *
      * @param array|string $placeholder
      */
-    public function addPlaceholder($placeholder, ?string $pattern = null): RouteCollectionInterface
+    public function addPlaceholder($placeholder, ?string $pattern = null, ?string $sample = null): RouteCollectionInterface
     {
         if (! is_array($placeholder)) {
             $placeholder = [$placeholder => $pattern];
         }
 
         $this->placeholders = array_merge($this->placeholders, $placeholder);
 
+        if ($sample !== null) {
+            $name = is_string($placeholder) ? [$placeholder => $sample] : [];
+
+            // When array format is used with a single key, extract the name
+            foreach ($placeholder as $name => $pat) {
+                $this->placeholderSamples[$name] = $sample;
+            }
+        }
+
         return $this;
     }
 
@@ -409,6 +430,18 @@ public function getPlaceholders(): array
         return $this->placeholders;
     }
 
+    /**
+     * Returns sample values for placeholders, used by SampleURIGenerator.
+     *
+     * @return array<string, string>
+     *
+     * @internal
+     */
+    public function getPlaceholderSamples(): array
+    {
+        return $this->placeholderSamples;
+    }
+
     /**
      * Sets the default namespace to use for Controllers when no other
      * namespace has been specified.

system/Router/RouteCollectionInterface.php

@@ -44,12 +44,16 @@ public function add(string $from, $to, ?array $options = null);
      * You can pass an associative array as $placeholder, and have
      * multiple placeholders added at once.
      *
+     * The $sample parameter provides a representative value for the
+     * placeholder, used by 'php spark routes' to generate valid sample URIs.
+     *
      * @param array|string $placeholder
      * @param string|null  $pattern     The regex pattern
+     * @param string|null  $sample      A sample value that matches the pattern
      *
      * @return RouteCollectionInterface
      */
-    public function addPlaceholder($placeholder, ?string $pattern = null);
+    public function addPlaceholder($placeholder, ?string $pattern = null, ?string $sample = null);
 
     /**
      * Sets the default namespace to use for Controllers when no other