Footprint Statamic Laravel Package

Getting Started

• Install with composer require danielgnh/footprint-statamic. At v0.1.0 there is no upgrade path yet, so install it on a branch and commit the lock file.
• Before anything else, open the package's composer.json and check the statamic/cms and laravel/framework constraints. This is a first release; the constraint is the fastest way to find out whether it fits your app or will force a dependency downgrade.
• Publish the config (php artisan vendor:publish --provider="Danielgnh\FootprintStatamic\ServiceProvider" — confirm the exact provider/tag with php artisan vendor:publish and pick from the list) and skim the published file. It tells you more about the integration surface than the README currently does.
• Read src/ServiceProvider.php first, then any Tags/, Fieldtypes/, Listeners/, or Migrations/ directories. Ten minutes there answers the only question that matters at 0.1.0: does this hook into Statamic via events, a fieldtype, an Antlers tag, or a middleware?
• If the addon isn't auto-discovered, register it in config/statamic/addons.php and run php artisan migrate if it ships migrations.
• First use case: wire it to a single collection on a staging site and push one entry through a full save → publish → unpublish cycle. Confirm a record lands exactly where you expect (a DB table, a log file, or a Control Panel listing) before you touch a second collection. Do not roll it out site-wide until you've seen one clean round trip.

Implementation Patterns

• Adopt it behind an adapter. Put a thin class in app/Support/ that wraps whatever the addon exposes, and call that from your own code. At 0.1.x the public API is not stable; an adapter means a minor bump costs you one file instead of a grep across the codebase.
• Prefer listening over subclassing. If the package dispatches events, register listeners in your own EventServiceProvider rather than extending its classes. Listeners survive internal refactors; subclasses don't.
• Scope rollout by collection, not by environment. Enable it for one or two high-value collections first (the ones where an audit trail actually pays for itself), verify the output shape, then widen.
• Check for overlap with Statamic's built-ins. Statamic already ships revisions and, on the Pro tier, some audit capability. Decide explicitly whether this addon replaces or complements that before you end up with two sources of truth for "who changed what."
• Testing. Use Statamic's addon test case (Statamic\Testing\AddonTestCase) or Testbench so your suite boots Statamic with the addon registered. Assert on the outcome (a row exists, a file is written) rather than the addon's internal classes — again, 0.x.
• Pin the version. Use "danielgnh/footprint-statamic": "0.1.*" in composer.json, not ^0.1. With no changelog detail beyond a commit link, a composer update should never be able to move you.
• Deployment. Add the publish/config step to your deploy script, and run php artisan config:clear before config:cache so the addon's config is picked up.

Gotchas and Tips

• 0.x semver is real here. The release notes for v0.1.0 are a bare changelog link, so read https://github.com/danielgnh/footprint-statamic/commits/v0.1.0 before every bump and diff the src/ tree yourself. Treat every 0.2.0, 0.3.0 as potentially breaking.
• Stache caching. Statamic caches aggressively. After enabling the addon, changing its config, or adding a field, run php artisan stache:clear (and stache:warm if you use it). Most "the addon isn't doing anything" reports are stale Stache, not a bug.
• Multi-site. Statamic multisite often exposes addons that quietly assume single-site. If you run more than one site, verify whether records are scoped per site or keyed only by entry ID — check this before production data accumulates.
• Flat-file vs Eloquent driver. Behaviour can diverge between Statamic's storage drivers. If you're on the Eloquent driver, test there specifically rather than assuming parity with the default flat-file setup.
• Migrations on multi-server deploys. If it ships migrations, they need to run once, not once per web node. Gate them behind your standard deploy release step, not a boot-time check.
• Where to debug. Start with storage/logs/laravel.log filtered by the addon's namespace, then ray()/dump() inside the service provider's boot method to confirm it actually registers. A silently failing register() is a common first-release symptom.
• Extension points to reach for first: publishable views/config (override in resources/views/vendor/... rather than editing vendor), container bindings in the service provider (bind your own implementation over the default), and events. Avoid forking — at 0.1.0 you'll want to pull upstream fixes.
• Budget for churn. This is a solo-maintainer, first-release package. Use it where the failure mode is "an audit record is missing," not where the failure mode is "the site goes down."