Resource Bundle Laravel Package

Technical Evaluation

Architecture fit — poor to moderate, with a caveat. Despite being surfaced in a PHP/Laravel package scan, atoolo/resource-bundle is a Symfony bundle, not a Laravel package. The 1.0.0 changelog is explicit: "transform to symfony-bundle", and later entries reference Symfony 6 support, autowiring, and namespaced service ids (atoolo_resource.resource_channel, atoolo_resource.resource_host). There is no extra.laravel auto-discovery, no Laravel service provider, and no facade. The domain concept — reading pre-produced, filesystem-backed content aggregates from an IES (Sitepark CMS) export, with caching and hierarchy traversal — is portable. The implementation is not: it assumes Symfony's DI container, config tree, and env-var processing (RESOURCE_ROOT).

Integration feasibility — feasible only via one of three deliberate paths. The core read path (Resource, DataBag, ResourceLocation, ResourceChannel/Language/Tenant, CachedResourceLoader, ResourceHierarchyWalker/Finder) may be largely plain PHP, but I need to verify how much Symfony coupling exists in the loader and cache layers before committing. Practical options: (a) run a sidecar Symfony app and expose resource reads over HTTP/queue, (b) Composer-install the bundle into Laravel and hand-wire its classes in a custom service provider, or (c) reimplement the read path against the on-disk format. Option (c) is blocked until we can see the data contract, which the README does not define.

Technical risk — high, concentrated in vendor dependency and zero external validation. Stars: 0. Dependents: 0. There is no community corpus, no third-party usage to learn from, and no Stack Overflow footprint. The documentation lives on a vendor-controlled site (sitepark.github.io/atoolo-docs), not in the repo. Release history shows sustained churn: service renames, namespace moves (atoolo-resource-loader → atoolo-resource), factory namespace refactor, a provide: atoolo/runtime-check-bundle that was added then removed. That is normal for an internal-first library but means upgrading is not free. Positive counter-signals: MIT license (forkable), PHPStan level 9, Codecov badge, an E2E suite in a sibling repo, and a broad PHP matrix (8.1–8.4, with 8.5 claimed in 1.9.0). One data anomaly to resolve before planning: the "last release" is dated 2026-10-28, which is in the future relative to any plausible review date — treat the release metadata as unreliable until verified.

Key questions to close before commitment:

• Is RESOURCE_ROOT a shared POSIX volume/NFS, or a synced artifact directory? This determines the entire scaling story.
• Who owns the producer side (IES export pipeline), and what is the refresh SLA and schema-versioning contract?
• What is the on-disk format and is it documented anywhere public, or only in vendor docs?
• Does the bundle work standalone without atoolo/runtime-check-bundle, given it was removed as a provide?
• How does "supports the deletion of loader caches" interact with our cache topology — is invalidation push, pull, or manual?
• Is there a commercial support agreement available with Sitepark? A 0-star, single-vendor, single-org package in a production critical path needs one.
• Does ResourceLocation::ofPath() (added 1.4.0) validate against path traversal?

Integration Approach

Stack fit. Target Laravel 10/11 on PHP 8.1–8.3. The bundle's PHP floor (8.1) is compatible; "no longer checked automatically" on 8.1 in the badge line is a mild warning that 8.1 support is decaying. The real friction is dependency surface: pulling this bundle drags in Symfony components (config, dependency-injection, cache-contracts, possibly http-kernel) that Laravel already pins to specific majors. Expect Composer conflict resolution work, and expect it to recur on every Laravel major upgrade.

Migration path — recommended sequencing of the three options:

1. Sidecar Symfony service (fallback / fastest to prove). Deploy the bundle in a minimal Symfony app, expose a narrow read API. Lowest coupling, no dependency bleed into the Laravel app, but adds a network hop and a second runtime to operate. Acceptable as a bridge, not as a destination.
2. In-process adapter (preferred if coupling is shallow). Install the bundle, write a Laravel ServiceProvider that registers the loader classes and binds RESOURCE_ROOT from config, and wrap the whole thing behind an internal ContentRepository interface so the rest of the app never imports vendor types. This is the option that survives a future rip-and-replace.
3. In-house reimplementation (destination if the format is stable). Only viable once we have the on-disk schemal; would remove the vendor runtime entirely while keeping the data pipeline.

Compatibility checks to run in the spike, not later:

• Resolve symfony/* constraints against the current composer.lock and confirm no downgrade of Laravel's own Symfony dependencies.
• Confirm whether the cache layer binds to Symfony cache contracts (CacheInterface) or a concrete adapter — this decides whether we can back it with Laravel's cache or must run a separate pool.
• Confirm RESOURCE_ROOT is read via Symfony's EnvVarLoader/EnvVarProcessor only, or whether it can be set through ordinary config injection. If the former, the Laravel adapter must emulate Symfony env processing — a real but bounded piece of glue.

Sequencing (roughly 4–6 weeks for one engineer, plus vendor coordination):

1. Week 1 — spike. Install, populate a fixture resource tree, load a Resource, a hierarchy, and a missing-language fallback inside a Laravel app. Kill criterion: unresolved Composer conflicts or a hard requirement on Symfony's kernel.
2. Week 2 — contract. Get the producer-side schema and refresh cadence in writing from the IES/Sitepark owners. No adapter work before this exists.
3. Weeks 3–4 — adapter. ContentRepository interface, Laravel provider, cache binding, error mapping for the bundle's exceptions.
4. Week 5 — dual-read. Feature-flagged rollout, shadow reads against the existing content path, diff the outputs.
5. Week 6 — cutover and runbook.

Operational Impact

Maintenance. Vendor-owned with a small maintainer set (@sitepark-veltrup dominates the commit log). Expect breaking-ish changes in minors — service ids and namespaces have already moved twice. Mitigations: pin exact versions, read every changelog, and pre-agree that we will fork under MIT if the vendor stalls. Budget roughly 2–4 hours per upgrade cycle for regression testing against the fixture tree.

Support. Effectively none beyond a direct vendor relationship. No community, no dependents, no issue-tracker corpus to mine. If this is production-critical, a commercial agreement with Sitepark is a prerequisite, not a nice-to-have. Internally, name a single owner for the adapter layer so knowledge does not evaporate.

Scaling. The read path is inherently cheap — pre-produced data, filesystem reads, a cache layer bolted on top. That is the package's genuine architectural virtue: content delivery costs no database round-trip. Horizontal scaling holds if RESOURCE_ROOT is a shared volume or a replicated artifact synced at deploy time; if it is node-local, you get silent per-node divergence. Watch three things: cold-cache stampede after a resource republish, unbounded hierarchy walks (ResourceHierarchyWalker/Finder) on deep trees, and cache directory growth on long-lived nodes without the deletion hook wired up.

Failure modes to instrument and alert on:

• Missing RESOURCE_ROOT — explicitly handled by the bundle since 1.0.0, but "handled" likely means a thrown exception at boot. Fail fast and loudly; do not let it degrade to empty content.
• Missing translation — silently falls back to the default language (1.0.0 feature). Correct behavior, wrong-language output if unmonitored. Log the fallback with the resource id and requested language.
• Malformed resources — 1.0.0 advertised "more robust loading against various invalid resources," which tells you invalid records are an expected condition. Emit a metric per skipped resource; a rising count is a producer-side regression signal.
• Circular parent references — detected (1.1.0), but detection implies a throw. Catch at the repository boundary and return a partial tree rather than 500ing a page.
• Stale cache after republish — the highest-probability production incident. The cache-deletion hook must be wired into the publish pipeline, not run manually.
• Path traversal via ResourceLocation::ofPath() (1.4.0) — validate any caller-supplied path input even if the library claims to.

Ramp-up. Documentation is off-repo and vendor-hosted; the README is a badge wall plus two sentences. Expect 1–2 weeks for a competent Laravel engineer to internalize the resource model (Resource, DataBag, Channel, Language, Tenant, Location, Hierarchy) and produce working code. Add time for whoever owns the producer side to explain the export. The absence of in-repo examples is the single biggest onboarding tax here and is cheap to fix internally: commit the spike's fixture tree and a worked example to our own repo on day one.