Statamic Activecampaign Laravel Package

Getting Started

v3.4.0 is primarily a compatibility release, so "getting started" depends on whether you're installing fresh or upgrading.

Requirements after this release (all three move together):

The Statamic floor is not arbitrary — 6.5 is the first Statamic release with Laravel 13 support. Do not try to pair Laravel 13 with Statamic 6.4 or earlier and expect this addon to work.

Install:

composer require <vendor>/<package>^3.4
php artisan vendor:publish --tag=<package>-config   # if the addon ships config
php artisan migrate                                  # if FormConfig entries are stored in a table

Where to look first, in order:

1. composer show <vendor>/<package> — confirm you resolved 3.4.x against Statamic 6.5+ and Laravel 12/13.
2. The addon's service provider. This release adds a call to Statamic's registerSerializableClasses API; that registration is the single most important line in the package for cache behaviour, and it's also the extension point you'll copy if you subclass anything.
3. The FormConfig blueprint / fieldset in resources/blueprints/ (or wherever the addon publishes it). That blueprint is the actual contract for what a form config entry contains — read it before writing any code against the config objects.
4. The published config file, for cache TTL / driver settings.

First use case: create a FormConfig entry in the Control Panel, then resolve it in a Blade view or controller and render it. Getting that loop working end-to-end before touching caching or multi-site will surface 90% of misconfiguration immediately.

Implementation Patterns

Treat FormConfig entries as content, not code. The idiomatic flow is: editors manage entries in the CP, your templates/controllers resolve them at render time. Avoid hardcoding field handles in PHP — read them off the resolved config object so blueprint changes don't silently break your forms.

Resolve through the repository, not Eloquent/Entry queries directly. Statamic addons that expose FormConfig typically wrap lookup behind a repository or facade. Going through it means you inherit the addon's caching and any query scoping (site, status, collection) for free; hand-rolling Entry::query() bypasses both.

Cache invalidation is the pattern to design around. If you cache rendered forms or resolved configs yourself, key the cache on the entry ID and $entry->lastModified() so CP edits bust it. The addon's own cache is handled internally, but your downstream caches are your responsibility.

Multi-site: resolve FormConfig entries with an explicit site when the form output is locale-specific. Statamic's default site resolution will otherwise leak the current request locale into cached values — a classic source of "the German form renders English labels" bugs.

Queued jobs and event listeners: since 3.4.0 registers FormConfig as a serializable class, you can safely pass config objects into queued jobs, broadcast events, and listeners. This is a genuine new capability on Laravel 13 — before this fix those payloads would fail to deserialize from the hardened cache. If you previously worked around this by passing entry IDs and re-resolving in the job, you can simplify, but only once you've dropped support for anything below 3.4.0.

Testing: add a test that round-trips a FormConfig through serialize()/unserialize() (or through the cache with your production driver). That single test catches the class of regression this release fixed, and will catch it again the next time you subclass or decorate the config object.

CI matrix: mirror the package's own matrix — PHP 8.3/8.4/8.5 × Laravel 12/13. If you support both Laravel versions, run both; the cache serialization path differs between them, so a green Laravel 12 build tells you nothing about 13.

Gotchas and Tips

The cache fix only covers the package's own classes. If you extend or decorate FormConfig — a custom subclass, a DTO wrapping it, an enum property — you must register your class with Statamic's registerSerializableClasses in your own service provider. Unregistered subclasses will still throw on deserialization under Laravel 13's hardened cache. This is the most likely thing to bite you after upgrading.

Symptom to recognise: "cannot be unserialized" / "not allowed" errors that appear only in production, only after a deploy, and only on cached pages. That's the allowlist, not your data. Fix is registration, not cache-busting — though php artisan cache:clear will make it disappear temporarily and fool you into thinking it's resolved.

Upgrade the three dependencies as a set. Bumping Laravel to 13 while leaving Statamic on 6.4, or bumping the addon on PHP 8.2, produces composer resolution failures that look like addon bugs. Move PHP → Statamic → Laravel → addon in that order, or all at once in a single composer.json edit.

PHP 8.3 means dropping 8.2. If you run a shared base image or a CI runner pinned to 8.2, the build breaks before composer ever explains why. Check your Docker base images and GitHub Actions php-version matrices first.

Deployment order matters. Cache the config (php artisan config:cache) and clear the application cache as part of the same deploy step that ships the new code. A deploy that clears the cache before the new service provider is live will repopulate it with entries serialized under the old allowlist.

Extension points worth knowing:

• registerSerializableClasses — for your own config subclasses (see above).
• The published config file — for cache driver/TTL tuning; check whether the addon respects CACHE_STORE or has its own store, because pointing it at a separate store changes your invalidation story.
• The FormConfig blueprint — additive field changes are safe; renaming or removing handles requires migrating stored entry data and auditing every template that reads the handle.

Don't skip reading the diff of the service provider between 3.3.x and 3.4.0. It's small, and it tells you exactly which classes are now allowlisted — which is the list you need to extend rather than duplicate.