Symfony Bundle Laravel Package

Technical Evaluation

Architecture fit. Release 0.15.0 completes a consolidation the family has been running for several waves: the bundle is being reduced to a thin DI/config layer, with shared behavior pushed down into indexnowkit/core and the optional console / history / sitemap / verify packages. Wave M removes the bundle's private copies of Check\LocalesCheck, Check\EntitySampler, Check\SampleOptions, Check\VerifySampleCheck, and every Command\* class, replacing them with the packages' equivalents under stable service ids. For a TPM this is the single most important signal in the release: the integration surface we program against (service ids, command names, arguments, options, exit codes, --json output) is being held stable while class names move. That is a deliberate and correct trade — it lets us pin behavior without pinning implementation.

One caveat on framing: this release is the Symfony bundle. The stack in our brief says Laravel/PHP. Everything in these notes — compiler passes, service_closure, #[AsCommand], decorates: — is Symfony DI. The relevant question for us is whether the core contracts introduced here (the clock, ConfigSourceInterface, SubjectSampler, BatchingDispatcher) land in the Laravel adapter at the same core version. Treat the bundle as the reference implementation, not the integration target.

Integration feasibility. High, with named exceptions. The genuinely new capability is indexnowkit.clock (Clock\SystemClock, aliased to Psr\Clock\ClockInterface), now the single time source for throttle, the memory debounce store, the submitter, the command submitter factory, and the pre-flight decorators. This is the release's best feature from a testability standpoint: a FrozenClock in a compiler pass moves the debounce window, the throttle window, and submission-record timestamps together, which means time-dependent behavior becomes deterministic in CI instead of flaky. It also means we must confirm the clock service is shared in our container; an unshared clock would reintroduce exactly the drift this change exists to eliminate.

Technical risk. Four items, in order:

1. Breaking references, not breaking behavior. IndexNowKit\SymfonyBundle\Command\*, Check\LocalesCheck, Check\EntitySampler, Check\SampleOptions, and Check\VerifySampleCheck are gone. Anything that does instanceof, subclasses a command, or puts a decorates: on a bundle command id will fail to compile. The documented migration is to decorate the runner (indexnowkit.console.submit_entity, …) or register a command of our own under the same name. Also, Command\EntityLoader now extends Console\AbstractSubjectLoader — constructor and manager() unchanged, so this is safe unless we subclassed internals.
2. FlushListener constructor change from a PSR-11 service locator to (CollectorInterface, Closure(): IndexNowKit). Only hand-built listeners break; container-wired ones are fine. The rationale (PSR-11 says an object should not be handed a container to fetch its own dependencies) is sound and worth accepting.
3. Version lockstep. The release requires core ^0.13, console ^0.5, and history ^0.4 when installed, with conflict entries against older. Three coupled pre-1.0 packages means our upgrade is atomic across them.
4. MessengerDispatcher constructor change — internal (indexnowkit.dispatcher), explicitly not in docs/bc.md. Low risk, but it confirms the BC promise is scoped to documented ids and class names.

Key questions for the maintainer. (a) Which service ids and classes are actually inside the docs/bc.md promise, and will that document be published as a contract we can test against? (b) Does the Laravel adapter ship at core ^0.13 and console ^0.5, and does it expose indexnowkit.clock? (c) Is PSR-20 clock adoption complete — are there remaining direct time() / new \DateTimeImmutable() calls in the bundle or core that would escape a FrozenClock? (d) What is the support matrix for Symfony and PHP versions, and the 1.0 horizon? (e) Is the new OptionalPackagesDetectionTest matrix exhaustive across the sitemap/verify/history combinations?

Integration Approach

Stack fit. If our application is Laravel, this bundle is not the artifact we install — the core plus a Laravel service provider is. The work here is still directly relevant: indexnowkit.clock, DependencyInjection\ConsoleConfigSource replacing three constructor arguments on check/config, and the IndexNowKit\Console\Command\* classes are family-level, and the notes state the Yii3 package registers the very same command classes. That cross-framework parity is a real asset: behavior we validate on Symfony carries to Laravel, and the optional-package detection logic now lives in core (OptionalPackage::sitemap() / verify() / history()), so a Laravel adapter gets the same fix for free.

Migration path. Because service ids are stable and only classes moved, the safe sequence is: pin the current bundle, grep for direct references to the removed FQCNs (SymfonyBundle\Command\, SymfonyBundle\Check\SampleOptions, VerifySampleCheck, LocalesCheck, EntitySampler), and for decorates: on any indexnowkit.console.* id; rewrite those to runner decoration or same-name command registration; then bump core, console, and history together, then the bundle.

Compatibility. PHP 8.x with psr/clock available, Symfony DI with service closures, and — for the debounce/throttle semantics to be meaningful — a shared clock. Where we run without indexnowkit/sitemap, verify, or history, 0.15.0 is strictly better than before: the prior build was a fatal during container compilation (Class "IndexNowKit\Sitemap\Adapter\SitemapServices" not found) because the config tree asked the optional packages' own *Services::package() whether they were installed. That is now routed through core's Adapter\OptionalPackage, with a CI job that removes all three and boots with detection.

Sequencing.

1. Adopt indexnowkit.clock and wire a FrozenClock in test/CI environments via compiler pass — do this before touching other behavior so time-sensitive tests become the safety net for the rest of the upgrade.
2. Inventory and rewrite direct class references and decorates: targets.
3. Upgrade core → console → history → bundle as one atomic change; assert composer why-not is clean.
4. Add our own CI variant that boots without each optional package, mirroring OptionalPackagesDetectionTest.
5. Turn on the new indexnowkit.check.locales (router.locales) warning in the deploy pipeline's indexnow:check run.

Operational Impact

Maintenance. Net positive. Deleting the bundle's byte-identical copies of core/packages classes and the nine literal 'memory' / 'none' comparisons (now DebounceStoreFactory::isShared()) means one implementation to patch, not four across framework adapters. The cost is tighter coupling: a core, console, or history bug now reaches us without an intermediate bundle release, and our upgrade cadence becomes their release cadence.

Support. Pre-1.0 across the family. The release notes read as an audit burn-down (references like "audit 0.13 A5", "W14", "S12"), which is healthy but implies continued churn through 0.x. The conflict on older core/console/history is the right guardrail; we should mirror it in our own constraints rather than relying on ^ resolving sanely.

Scaling. The clock change is behaviorally neutral at request scale but materially improves correctness under concurrency: throttle windows, debounce windows, and submission-record timestamps now derive from one source. The locale fix also removes a silent under-submission — #[IndexNow(locales: 'all')] against an empty framework.enabled_locales used to emit a single unlocalized URL instead of one per locale, quietly halving (or worse) our IndexNow coverage.

Failure modes to watch.

• Unshared clock service → windows drift, FrozenClock tests pass while production misbehaves.
• Empty framework.enabled_locales with locales: 'all' → now warned by both indexnow:check and the router bridge (once per process, indexnow channel), but still a silent URL collapse if nobody reads the log. Alert on the router.locales code.
• Stale compiled container with debug: false: the functional suite now fingerprints bundle sources into the cache path precisely because Symfony never freshness-checks a compiled container in that mode. Our own deploy pipeline needs the same discipline, or a bundle edit deploys against the previous container.
• Profiler panel store failures: previously printed the raw exception message, potentially including DSN credentials. Now shows class plus a masked message consistent with indexnow:config. Real security exposure closed — but only for this bundle; audit our other diagnostics panels for the same leak.
• Messenger transport: the in-memory transport now runs ?serialize=true, so messages and stamps are genuinely encoded/decoded. Previously they round-tripped as the same object, which would have hidden serialization regressions until a real transport hit them.

Ramp-up. Moderate — one to two engineer-days for someone comfortable with Symfony DI and compiler passes, longer for a Laravel-only team that has to reason about the Symfony reference implementation as documentation. Required background: PSR-20 (clock), PSR-11 (why the locator went away), service decoration versus command replacement, and the --sample gate's SampleGateCheck semantics. The payoff is a codebase where the integration surface we own is service ids and command contracts — the most stable thing the family offers at 0.x.