Statamic Fa Widget Laravel Package

Getting Started

v2.0.0 is the Statamic 5 compatibility line. Start by confirming your app is on Statamic 5, and that your PHP/Laravel versions satisfy Statamic 5’s requirements, before requiring ^2.0. If you are still on Statamic 4 or earlier, stay on v1 until the app upgrade is complete.

First places to look:

1. composer.json for statamic/cms, php, and laravel/framework constraints.
2. The package changelog/upgrade notes for migration, config, namespace, or registration changes.
3. The service provider/addon registration and any publishable config, views, or assets.
4. Any migrations, blueprints/fieldsets, fieldtype registration, or CP nav/permission changes.

First use case: install on a fresh Statamic 5 site or a staging copy, publish config/assets, register the addon/fieldtype, create one representative entry or field, and verify it in both the Control Panel and front end before touching production content. That proves the integration path end-to-end.

Implementation Patterns

• Upgrade in a branch: composer require vendor/package:^2.0, clear caches, republish only changed assets/config, run migrations, smoke-test CP and front end, then deploy.
• Treat package config as app config: keep it in version control, drive environment-specific values through .env, and diff published config instead of overwriting customizations.
• Use the package through Statamic’s normal content model—blueprints/fieldsets, CP configuration, Antlers/Blade rendering—and keep custom business logic in app classes rather than editing vendor code.
• For day-to-day work, model content once in a blueprint/fieldset, add a small fixture entry, and test rendering in both CP preview and front end. This catches most integration regressions.
• If the package exposes fieldtypes, tags, modifiers, or addon routes, register them through the normal service provider/addon manifest and keep permissions/nav configuration explicit.
• Add regression tests around saved content and rendered output, especially after a major compatibility bump. Cache expensive rendered output where the package allows it.
• For multi-environment setups, verify the same config keys exist in local/staging/prod and run the same cache-clear/deploy sequence in each.

Gotchas and Tips

• v2.0.0 is a major release. Do not assume v1 behavior carries over; pin ^2.0 only after confirming Statamic 5 compatibility.
• Statamic 5 has its own PHP/Laravel requirements. Check composer.json before upgrading; a package constraint mismatch often shows up as a confusing addon boot failure.
• Caches hide config/addon changes. Clear Laravel config/view cache and Statamic’s stache/cache after install or config edits.
• Re-publishing config or views can overwrite local customizations. Publish to a temp location or diff first.
• If the addon does not appear in the CP, check service provider discovery, addon registration, permissions, and logs before assuming the package is broken.
• Debug from the outside in: composer constraints, addon boot, config publication, fieldset/blueprint wiring, CP render, front-end render. Most failures are one layer earlier than they look.
• Extension points to prefer: publishable config/views, events/hooks, custom fieldtypes/tags, and app-level wrappers. Avoid vendor edits so the next Statamic major is cheaper.
• Keep a rollback path: old composer.lock, database backup, and a tested v1 branch until the Statamic 5 upgrade is verified in staging.