feat: introduce MercureHelper::addTopic()/AddTopics()

Also drop MercureHelper::buildUrl as this is confusing and not needed

Author: josbeir

README.md

@@ -578,23 +578,20 @@ eventSource.onmessage = (event) => {
 </script>
 ```
 
-> [!WARNING]
-> **Important:** The `url()` method **only sets authorization when the `$subscribe` parameter is provided**. If you're already handling authorization in your controller (via `MercureComponent`), you can use either:
+> [!NOTE]
+> **Separation of Concerns:** The `url()` method **only sets authorization when the `$subscribe` parameter is provided**. If you're already handling authorization in your controller (via `MercureComponent`), simply omit the `$subscribe` parameter:
 >
 > ```php
 > // Authorization already set in controller
 > $this->Mercure->authorize(['/books/123']);
 >
-> // In template: either of these works (no duplicate authorization)
-> const url1 = '<?= $this->Mercure->url(['/books/123']) ?>';  // No $subscribe = no auth
-> const url2 = '<?= $this->Mercure->getHubUrl(['/books/123']) ?>';  // Explicit
+> // In template: just get the URL (no duplicate authorization)
+> const url = '<?= $this->Mercure->url(['/books/123']) ?>';
 > ```
->
-> Use `getHubUrl()` when you want to be explicit that authorization is handled elsewhere.
 
 #### Setting Default Topics
 
-You can configure default topics that will be automatically merged with any topics you provide to `url()` or `getHubUrl()`. This is useful when you want certain topics (like notifications or global alerts) to be included in every subscription:
+You can configure default topics that will be automatically merged with any topics you provide to `url()`. This is useful when you want certain topics (like notifications or global alerts) to be included in every subscription:
 
 ```php
 // In your controller or AppView
@@ -612,18 +609,23 @@ public function initialize(): void
 }
 ```
 
-Now every call to `url()` or `getHubUrl()` will automatically include these default topics:
+Now every call to `url()` will automatically include these default topics:
 
 ```php
 // In your template
 <script>
 // This will subscribe to: /notifications, /alerts, AND /books/123
 const url = '<?= $this->Mercure->url(['/books/123']) ?>';
 const eventSource = new EventSource(url, { withCredentials: true });
-
-// Access configured defaults if needed
-const defaults = <?= json_encode($this->Mercure->getConfig('defaultTopics', [])) ?>;
 </script>
+
+// You can also add topics dynamically:
+$this->Mercure->addTopic('/user/' . $userId . '/messages');
+$this->Mercure->addTopics(['/books/456', '/comments/789']);
+
+// These will be merged with configured defaults
+const url = '<?= $this->Mercure->url(['/books/123']) ?>';
+// Result includes: /notifications, /alerts, /user/{id}/messages, /books/456, /comments/789, AND /books/123
 ```
 
 #### Using the Facade (Alternative)
@@ -999,7 +1001,8 @@ Static facade for direct authorization management (alternative to component).
 | Method | Returns | Description |
 |--------|---------|-------------|
 | `url(array\|string\|null $topics, array $subscribe, array $additionalClaims)` | `string` | Get hub URL **and optionally authorize** (only sets cookie when `$subscribe` is provided). Merges with default topics if configured. |
-| `getHubUrl(array $topics, array $options)` | `string` | Get hub URL **without authorization** (explicit, no cookie ever set). Merges with default topics if configured. |
+| `addTopic(string $topic)` | `$this` | Add a single topic to default topics (fluent interface) |
+| `addTopics(array $topics)` | `$this` | Add multiple topics to default topics (fluent interface) |
 | `authorize(array $subscribe, array $additionalClaims)` | `void` | Set authorization cookie explicitly |
 | `clearAuthorization()` | `void` | Clear authorization cookie |
 | `discover()` | `void` | Add Mercure discovery Link header |
@@ -1010,7 +1013,7 @@ Static facade for direct authorization management (alternative to component).
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `defaultTopics` | `array` | `[]` | Topics to automatically merge with every subscription |
+| `defaultTopics` | `array` | `[]` | Topics to automatically merge with every subscription (read-only, not mutated by `addTopic()`/`addTopics()`) |
 
 ### Update
 

src/View/Helper/MercureHelper.php

@@ -34,6 +34,10 @@
  * // Default topics will be merged with provided topics
  * $hubUrl = $this->Mercure->url(['/books/123']); // Result: ['/books/123', '/notifications', '/alerts']
  *
+ * // Add topics dynamically
+ * $this->Mercure->addTopic('/user/123/messages');
+ * $this->Mercure->addTopics(['/books/456', '/comments/789']);
+ *
  * // Simple usage: Just get the hub URL with default topics
  * $hubUrl = $this->Mercure->url();
  *
@@ -53,9 +57,8 @@
  * // Add Mercure discovery header
  * $this->Mercure->discover();
  *
- * // Legacy API (still supported):
+ * // Manual authorization (if needed separately):
  * $this->Mercure->authorize(['/books/123', '/notifications']);
- * $hubUrl = $this->Mercure->getHubUrl(['/books/123']);
  * $this->Mercure->clearAuthorization();
  * ```
  */
@@ -71,19 +74,69 @@ class MercureHelper extends Helper
     ];
 
     /**
-     * Merge provided topics with default topics (removing duplicates)
+     * Runtime topics (includes default topics + dynamically added topics)
+     *
+     * @var array<string>
+     */
+    protected array $topics = [];
+
+    /**
+     * Initialize callback
+     *
+     * @param array<string, mixed> $config Configuration
+     */
+    public function initialize(array $config): void
+    {
+        parent::initialize($config);
+
+        // Initialize topics from config
+        $defaultTopics = $this->getConfig('defaultTopics', []);
+        $this->topics = is_array($defaultTopics) ? $defaultTopics : [];
+    }
+
+    /**
+     * Add a single topic to the helper's topics
+     *
+     * @param string $topic Topic to add
+     * @return $this
+     */
+    public function addTopic(string $topic)
+    {
+        if (!in_array($topic, $this->topics, true)) {
+            $this->topics[] = $topic;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Add multiple topics to the helper's topics
+     *
+     * @param array<string> $topics Topics to add
+     * @return $this
+     */
+    public function addTopics(array $topics)
+    {
+        foreach ($topics as $topic) {
+            $this->addTopic($topic);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Merge provided topics with helper's topics (removing duplicates)
      *
      * @param array<string> $topics Provided topics
      * @return array<string>
      */
     protected function mergeTopics(array $topics): array
     {
-        $defaultTopics = $this->getConfig('defaultTopics', []);
-        if ($defaultTopics === []) {
+        if ($this->topics === []) {
             return $topics;
         }
 
-        return array_values(array_unique(array_merge($defaultTopics, $topics)));
+        return array_values(array_unique(array_merge($this->topics, $topics)));
     }
 
     /**
@@ -128,31 +181,6 @@ public function url(array|string|null $topics = null, array $subscribe = [], arr
         return $this->buildSubscriptionUrl($hubUrl, $topics, []);
     }
 
-    /**
-     * Get the Mercure hub URL
-     *
-     * Optionally builds a URL with topic query parameters for EventSource connections.
-     * Default topics (if configured) will be automatically merged with provided topics.
-     *
-     * @param array<string> $topics Optional topics to subscribe to
-     * @param array<string, mixed> $options Additional query parameters
-     * @return string Hub URL
-     * @throws \Mercure\Exception\MercureException
-     */
-    public function getHubUrl(array $topics = [], array $options = []): string
-    {
-        // Merge with default topics
-        $topics = $this->mergeTopics($topics);
-
-        $hubUrl = ConfigurationHelper::getPublicUrl();
-
-        if ($topics === [] && $options === []) {
-            return $hubUrl;
-        }
-
-        return $this->buildSubscriptionUrl($hubUrl, $topics, $options);
-    }
-
     /**
      * Set authorization cookie for subscriber access to private topics
      *