Statamic Hubspot Laravel Package

Getting Started

v2.1.0 is primarily a platform-support release (Laravel 13, Statamic 6.5, PHP 8.3) plus one real bug fix for cached FormConfig objects. There are no new user-facing features, so if you are already on 2.0.x with Laravel 12, this upgrade is mostly about the version floor and the cache fix.

Before you require it, check your matrix:

If you are on PHP 8.2, Laravel 12, or Statamic 6.4, stay on 2.0.x. The floor bumps are hard requirements, not soft suggestions — Composer will simply refuse to resolve.

Upgrade path:

1. Bump PHP in every runtime you own (local, CI image, Dockerfile base, Forge/Lambda/Vapor/Nitro build image). This is the step people forget; the Composer resolution succeeds locally and fails in deploy.
2. Upgrade Statamic to 6.5+ and Laravel to 13 together — they are coupled in this release. Do not try to hold Laravel 12 while taking Statamic 6.5.
3. composer require <vendor>/<package>:^2.1
4. Publish/refresh config if the package ships one, then clear caches: php artisan cache:clear && php artisan statamic:stache:clear && php artisan statamic:stache:warm
5. Smoke-test a form submission end to end.

Where to look first in the codebase:

• The package service provider — confirm what it registers (Stache/entry repositories, config, and now the serializable-class allowlist).
• The FormConfig class itself — this is the object that gets cached and was the subject of the fix.
• The published config file, if any, for cache/store settings.

First use case: create a FormConfig entry (through the CP or a seeder), resolve it in a controller/antlers template, and render the form. That single flow exercises the content layer, the cache layer, and the fix in this release.

Implementation Patterns

Treat forms as content, not code. The FormConfig model implies forms are editable entries. Lean into that: define the blueprint, let editors add/remove fields, and resolve the config at render time rather than hardcoding field lists. This is the whole reason to use the package over raw Statamic forms.

Resolving a config:

// Resolve through the repository/Stache — do not hand-parse YAML or JSON.
$config = FormConfig::findByHandle('contact');

Wrap hot lookups in a request-scoped singleton or once() helper if you resolve the same config multiple times per request, but do not push FormConfig instances into a long-lived cache store yourself — see the gotchas.

Programmatic creation (seeders, migrations, imports):

FormConfig::make()
    ->handle('newsletter')
    ->data([...])
    ->save();

Save through the model so Stache updates and events fire; writing the underlying files directly will leave the Stache stale until the next refresh.

Submission handling: let Statamic's form submission pipeline do validation against the blueprint. Your job is to resolve the right FormConfig, pass it to the form tag/view, and handle post-submit side effects (notifications, CRM push) in a listener rather than in the controller.

Testing:

• Use the package's factories/fixtures where provided; otherwise build configs in setUp() and call statamic:stache:clear in tearDown().
• Add an explicit test that caches a FormConfig and reads it back — that is your regression guard for the serialization fix.
• Run CI against the actual matrix (PHP 8.3 × Laravel 13 × Statamic 6.5). Testing on Laravel 12 will not catch the hardened-cache behaviour.

Deployment: config cache + Stache warm in the release step, in that order, after the code is on disk.

Gotchas and Tips

The cache serialization fix is the one thing to actually understand. Laravel 13 hardened unserialize() with an allowlist. Previously, a FormConfig that had been serialized into the cache could come back as __PHP_Incomplete_Class or throw an offset/unserialize() error. v2.1.0 registers the class through Statamic's registerSerializableClasses API.

Practical consequences:

• Clear your cache on deploy. Any FormConfig objects serialized by 2.0.x under Laravel 13 are unrecoverable — clearing is the fix, not a workaround. Same for Redis/Memcached, which outlive your app server.
• If you subclass FormConfig, register your subclass in the same allowlist via registerSerializableClasses. The package registers its own class, not yours. This is the main extension point this release exposes.
• Symptoms before the fix: forms mysteriously "disappear," fields render empty, or you get a 500 on the first request after a cache warm. If a user reports this post-upgrade, cache:clear first, debug second.

Version floor traps:

• Bumping PHP to 8.3 also means dropping any transitive dependency that caps at 8.2 — run composer why-not php 8.3 before assuming the resolution failure is this package's fault.
• Statamic 6.5 is described as "the first version with Laravel 13 support." There is no supported combination of Statamic 6.4 + Laravel 13, so don't attempt it as a halfway upgrade.

Stache vs. framework cache are two different caches. cache:clear won't fix a stale Stache and statamic:stache:clear won't clear serialized objects in Redis. When debugging a FormConfig that looks wrong, clear both and confirm which one actually changed the behaviour before touching code.

Don't edit Stache YAML by hand while the Stache is warm — the file and the in-memory index will disagree, and you'll misattribute the problem to the serialization change.

No deprecations, no removed methods are called out in this release, so a 2.0.x → 2.1.0 diff should be safe code-wise. The risk is entirely in the environment (PHP/Laravel/Statamic versions) and in stale serialized state.