Statamic Chatgpt Integration Laravel Package

Getting Started

This is a Statamic addon (not a standalone Laravel package), so you'll use it inside a Statamic 3/4 site running on Laravel. v1.0.2 is the first public release, so treat it as early-days software: read the source before trusting it in a client project.

1. Install

composer require stack83com/statamic-chatgpt-integration

Then publish the addon's config (check for a config/statamic/chatgpt.php or similar in the repo — the release notes reference env-driven model selection, which implies a config file is shipped):

php artisan vendor:publish --tag=statamic-chatgpt

2. Credentials Set your OpenAI key in .env. Never commit it, and never let it land in a CP-editable field:

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini

The v1.0.2 note "allow for other models through env" means the model is resolved from environment/config at runtime — so .env is your switchboard for model choice, not a per-field setting.

3. Where to look first

• The service provider (src/ServiceProvider.php) — confirms which fieldtype/controller/routes get registered.
• The fieldtype class — that's the surface you'll actually touch in the Control Panel.
• The config file — the only place model/temperature/limits are likely configurable right now.

4. First use case Add the fieldtype to a blueprint (e.g. an article collection's intro field), open an entry in the CP, and use the assistant to draft or rewrite copy in place. The v1.0.2 snackbar work (copy-to-clipboard + error messages) confirms the primary interaction is in-CP text generation with a copy button — an editor-assist tool, not a headless API client.

Implementation Patterns

Blueprint-first, not code-first. There's no evidence of a public PHP API in this release. The realistic integration point is the CP fieldtype, added via the Blueprint editor or YAML:

intro:
  type: chatgpt   # verify exact handle in the repo
  display: Intro

Don't plan on calling this from a controller or console command until you've read the source and confirmed a callable service class.

Model selection per environment. Because v1.0.2 moved model choice to env, use that deliberately:

# local / staging - cheap, fast, less scary to experiment with
OPENAI_MODEL=gpt-4o-mini
# production - only bump when you've validated prompt quality

Keep a .env.example entry so new team members don't hit a silent failure on first use.

Content-editor workflow. The copy snackbar suggests a generate → review → paste loop rather than direct field writes. Encourage editors to treat output as a draft: generate, copy, edit, save. This also sidesteps any risk of the addon overwriting existing field content.

Client handover pattern. For agency work, gate the fieldtype behind a permission or only include it in blueprints for specific collections. Editors who don't need it shouldn't see a "generate" button on every field — it burns tokens and invites accidental use on sensitive entries.

Cost guardrails. Since there's no visible quota/caching layer in this release, keep usage to short fields (intros, meta descriptions, alt text, summaries) and use the cheapest model that passes your quality bar. Long-form generation through a CP fieldtype is where bills creep.

Version pinning. Pin explicitly in composer.json rather than floating:

"stack83com/statamic-chatgpt-integration": "^1.0"

The Statamic 4 support landed mid-release-cycle (PRs #5/#6), so the 1.0.x line is where the compatibility churn is happening.

Gotchas and Tips

Statamic 4 vs 3 compatibility. The addon was initially Statamic 3, with Statamic 4 support added in this release. If you're on Statamic 3, confirm the version constraint in composer.json before upgrading the addon — a loose constraint could pull a build that assumes v4 APIs. Check composer why-not if the install refuses.

Fieldtype handle naming. PR #2 is literally "Fix naming issue." Expect the fieldtype handle, config keys, or translation keys to have shifted between the first commit and 1.0.2. If you installed anything pre-1.0.2, re-check your blueprint YAML against the current source rather than assuming the handle is unchanged.

Env changes need a config cache clear. Changing OPENAI_MODEL or the API key won't take effect if config is cached:

php artisan config:clear

On production deploys, remember config:cache runs — an env var set only in the shell and not in the deploy's .env will read as null.

Errors surface in snackbars, not logs. The v1.0.2 snackbar covers error messages, which is editor-friendly but developer-hostile. When something fails, don't hunt the CP toast — check storage/logs/laravel.log, and be ready to add temporary logging around the addon's HTTP call. Common causes: invalid/expired key, no billing set up on the OpenAI account, wrong model name string, or network egress blocked from the server.

Server-side request, sync, and timeouts. Generation almost certainly happens synchronously in the request cycle. Long prompts + a slow model = a hanging CP request. Keep prompts short, prefer faster models, and if you hit timeouts look at your PHP max_execution_time and any proxy/queue in front of the app.

No caching layer. Nothing in these release notes suggests response caching or rate limiting. Identical prompts will be billed every time. If you need deduplication or audit trails, that's on you — wrap it at the application level once you've confirmed whether the addon exposes a service you can call.

Key handling and leakage. The API key is server-side, which is correct — but verify the generated content isn't posted anywhere it shouldn't be, and don't let editors paste customer PII into a field that will be sent to OpenAI. Consider a note in your editor onboarding.

Early-stage maintenance risk. Single contributor, first release, six PRs. Before adopting: check the issue tracker and last-commit date, and have a fallback plan (the OpenAI HTTP call is straightforward to reimplement in a custom fieldtype if the addon stalls). For client work, prefer it on low-stakes fields and keep your own thin wrapper if you need it embedded in business logic.

Extension points to watch. The likely seam is the service/HTTP client class behind the fieldtype. If v1.x exposes a resolvable service (e.g. via the container), that becomes your injection point for custom prompts, logging, or swapping providers — worth checking after install, as it determines whether this stays a CP toy or becomes infrastructure.