Statamic Inline Assets Laravel Package

Getting Started

The 4.0.3 release is a small, additive change: it introduces an ignore-missing flag (issue #6) so the package can skip over entries it cannot resolve instead of failing hard. If you already have the package installed, upgrading is low-risk — no breaking changes, no deprecations, and the flag is opt-in.

1. Upgrade and pin the constraint so you actually get the new flag:

   composer require <vendor>/<package>:"^4.0.3"
   

2. Republish/merge the config if your config file predates this release, so the new key is present:

   php artisan vendor:publish --tag=<package>-config --force
   

   Diff the published file against your existing one rather than blindly overwriting — you only need the new ignore_missing entry.
3. Look first at the config file and the README section for "ignore missing" — the release note is terse, but the flag is documented there with its default (strict/off) and scope.
4. First use case: turn the flag on in local and CI-safe contexts where missing entries are expected (partial checkouts, generated stubs, translation/route/asset lookups that are legitimately absent), then confirm the package no longer throws or aborts on those entries.

A sensible first run:

# Strict mode (default) — surfaces everything
php artisan <package>:command

# Lenient mode — skips unresolved entries, reports the rest
php artisan <package>:command --ignore-missing

Implementation Patterns

Config as the default, CLI/method as the override. The most maintainable pattern is to set the flag in config/<package>.php per environment (strict in production, lenient locally) and use the per-invocation flag only for one-offs:

// config/<package>.php
return [
    // ...
    'ignore_missing' => env('PACKAGE_IGNORE_MISSING', false),
];

# .env.local
PACKAGE_IGNORE_MISSING=true

Environment-driven strictness. Keep production strict so regressions are loud, and only relax it where the input set is knowingly incomplete. This gives you the benefit of the new flag without masking real breakage in the pipeline that matters.

Per-run override in scripts. When invoking programmatically, pass the flag explicitly rather than mutating config at runtime — it keeps the call site self-documenting and avoids leaking state between jobs:

$result = Package::make()
    ->ignoreMissing()   // or ->withIgnoreMissing(true), depending on the fluent API
    ->run();

Wrap the lenient path in observability. Because the flag swallows missing entries, log or collect what was skipped so you retain visibility:

$result = Package::make()->ignoreMissing()->run();

if ($result->hasSkipped()) {
    Log::warning('<package>: skipped missing entries', [
        'count' => count($result->skipped()),
        'entries' => $result->skipped(),
    ]);
}

Wire this into the same channel as your deploy/pre-build tooling so skipped entries are reviewable but non-fatal.

Use it as a migration/backfill aid. When introducing the package or rolling out a change, run once with --ignore-missing to get the job done, then run again in strict mode to enumerate exactly what's absent and fix the backlog deliberately.

Gotchas and Tips

• The default is still strict. 4.0.3 adds a flag, it does not change behavior. If you expected missing entries to stop failing after upgrade, you must enable the flag explicitly.
• Config caching will bite you. After editing ignore_missing, run php artisan config:clear (and re-cache with config:cache in production). A stale cached config is the most common reason "the flag has no effect."
• Naming mismatch between config and CLI. Watch the exact spelling — config keys are typically snake_case (ignore_missing) while the artisan option is --ignore-missing and the fluent method may be ignoreMissing(). Check the README rather than guessing.
• Ignoring missing can hide real regressions. A typo in a path/key looks identical to a legitimately absent entry. Pair the flag with logging (above) and only enable it in environments where absences are expected.
• Do not use it as a permanent production setting. Treat it as a scoped escape hatch; otherwise you lose the package's primary value of surfacing unresolved input.
• Debugging strategy: run once without the flag to get the exact failing list, then re-run with it to confirm the skip path and inspect what was collected in skipped()/logs.
• Version pinning matters here. The flag landed in 4.0.3 — a ^4.0 constraint is fine, but if you lock to 4.0.0–4.0.2 the flag simply won't exist. Verify with composer show <vendor>/<package>.
• Extension points: if the package exposes a resolver/handler contract, prefer implementing/overriding it to teach the package about your custom "missing" cases rather than globally ignoring everything. That keeps the flag's blast radius small.
• No upgrade migration needed — this is additive. Roll it out normally; just remember to publish/merge config if you rely on the new key.