>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3584485. --> Reported by: [mably](https://www.drupal.org/user/3375160) Related to !3 >>> <h2>Problem</h2> <p>Visit tracking currently has two issues:</p> <ol> <li><strong>Two separate tracking code paths</strong>: the <code>ShortUrlVisitMiddleware</code> (HTTP layer) and <code>VisitTracker</code> (service) both build visit field arrays and insert into <code>shorturl_visits</code> independently, with different method signatures. Changes to the visit schema must be applied in both places.</li> <li><strong>No extension point for external analytics</strong>: there is no way for submodules to send visit events to external analytics services (Matomo, Piano/AT Internet, Google Analytics Measurement Protocol, etc.) without monkey-patching or replacing the entire tracker.</li> </ol> <h2>Proposed solution</h2> <p>Introduce a <strong>visit event</strong> dispatched via Symfony EventDispatcher when a visit occurs. This provides a single, clean extension point for all visit-related behavior.</p> <h3>Architecture</h3> <ol> <li><strong>ShortUrlVisitEvent</strong>: a Symfony event carrying all visit data (nid, langcode, referrer, IP hash, user agent, country code, timestamp, plus any extra fields added by submodules like domain_id).</li> <li><strong>Middleware dispatches the event</strong>: instead of doing its own DB insert, the middleware builds the visit data from response headers and dispatches a <code>ShortUrlVisitEvent</code>. This becomes the single entry point for all visit tracking.</li> <li><strong>Event subscribers react</strong>: <ul> <li><strong>DatabaseVisitSubscriber</strong> (priority 0): writes to <code>shorturl_visits</code> table (current behavior, now in one place)</li> <li><strong>AnalyticsVisitSubscriber</strong> (contrib/custom): sends the event to Matomo, Piano, GA, etc.</li> <li><strong>Custom subscribers</strong> (contrib/custom): can read any field from the event and send to external services, add logging, etc.</li> </ul> </li> <li><strong>VisitTracker service</strong>: simplified to dispatch the same event, so direct <code>trackVisit()</code> calls also go through the event system. The <code>getStats()</code> and <code>purgeExpiredVisits()</code> methods remain on the service (they are DB-specific).</li> </ol> <h3>Benefits</h3> <ul> <li>Single code path for visit tracking (no more middleware vs service duplication)</li> <li>Submodules add fields via event subscribers (e.g. domain_id) with standard Drupal patterns</li> <li>External analytics integration via event subscribers, no core changes needed</li> <li>Consistent method signatures throughout</li> <li>Easy to test (dispatch event, assert subscriber behavior)</li> </ul> <h3>Example: analytics subscriber</h3> <pre> class MatomoVisitSubscriber implements EventSubscriberInterface { public static function getSubscribedEvents(): array { return [ShortUrlVisitEvent::class =&gt; 'onVisit']; } public function onVisit(ShortUrlVisitEvent $event): void { // Send to Matomo tracking API. $this-&gt;matomoClient-&gt;trackPageView( $event-&gt;getSlug(), $event-&gt;getReferrer(), $event-&gt;getCountryCode(), ); } } </pre><h2>Automatic field collection from response headers</h2> <p>Instead of hardcoding which headers to read, the middleware should collect <strong>all <code>X-Shorturl-*</code> response headers</strong> automatically and add them to the event:</p> <pre> $fields = []; foreach ($response-&gt;headers-&gt;all() as $name =&gt; $values) { if (str_starts_with($name, 'x-shorturl-')) { $key = substr($name, 11); // strip "x-shorturl-" $fields[$key] = $values[0]; } } </pre><p>Any module that stamps an <code>X-Shorturl-*</code> header in <code>hook_redirect_response_alter</code> automatically gets that field into the event. Zero code changes in shorturl for new fields. For example:</p> <ul> <li><code>X-Shorturl-Nid</code> (base module) &rarr; <code>nid</code></li> <li><code>X-Shorturl-Langcode</code> (base module) &rarr; <code>langcode</code></li> <li><code>X-Shorturl-DomainId</code> (domain_shorturl) &rarr; <code>domainid</code></li> <li>Any future <code>X-Shorturl-CampaignId</code>, <code>X-Shorturl-ABVariant</code>, etc.</li> </ul> <p>The headers are cached by PageCache along with the redirect response, so subsequent anonymous requests still carry all metadata without any DB lookup.</p> <h2>Domain awareness is generic, not a submodule concern</h2> <p>The <code>domain_id</code> field on redirects is added by <code>domain_redirect</code> (a base field on the redirect entity). The event should carry <code>domain_id</code> natively by reading it from the redirect entity, just like it reads <code>shorturl_nid</code> and <code>langcode</code>.</p> <p>This means:</p> <ul> <li>The <code>ShortUrlVisitEvent</code> includes <code>domain_id</code> when the field exists on the redirect</li> <li>The <code>DatabaseVisitSubscriber</code> writes it to the <code>shorturl_visits</code> table (when the column exists)</li> <li>Analytics subscribers receive it automatically</li> <li><code>DomainAwareVisitTracker</code> and <code>DomainAwareVisitMiddleware</code> in domain_shorturl become unnecessary and can be removed</li> </ul> <p>The event architecture eliminates the need for separate domain-aware overrides of the tracker and middleware. The redirect entity is the single source of truth, and the event carries all its relevant fields generically.</p> <h2>Backward compatibility</h2> <p>The <code>VisitTrackerInterface</code> remains unchanged. The <code>buildVisitFields()</code> method (added in <a href="https://www.drupal.org/project/shorturl/issues/3584473">#3584473</a>) would be replaced by the event data object, but since it is a protected method, this is not a BC break.</p> <h2>Performance considerations</h2> <p>The current middleware is optimized for zero DB lookups: it reads metadata from cached response headers and does a single INSERT. The event-based architecture must preserve this performance characteristic.</p> <h3>Event dispatch overhead</h3> <p>Dispatching a Symfony event is negligible: an array lookup + method call per subscriber. No reflection or DI resolution at dispatch time. With 1&ndash;3 subscribers this adds microseconds.</p> <h3>Risks and mitigations</h3> <table> <tr> <th>Risk</th> <th>Impact</th> <th>Mitigation</th> </tr> <tr> <td><strong>Subscriber dependency loading</strong></td> <td>A subscriber that injects heavy services (HTTP client, analytics SDK) causes those to be instantiated at dispatch time, even on non-shorturl requests.</td> <td>Use lazy service proxies for subscribers with heavy dependencies. The container only instantiates the real service when a method is called.</td> </tr> <tr> <td><strong>Blocking external API calls</strong></td> <td>An analytics subscriber that makes a synchronous HTTP call to Matomo/Piano during the request blocks the redirect response.</td> <td>Subscribers should write to a lightweight queue (database or memory). A cron worker or kernel.terminate subscriber sends batched events to the external API after the response.</td> </tr> <tr> <td><strong>Entity loading</strong></td> <td>If the event carries a Redirect entity, that requires a DB load that the middleware currently avoids.</td> <td>The event carries raw field data (from response headers), not entities. The <code>ShortUrlVisitEvent</code> object holds scalar values: nid, langcode, referrer, domain_id, etc. Subscribers that need the full entity can load it themselves.</td> </tr> <tr> <td><strong>Multiple DB writes</strong></td> <td>Multiple subscribers each doing their own INSERT.</td> <td>Only the DatabaseVisitSubscriber writes to <code>shorturl_visits</code>. Other subscribers read from the event data (which is already in memory) and write to their own destinations.</td> </tr> </table> <h3>Performance target</h3> <p>The event-based architecture should add no more than 0.5ms overhead per visit compared to the current direct INSERT. This should be validated with benchmarks before and after the refactor.</p> <h2>Integration with kernel.terminate for external analytics</h2> <p>External analytics subscribers (Matomo, Piano, GA) should NOT make HTTP calls during the <code>ShortUrlVisitEvent</code> &mdash; that would block the redirect response. Instead, the recommended pattern uses <code>kernel.terminate</code>:</p> <ol> <li><strong>Visit event subscriber</strong> (runs during request): collects visit data into an in-memory collector service. No external calls.</li> <li><strong>kernel.terminate subscriber</strong> (runs after response is sent): reads collected visits and sends them to the external API. The user does not wait.</li> </ol> <h3>Example pattern</h3> <pre> // Collects visits during the request. class VisitAnalyticsCollector { protected array $visits = []; public function add(ShortUrlVisitEvent $event): void { $this-&gt;visits[] = $event-&gt;getFields(); } public function flush(): array { $visits = $this-&gt;visits; $this-&gt;visits = []; return $visits; } } // Subscribes to visit event &mdash; just collects, no API call. class AnalyticsVisitSubscriber implements EventSubscriberInterface { public static function getSubscribedEvents(): array { return [ShortUrlVisitEvent::class =&gt; 'onVisit']; } public function onVisit(ShortUrlVisitEvent $event): void { $this-&gt;collector-&gt;add($event); } } // Subscribes to kernel.terminate &mdash; sends to API after response. class AnalyticsTerminateSubscriber implements EventSubscriberInterface { public static function getSubscribedEvents(): array { return [KernelEvents::TERMINATE =&gt; 'onTerminate']; } public function onTerminate(): void { foreach ($this-&gt;collector-&gt;flush() as $visit) { $this-&gt;analyticsClient-&gt;send($visit); } } } </pre><h3>Caveat: middleware and container bootstrap</h3> <p>The visit middleware runs at priority 210 (before PageCache at 200). On cached anonymous requests, <code>kernel.terminate</code> still fires, but the Drupal container may not be fully bootstrapped. Analytics subscribers that rely on Drupal services (config, entity storage) need to verify the container is available. The visit data itself (from the event) is always available since it was collected during the middleware phase.</p>