Laravel Storyblok Laravel Package

Product Decisions This Supports

• Headless CMS architecture choice: whether Storyblok (rather than a database-backed CMS or Contentful/Sanity) is our content source for Laravel-rendered sites — this package is the adoption enabler, not just glue.
• Build vs buy for the integration layer: it supplies the Storyblok Content Delivery API client, Eloquent-like "Story" models, relation resolution, image transformation helpers, preview/draft mode, and webhook-driven cache invalidation. In-house equivalents typically cost 2–6 engineering weeks plus ongoing maintenance as Storyblok's API evolves; this is a buy/reuse decision, not a build one.
• Content-model velocity on the roadmap: lets Marketing ship page structures, landing pages, blogs, docs and navigation changes in Storyblok without Laravel deploys — a recurring roadmap unblocker.
• Multi-site / localisation and preview workflows: supports per-locale content and editor preview against staging, which are prerequisites for internationalisation and content-team autonomy.
• Internal linking and SEO integrity: 3.0.3 fixes link resolution — the mechanism turning Storyblok story/asset/email links into real URLs inside richtext and navigation. Broken link resolution is a traffic and SEO defect (broken nav, dead CTAs, orphaned pages), so this is a customer-facing correctness fix rather than cosmetic.
• Risk register, not just feature list: the package is small and effectively single-maintainer; each release is a signal about maintenance health, and patch cadence feeds the "adopt vs fork vs wrap" call.

When to Consider This Package

Consider it when:

• The application is Laravel/PHP (reasonably modern Laravel) and Storyblok is the chosen or shortlisted headless CMS.
• You want Eloquent-idiomatic access to stories, Blade/component rendering, and caching that fits Laravel's cache and HTTP layers rather than a bespoke REST wrapper.
• You need the specifics this package covers: link resolution in richtext/navigation, resolve_relations for nested content, Storyblok image service URLs, draft/preview mode, and webhook-triggered cache invalidation.
• Your team is small and prefers a thin, readable adapter over a heavy abstraction, and is comfortable pinning a Composer version and running its test suite against your content models.
• Time-to-first-page matters: the alternative is weeks of API client, caching, and link-parsing work that is not your differentiator.

Look elsewhere or plan mitigation when:

• The frontend is not Laravel (Nuxt/Next/JS) — use Storyblok's official JS SDK or a plain PHP client instead; this package's value is its Laravel integration.
• You need the Management API (content migrations, schema automation, programmatic publishing) — this is a delivery-side tool.
• You need edge/static rendering or vendor SLAs: Storyblok's CDN plus SSG, or a commercially supported integration, may fit better than a community package.
• Bus factor is unacceptable without a plan. Adopt only alongside one of: pinning and wrapping behind an internal interface, a fork you own, or an agreed upgrade/test budget. Recent releases are patch-level only (3.0.3 fixes link resolution); there is no evidence of new 3.x features or deprecations, so treat the dependency as mature-but-quiet rather than actively expanding.

How to Pitch It (Stakeholders)

For executives: This is a small open-source Laravel adapter that lets us use Storyblok as our CMS without building the integration ourselves — saving several weeks of engineering and giving Marketing direct control of page content, localisation, and previews. Cost is zero licence, low lock-in (it wraps a REST API we could replace), and the risk is bounded because it is a thin layer over a documented vendor API. The latest release, 3.0.3, is a patch-level bug fix for internal link resolution only — no new features, no breaking changes, no data migration. It is safe to adopt or upgrade by pinning the version and running our standard test pass; the one risk to note is that the package has a small maintainer base, which we mitigate by pinning and keeping the option to fork.

For engineering: Semver-compatible patch release; upgrade path is a Composer bump with no code changes expected. The fix targets link resolution — exercise richtext bodies, navigation menus, and asset/email links in regression tests, and verify preview mode still resolves draft links. Keep the package behind a thin internal interface where practical, pin the version in composer.json, and track upstream issue responsiveness so we can fork if maintenance stalls.