Fine Builder Laravel Package

Getting Started

This assessment is based on the v0.1.5 release note (“Compliance with Statamic Marketplace”). That note tells us two important things: the package is a Statamic addon (Statamic sits on top of Laravel, so all normal Laravel conventions apply), and it is still pre-1.0, meaning the public API can still move between minor versions. Marketplace compliance releases are typically packaging/metadata changes rather than behavioural ones, so treat v0.1.5 as a low-risk bump from earlier 0.1.x versions.

Minimal setup:

composer require vendor/package:^0.1.5
php artisan vendor:publish --provider="Vendor\Package\ServiceProvider"   # if the addon ships config/views
php artisan config:clear && php artisan view:clear

Statamic discovers addons through the package’s composer.json (extra.statamic) after composer dump-autoload, so there is usually nothing to register by hand. Confirm discovery in the Control Panel under Tools → Addons, or by checking that any new tags/fieldtypes appear where the README says they should.

Where to look first, in order:

1. README.md — install steps, config keys, and the example that the marketplace listing renders.
2. The published config file in config/ — this is the contract for how the addon behaves in your app.
3. src/ServiceProvider.php — what gets registered (tags, fieldtypes, modifiers, routes, commands, nav items).
4. tests/ — the clearest description of intended usage the maintainer wrote.

First use case: wire the addon into a single, low-risk surface before rolling it out. If it exposes an Antlers tag, drop it into one template; if it exposes a fieldtype, add it to one field on a draft collection; if it exposes a modifier, use it in one partial. Verify output in the CP and in the REST/GraphQL response before touching production content.

Implementation Patterns

Config-first, code-second. Most Statamic addons are configured rather than subclassed. Publish the config, move environment-specific values (API keys, endpoints, feature switches) into .env, and keep the config file in version control with only defaults and env() calls. This is the single highest-leverage habit for day-to-day work: it keeps the addon upgradeable without merge conflicts.

Antlers as the primary surface. In templates you will typically consume the addon as a tag pair or single tag:

{{ addon_tag :param="value" }}
    {{ result_field }}
{{ /addon_tag }}

If you need the same data in Blade or PHP, prefer the package’s documented facade/helper over reaching into its internals. Where no facade exists, Statamic::tag('addon_tag')->params([...])->fetch() is the conventional bridge.

Fieldtypes and blueprints. When the addon provides a fieldtype, add it to blueprints via the CP rather than editing YAML by hand, then commit the resulting blueprint YAML. Check augmentation early — a fieldtype that looks fine in the CP can serialise differently in the REST API, which matters if a front end consumes content headlessly.

Cache and Stache awareness. Anything that reads content should be assumed to interact with Statamic’s Stache. During development, run php artisan statamic:stache:clear after changing blueprints, fieldtypes, or config, otherwise you will debug phantom behaviour. In production, ensure your deploy runs php artisan config:cache and that the addon’s config is cache-safe (no closures, no runtime-only values).

Testing. Statamic addons conventionally ship Statamic\Testing\AddonTestCase. Use the package’s own test setup as the template for your integration tests, and extend it for your own fixtures rather than bootstrapping a full app yourself.

Local development. If you need to patch or inspect the addon, add a path repository entry in your app’s composer.json and symlink the package. This is far faster than editing vendor/ and losing changes on the next composer update.

Marketplace compliance as an integration signal. Because the release targets marketplace compliance, expect the package to follow standard conventions: a provider registered via extra.statamic, publishable config/views, a licence, and a rendered README. That standardisation is what makes the addon predictable to integrate — lean on those conventions rather than fighting them.

Gotchas and Tips

Pin pre-1.0 versions deliberately. ^0.1.5 permits 0.1.x but not 0.2.0 — which is correct semantics, but note that in the 0.x range a “minor” bump is where breaking changes are allowed. Pin to 0.1.* in production and review the changelog on every bump until 1.0.

v0.1.5 specifically. The note describes marketplace compliance only, so the practical risk is metadata, not behaviour. Still verify after upgrading: the addon still appears under Tools → Addons, published config/views were not renamed, and any CP nav item still renders. If you previously installed from a VCS or path repository, re-check that the package name matches the marketplace listing, since compliance work sometimes normalises package names.

Re-publish only when told to. vendor:publish overwrites files by default. Use --force only after diffing; otherwise you will silently lose local customisations to config or views.

Clear the right cache. When behaviour looks stale, work through config:clear, view:clear, statamic:stache:clear, and composer dump-autoload in that order. Addon changes that touch registration frequently need the autoload dump, not just a cache clear.

Forking breaks discovery. If you fork the addon for a fix, preserve the extra.statamic block, the provider namespace, and the licence. Dropping or renaming these is the most common reason a forked Statamic addon “disappears” after installation.

Multi-site and localisation. Statamic addons often ship translations and site-aware behaviour. If you run multi-site, test the addon on a secondary site explicitly — site-relative URLs and translated strings are a frequent source of bugs in young addons.

Debugging. Statamic addons run within your Laravel app, so the usual tools work: Log::debug(), Telescope, and the Laravel debugbar. For template-level issues, {{ dump }} in Antlers and php artisan statamic:stache:refresh will resolve most “it renders nothing” reports.

Extension points. Before patching the addon, check whether the provider exposes events, view namespaces, or a publishable config that already covers your case. In the 0.1.x range, extension points are fewer than in mature packages — if you need one that doesn’t exist, file an issue early, because the maintainer is likely still shaping the API ahead of 1.0.