Statamic Bard Openai Laravel Package

Getting Started

Assumes a working Statamic project (v3+) with a Bard field already rendering in the control panel.

1. Install the addon into the Laravel project:

   composer require zsoltjanes/statamic-ai-writer-for-bard
   

   Statamic auto-discovers addons via the extra.statamic block in the package's composer.json; you normally won't need to register a service provider manually. If discovery ever fails, check config/app.php / Statamic's addon cache (php artisan statamic:addons:discover).

2. Provide an OpenAI key. Add to .env:

   OPENAI_API_KEY=sk-...
   

   If the addon ships a config file, publish it and inspect the defaults before wiring anything else:

   php artisan vendor:publish --provider="ZsoltJanes\StatamicBardOpenAI\ServiceProvider"
   

   Look first at the config for: the env key it reads, the default model, and any max_tokens/temperature values.

3. Enable it on a Bard field. Open the relevant fieldset YAML (e.g. resources/fieldsets/article.yaml) and add the addon's toggle to the Bard config — typically an ai/openai key under the field, or a bard button option, depending on the version. Since the addon is young and lightly documented, the fastest way to confirm the exact key is to read the fieldtype/button source inside vendor/zsoltjanes/statamic-ai-writer-for-bard.

4. First use case: in the CP, open an entry with the Bard field, click into the editor, and use the AI control to generate or continue a paragraph from a prompt. Edit the result inline as you would any Bard content, then save — the generated content is stored as normal ProseMirror/Bard content, so nothing about your templates or Antlers changes.

Before relying on it: confirm the exact Statamic/PHP versions in the package's composer.json, and confirm the model string it defaults to is one your OpenAI account can access.

Implementation Patterns

Field-level scoping. Don't enable AI on every Bard field. Turn it on only for fields where a draft-then-edit workflow makes sense (body copy, teasers, meta descriptions) and leave structured/legal/boilerplate fields untouched. Because the toggle lives in the fieldset, you can ship one fieldset with AI and another without and assign them per-collection.

Draft → human edit → publish. Treat the addon as a first-draft generator, not a publisher. The realistic loop is: prompt for a paragraph, regenerate or extend a selection, then rewrite for voice. This keeps you inside OpenAI's content policy and your editorial standards, and it keeps Bard's structural elements (sets, Replicator blocks) sane, because AI output arrives as flat prose that you promote into sets manually.

Prompt conventions. Keep prompts short and imperative ("Rewrite this in a concise B2B tone", "Expand to 120 words"). If the config exposes a system prompt or model, fork it per environment so local/staging use gpt-4o-mini (or your cheapest current model) and production uses the higher-quality model. If the config does not expose a model override, wrap calls yourself rather than editing vendor files.

Content-type awareness. Bard content includes sets (image, quote, embed blocks). AI generation is only useful for the text-bearing parts. When drafting inside a Bard field that has sets configured, keep the generated prose in a plain paragraph block and convert to sets afterwards.

Environment/config parity. Mirror the config file into config/ (published) and drive values from env so each environment can point at different models and token caps. This is the single biggest lever for controlling spend across local, CI, and production.

Programmatic reuse. If the addon exposes a service/action (check src/), you can call the same generation logic from a custom command or a queued job to backfill content, rather than only from the CP button. If it doesn't, write your own thin OpenAI client and use the addon only for the CP affordance.

Guardrails for editors. If the addon doesn't already gate the feature, pair it with Statamic permissions so only trusted roles see the AI control, and document expected cost-per-click for the team.

Gotchas and Tips

• Cost is per keystroke-adjacent. Every generation is a billed API call. Set a low max_tokens and a cheap model by default; raise quality deliberately. Watch the OpenAI usage dashboard after the first week — a 3-star addon won't have spend controls built in.
• Output is prose, Bard wants structure. Bard persists ProseMirror JSON, not markdown. AI output typically comes back as markdown/plain text; headings, lists, and emphasis may not map to Bard marks. Expect to clean up formatting after generation rather than trusting it verbatim.
• Silent failures. Small addons often swallow OpenAI errors (rate limits, invalid key, deprecated model) and leave the CP looking like nothing happened. When a generation no-ops, check storage/logs/laravel.log and the browser network tab for the request to your app, then test the key directly against OpenAI.
• Model deprecation. Hard-coded model strings rot. If the config pins a model, verify it's current before each deploy; better, make it env-driven.
• Latency and timeouts. Non-streaming calls can take 10–30s. If you're behind a proxy/LoadBalancer with a short timeout, generation gets cut off. Confirm PHP max_execution_time and any gateway timeout are generous enough.
• Key hygiene. Never commit .env; scope the OpenAI key to the minimum required and rotate it. Since the key sits server-side, the CP never sees it — good — but don't expose generation endpoints to unauthenticated routes.
• License is NOASSERTION. Verify the actual license terms in the repo before commercial deployment; "no license" is a legal risk, not a green light. With 0 dependents and 3 stars, treat this as a fork-and-own dependency: pin the version in composer.json, and be prepared to maintain a local patch.
• Extension points. The config file (if published) is the safe customization surface — prompts, model, tokens. Avoid editing vendor/; if you need behavior changes, subclass or fork. Check the package's event/listener usage in src/ for hooks before assuming none exist.
• Multisite. If you run Statamic multisite, verify the field config and API key work per-site; addon config is usually global, but generation endpoints may infer the current site and behave inconsistently.
• No test coverage signal. With a single maintainer and no dependents, build a smoke test of your own: one Bard field, one generation, one save, verify the stored content renders correctly on the front end through your Antlers templates.
• Debugging tip: reproduce generation outside the CP with a direct curl to https://api.openai.com/v1/chat/completions using the same key and model, so you can separate addon bugs from OpenAI-side issues.