Weave Code
Storyblok Laravel Package
21torr/storyblok
Symfony bundle providing API helpers and infrastructure to work with Storyblok. Simplifies fetching content, integrating Storyblok services, and building Storyblok-powered Symfony apps. Includes documentation for setup and usage.
A Symfony integration for the Storyblok headless CMS
Frequently asked questions about Storyblok
- Can I use this Storyblok bundle with Laravel, or is it strictly for Symfony?
- This package is designed for Symfony, not Laravel. Laravel developers should explore alternatives like the official Storyblok PHP SDK or Laravel-specific packages like *spatie/laravel-storyblok*. However, if you're using Symfony components in Laravel (e.g., via Lumen or Symfony bridge), you could adapt this bundle with caution.
- How do I install and configure the StoryblokBundle in a Symfony project?
- Run `composer require 21torr/storyblok-bundle` and configure it in `config/packages/storyblok.yaml`. Define your Storyblok space token, API version, and adapter settings. The bundle includes console commands like `storyblok:sync` for managing content. Full setup instructions are in the [official documentation](https://21torr-docs.pages.dev/docs/php/symfony/storyblok/).
- Does this bundle support multiple Storyblok spaces in a single Symfony app?
- Yes, the bundle supports multiple spaces via the adapter pattern. Configure each space as a separate adapter in `storyblok.yaml` (e.g., `adapters: { space1: { api_token: ... }, space2: { api_token: ... } }`). Access content via dependency injection, specifying the adapter name when fetching stories or assets.
- How does the bundle handle Storyblok webhooks for real-time updates?
- The bundle validates webhooks using adapter-specific tokens (configured in your Storyblok space). You must set up a secure endpoint in Symfony (e.g., via `#[AsController]` or a dedicated route) to receive and process webhook payloads. Use Symfony’s Messenger component to queue updates asynchronously if needed.
- What Laravel version compatibility issues might I face if I try to adapt this for Laravel?
- This bundle relies heavily on Symfony’s dependency injection, configuration system, and console components—none of which are natively available in Laravel. You’d need to manually replicate these features (e.g., service containers, YAML config parsing) or use a compatibility layer like `symfony/console-bridge`, which adds complexity.
- Are there built-in caching mechanisms for Storyblok content in this bundle?
- The bundle itself doesn’t include caching, but it provides sync commands (`storyblok:sync`) to fetch and store content locally. For performance, pair it with Symfony’s cache system (e.g., Redis or APCu) to cache Storyblok responses. Use tags or events to invalidate cache when content updates via webhooks.
- How do I handle Storyblok API failures or offline scenarios in production?
- The bundle doesn’t include retry logic, so you’ll need to implement fallback strategies. Use Symfony’s HTTP client with middleware (e.g., retry, circuit breaker) for API calls. For offline scenarios, cache responses locally and implement a grace period or stale-while-revalidate strategy.
- Can I mock Storyblok responses for local development or testing?
- Yes, leverage the adapter pattern to create a custom mock adapter by implementing `AbstractStoryblokAdapter`. Override methods like `fetchStory()` to return static data or use tools like Storyblok’s local bridge. This is ideal for unit/integration tests or local development without hitting the Storyblok API.
- What are the breaking changes in version 5.0.0, and how do I upgrade?
- Version 5.0.0 removed global services like `ContentApi` and `ManagementApi`, requiring per-adapter configuration. Update your `storyblok.yaml` to define adapters explicitly and refactor service references in your code. Follow the [upgrade guide](https://github.com/21TORR/StoryblokBundle/blob/main/UPGRADE.md) for detailed steps.
- Does this bundle work with Symfony 6.4+, and what if I’m on an older version?
- The bundle is optimized for Symfony 6.4+ and PHP 8.4+, aligning with modern Symfony features like attributes and dependency injection. If you’re on an older version, you may encounter compatibility issues. Consider upgrading your Symfony runtime or using Docker to isolate dependencies.
Weaver
How can I help you explore Laravel packages today?