Statamic Choices Laravel Package

Getting Started

statamic-choices is a Statamic addon (verified against Statamic v5 and v6) distributed as a Composer package. It ships a prebuilt Control Panel Vite bundle, so there is no Node build step on your side.

1. Install with Composer:

   composer require <vendor>/statamic-choices
   

2. Confirm the CP assets were published to public/vendor/statamic-choices/build. The v0.1.1 release adds an automatic publish step during composer install, so a fresh composer require should leave you with a working Control Panel without manual asset commands.
3. Look first at:
   • config/statamic-choices.php (if published) for option/config defaults.
   • resources/views/ for the fieldtype’s rendering templates.
   • src/Fieldtypes/ for the fieldtype class and its expected option schema.
4. First use case: add the Choices fieldtype to a blueprint, define its options, and render the stored value in an Antlers template. This is the fastest way to validate installation, asset publishing, and field configuration end to end.

Implementation Patterns

Blueprint-first configuration. Define Choices fields in your blueprint YAML and keep option lists close to the field. This is the normal Statamic workflow and avoids scattering option definitions across PHP and templates.

Reusable option sources. For option sets shared across blueprints, centralise them in config or a small service/provider rather than duplicating YAML. Keep the field’s stored value format (single value vs. array for multiple selections) consistent across blueprints.

Antlers rendering. Treat the field like any other Statamic field: access it through the entry, guard for empty values, and use conditionals for display logic. For multi-select fields, loop over values rather than assuming a scalar.

Programmatic access. In Laravel code, read the field from the entry and use Statamic’s augmented values when you need labels rather than raw stored keys. Keep raw values for persistence and augmented values for presentation.

Validation. Add validation rules in the blueprint or form submission layer that match the field’s cardinality: a single-select field should validate as a scalar, multi-select as an array of allowed options. Validate against the allowed option keys, not labels.

Deployment workflow. Let composer install run normally in your build/deploy pipeline so the packaged Vite assets publish. If your pipeline commits public/vendor, include the published build output; if it doesn’t, ensure the publish step runs on every deploy that refreshes public/vendor.

Local vs. production. Because the package ships a prebuilt Vite bundle, production does not need Node or a frontend build. Local development only needs Composer unless you are overriding the package’s views or assets.

Gotchas and Tips

• Auto-publishing is tied to Composer scripts. composer install --no-scripts, some CI configurations, and certain deploy tools skip script hooks. If the Control Panel shows Vite manifest not found, verify public/vendor/statamic-choices/build/manifest.json exists and re-run the publish step.
• Deployments that wipe public/vendor. If your deploy process cleans generated public assets, the addon’s CP bundle disappears with them. Add an explicit publish step or ensure Composer runs after the clean.
• Permissions. Publishing during Composer can create files owned by the deploy/CI user. If the web server cannot read public/vendor/statamic-choices/build, you will get asset 404s or manifest errors even though the files exist.
• Caches after install or upgrade. Clear Laravel and Statamic caches after updating the package, and refresh Statamic’s addon discovery if the fieldtype does not appear in the blueprint editor. View and config caches can also mask newly published templates/config.
• Pre-1.0 API stability. At v0.1.x, treat the package as early-stage. Pin the version in composer.json, read release notes before upgrading, and avoid relying on internal classes or view names that are likely to change.
• Manual publish fallback. If automatic publishing fails, use the package’s vendor publish tag/provider to publish assets and config manually. Check php artisan vendor:publish output for the exact tag rather than guessing.
• Extension points. Prefer overriding published views/config over editing files inside vendor/. Re-publish after package upgrades so your overrides stay in sync with upstream changes.
• Debugging checklist for CP asset failures: confirm the package is discovered, confirm the build directory exists under public/vendor/statamic-choices/build, check file permissions, clear caches, then hard-refresh the Control Panel.