Statamic Kontainer Laravel Package

Getting Started

Install and wire it up

composer require jezzdk/statamic-kontainer
php artisan vendor:publish --provider="Jezzdk\Kontainer\ServiceProvider"   # publish config/assets if offered
php please cache:clear

Then, in order:

1. Credentials first. The addon stores Kontainer API credentials in the addon settings (Control Panel → Addons → Kontainer). Do this before adding the fieldtype anywhere — a fieldtype with no working client typically renders a broken/empty control panel field, and it's easy to waste an hour assuming the field is misconfigured when the API call is failing.
2. Confirm what the field stores. Read src/Fieldtypes/*.php and check process() / preProcess(). The single most important thing to learn on day one is whether the saved value is a Kontainer asset ID, a full URL, or an array of metadata. Everything downstream (Antlers, augmentation, caching, imports) depends on this.
3. Add one field to one fieldset and test in the CP before rolling it out:

# resources/fieldsets/hero.yaml
title: Hero
fields:
  -
    handle: hero_image
    field:
      type: kontainer
      display: Hero image
      # container/folder/max-files style options: verify exact keys in src/Fieldtypes

First use case: a marketing hero image or press/logo asset on a Page collection — approved brand media that lives in the DAM and must not be re-uploaded into assets/. That's the cheapest end-to-end test: select in CP → preview renders → save → inspect the YAML in content/collections/pages/*.md → render on the front end.

Where to look first (in this order): the fieldtype class (preload() tells you what the Vue component receives), the Vue component under resources/js/components/fieldtypes/, the config file, then the README. With a package this small and this thinly documented, the source is the documentation.

Implementation Patterns

Fieldtype as the only integration surface. Treat this addon as "a picker plus a reference," not as a media pipeline. The realistic pattern:

• Selection in the CP, storing a reference.
• Resolution in your own code — a small Antlers tag, an augmentor, or a model accessor that turns the stored reference into a URL/alt/dimensions via Kontainer's API.
• Caching around resolution, because you don't want a front-end page render to make N synchronous DAM API calls.

Resolution + caching pattern (adjust to the actual stored shape):

// app/Tags/KontainerAsset.php  — or an augmentor on the field
public function url(): string
{
    $ref = $this->context['hero_image'] ?? null;
    if (! $ref) {
        return '';
    }

    return Cache::remember("kontainer:{$ref}:url", now()->addDay(), function () use ($ref) {
        return app(\Jezzdk\Kontainer\Kontainer::class)->asset($ref)['url'] ?? '';
    });
}

If the addon ships no client/service binding, instantiate its HTTP wrapper directly or (simpler, and often safer) call Kontainer's REST API from your own thin service class and use the addon purely for the CP picker.

Consistent fieldsets across collections. Define the Kontainer field once in resources/fieldsets/ and import it into every collection that needs approved media. This is also the cheapest way to later restrict containers/folders per context (e.g. a "Brand" folder for the About page, a "Campaign" folder for landing pages) without touching content.

Coexistence with Statamic's native asset field. Use assets for things editors upload ad hoc (PDFs, per-page images) and kontainer for centrally governed media. Mixing them on the same fieldset is normal and encouraged — don't try to force everything through the DAM.

Seeding/importing content. Because the value is a plain reference, you can write it straight into content YAML from a migration or importer. Do a dry run against one entry and diff the resulting markdown file before writing a bulk importer; if the fieldtype stores extra JSON, your importer must reproduce that shape exactly or the CP field will load as empty even though the data is "there."

Globals for site-wide assets. Logos, OG defaults, and favicons belong in a global set using the Kontainer field — one reference, one cache key, one place to update when the DAM asset changes.

Gotchas and Tips

• Zero stars, last release March 2022, near-zero docs. Pin an exact version in composer.json and expect to read the source. Budget for the possibility that you maintain a fork; a Statamic major upgrade will likely break it and no fix may arrive.
• The bundled assessment-pm.md does not describe this package. It talks at length about read_only enforcement and model attributes — that's a different project's notes. Ignore it entirely; it is not evidence about this addon's behavior, and it inflates the apparent "score" misleadingly. Verify every capability against the code.
• CP preview ≠ front-end output. The fieldtype's job is previewing images in the control panel. The front end will most likely receive the raw stored reference string. Never assume {{ hero_image }} renders an <img> — dump the value from a template first.
• API failure modes. Check whether the fieldtype has a timeout and degrades gracefully. If the Kontainer API is down or credentials are wrong, editors may see a permanently empty picker with no error message. Add a note to your editor docs ("if the media picker is blank, tell engineering, don't drag-drop a replacement").
• Credentials in addon settings are often YAML on disk. Addon settings live under resources/addons/ and get committed. If the addon supports env vars in its config, use them; otherwise confirm the credential file is gitignored or the key is scoped read-only.
• DAM references are stable; the bytes behind them are not. When someone replaces an asset in Kontainer, your stored ID doesn't change — so your own page cache, CDN, and any Cache::remember keys silently serve stale media. Define an invalidation story (short TTL, or a webhook/hook that flushes by reference ID).
• Preview/CORS quirks. Image previews loading from a Kontainer CDN domain sometimes fail in the CP due to hotlink protection or CORS. Symptom: working selection, broken thumbnails. Test in a real browser, not just by asserting the saved value.
• Extension points to know: the fieldtype class itself (subclass and override preload() to pass extra config to Vue, process()/preProcess() to normalize the stored shape), publishable views/config, and the Vue component if you need a different picking UX. Since the surface is small, a subclassed fieldtype is usually cleaner than patching the vendor file.
• Write one integration test asserting: field saves the expected shape, the CP endpoint returns preloaded data, and an entry retrieved via Antlers yields a resolvable reference. That test is your only real defense against a silent break on a Statamic upgrade.