mulertech/seo-bundle
SEO toolkit for Laravel: manage meta tags, Open Graph, Twitter cards, canonical URLs, robots directives, JSON-LD structured data, and XML sitemaps from one bundle. Blade helpers keep head markup clean and consistent across pages.
Architecture fit. The package is a thin rendering layer: a global helper schema_org_json_ld($type, $payload) that emits a schema.org JSON-LD <script> block. That is a good fit for Laravel's helper/Blade idiom — no service provider ceremony, no container coupling, callable from controllers, Blade views, or API resources. The one real architectural commitment is BlogPostingSeoInterface, which requires application models (or DTOs) to implement a package-owned contract. That is an inversion the app has to accept; it is reasonable for a single type but should be checked for how many models it touches.
Integration feasibility. Low effort. Existing call sites already exist for at least four types (blogPosting, service, breadcrumbList, faqPage), so this is an upgrade of an in-use dependency rather than a greenfield integration. The FAQPage addition is the only new capability and is a straightforward {question, answer} list.
Technical risk. The headline risk in v1.6.0 is that silent no-render became a thrown InvalidArgumentException. Every previously tolerated malformed payload — a service without a string title, a breadcrumb item missing a key, a non-BlogPostingSeoInterface object — now throws instead of quietly emitting nothing. That is a genuinely good change for SEO observability (the release notes are right that broken blocks previously went unnoticed until an audit), but it is behaviourally breaking: any production path fed by user- or CMS-authored data that was quietly degrading will now surface as an exception, likely a 500. Second risk: answer passes through as HTML. That is an explicit trust boundary pushed onto the application — markdown rendering and sanitisation are now our responsibility, and any unescaped </script> or attribute breakout in that HTML has to be handled by the package's JSON encoding. Third: a Service without a description no longer emits "description": "" — correct semantically, but it changes emitted markup, so snapshot tests and any downstream structured-data assertions will need updating.
Key questions.
JSON_HEX_TAG / JSON_UNESCAPED_SLASHES handling — so that HTML in answer cannot break out of the <script> context?InvalidArgumentException the only exception type, and is it distinguishable from unrelated SPL usage in catch blocks? A dedicated subclass would be safer to catch.breadcrumbList and faqPage the only types where an empty list is a legitimate no-op? Is that documented per type?Stack fit. Standard Composer dependency for a Laravel application; no database, queue, cache, or filesystem footprint. The only runtime coupling is the helper's global function name, which is collision-prone if another package defines schema_org_json_ld — worth a quick check.
Migration path. Treat this as a behaviour-changing minor, not a patch. Steps: (1) pin the current version and inventory every call site by type; (2) for each site, classify the data source as developer-controlled (safe) or user/CMS-controlled (needs validation); (3) run the application test suite against v1.6.0 and reconcile snapshot/markup assertions with the dropped empty description; (4) add a boundary validation or a try/catch at user-controlled sites before deploying.
Compatibility. Two contract obligations to verify: models passed as blogPosting must implement BlogPostingSeoInterface, and service payloads must carry a string title. Both were previously forgiving and are now enforced, so any test fixtures that relied on partial data will fail loudly — which is the point, but it means the upgrade cannot be validated by "the page still renders."
Sequencing. Ship the dependency bump and the call-site hardening in the same release, or harden first and bump second. Splitting them across releases creates a window where a CMS-authored FAQ item with a missing key takes down a page. The faqPage feature itself can land later, since it is additive and independent of the strictness change.
Maintenance. Small, self-contained surface — a helper and a handful of type renderers. The main ongoing cost is the interface obligation on models and keeping the sanitisation of answer in step with whatever markdown pipeline the application already uses. Low carrying cost.
Support. Support load shifts from "structured data silently missing" (invisible until an SEO audit) to "page threw an exception" (visible immediately, and attributable to a specific malformed payload because the message names the expected shape). That is a net improvement in diagnosability, but it moves tickets from the SEO backlog to the on-call rotation. Whoever is on call needs to know these exceptions exist before the upgrade ships, not after.
Scaling. Negligible. String assembly and json_encode per request; no I/O. Only consideration is payload size for large faqPage lists, which is unlikely to be material.
Failure modes.
InvalidArgumentException on a page render — the dominant new failure mode, and the one to guard at user-controlled boundaries.answer breaking out of the script context or emitting invalid JSON-LD — a security and correctness risk that sits with the application, not the package.breadcrumbList / faqPage rendering nothing — deliberate and correct (Google rejects empty blocks), but it is a silent path, so observability for "why is my FAQ not showing in search" does not improve.service output (no empty description) breaking snapshot tests or downstream consumers that asserted on the old markup.Ramp-up. Low for developers already calling the helper — the API shape is unchanged. The learning is conceptual: contributors must internalise that malformed data now fails fast, that answer is raw HTML requiring sanitisation upstream, and that empty lists are the one remaining silent no-op. A short note in the team's structured-data conventions is sufficient; no dedicated training needed.
How can I help you explore Laravel packages today?