Statamic Storychief Laravel Package

Getting Started

• Install with composer require storychief/statamic-storychief. Statamic addons are auto-discovered; no manual provider registration should be required.
• Publish the config: php artisan vendor:publish --tag=storychief-config (confirm the tag in the README). The config file is the first place to look — it typically holds the webhook secret, target collection, field mappings, asset container, and author assignment.
• Set the shared secret in .env (e.g. STORYCHIEF_WEBHOOK_SECRET=...) and point StoryChief's webhook/channel at the route the addon registers (/storychief/webhook or similar — check routes/ in the package). On Laravel 11+, ensure that route is excluded from CSRF in bootstrap/app.php; on Laravel 10, add it to VerifyCsrfToken::$except.
• First use case: create a blog collection with fields you expect StoryChief to send (title, slug, content/bard, excerpt, featured image, SEO meta). Configure those handles in config/storychief.php, then use StoryChief's "test" publish to create a draft entry. Verify the entry, image, and SEO fields land correctly before wiring production channels.
• Run php artisan config:clear && php artisan stache:clear after config changes — Statamic will otherwise serve stale collection/blueprint definitions.

Implementation Patterns

• Field mapping is config-driven, then code-driven. Start by declaring StoryChief payload keys → Statamic field handles in config. When you need per-article logic (e.g., different collections by storychief.channel), bind a custom controller or listen to the package's import event and mutate the entry before save.
• Idempotent upserts. StoryChief will re-send on updates. Persist the remote article ID in a hidden field (e.g. storychief_id) and look up the existing entry by that field before creating. Without this you get duplicates on every edit.
• Content conversion. StoryChief sends HTML. If your blueprint uses Bard, convert HTML → Bard sets (Statamic 4+ ships htmlToBard(), or use a dedicated converter) rather than dumping HTML into a Markdown field. If you keep raw HTML, render with {!! $entry->content !!} inside a sanitized scope.
• Assets. Featured images usually arrive as URLs. The addon typically downloads them into a configured asset container; make sure the container exists, the disk is writable, and filenames are hashed to avoid collisions. For reliability, move the download into a queued job dispatched from the webhook so StoryChief's request returns fast.
• Author and status. Map StoryChief's author to a Statamic user (or fall back to a system user). Respect a draft/published flag in the payload rather than always publishing.
• Multisite. If you run multiple sites, key the target site off the payload's locale and set site on the entry before save.
• Local development. Use ngrok/expose or StoryChief's manual "send test" to hit your local route. Wrap the payload in a feature test with Http::fake() and a signed request so regressions are caught in CI.
• Events as extension points. Rather than editing vendor code, listen for EntrySaved (or a package-specific event) to trigger search indexing, CDN purges, or notifications after import.

Gotchas and Tips

• Treat it as a small package. With very low star count and dependent count, pin the version in composer.json, review the source before deploying, and be prepared to fork. Check the actual release cadence against the repo rather than trusting the listed date.
• Signature verification. Confirm the addon actually validates the webhook secret with a constant-time comparison. If it doesn't, add middleware — an unauthenticated route that creates entries is a content-injection vector.
• Field handle mismatch fails silently. A typo in a mapping key just drops data. Log the raw payload in non-production and diff it against your blueprint.
• HTML sanitization. StoryChief output can contain tags Bard doesn't model (embeds, custom blocks). Sanitize with an allowlist (mews/purifier) and test a real post end-to-end; otherwise content is silently truncated during conversion.
• Image re-downloads. On updates, avoid re-fetching and re-uploading the same asset. Match by remote URL stored in asset meta or by a hash of the filename.
• Caching. If you use Statamic's static cache or a CDN, invalidate after import. Also consider stache:warm in deploy scripts.
• Timeouts and payload size. Large images and long posts can exceed PHP/webhook timeouts. Queue the heavy work and return 200 immediately.
• Permissions. The configured author may lack permission to publish to a collection, and the asset container needs write access for the web server user. Test with the same user the queue/CLI runs as.
• Extension points to prefer: config overrides, route/controller binding, events/listeners, and published views. Avoid patching vendor/; if you must, use a Composer patch plugin so it survives composer update.