Statamic Starter Kit Laravel Package

Getting Started

This is the first stable (1.0.0) release of the package, so the public API is now covered by semver — safe to adopt in production and pin with ^1.0.

Install and publish:

composer require <vendor>/<package>:^1.0
php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"

Start by inspecting three things, in this order:

1. config/<package>.php — the release adds caching and translation behaviour, both of which almost always surface as config keys (cache TTL/store, locale fallback).
2. resources/lang/vendor/<package>/ — the new translations ship here; check which locales are bundled and which keys exist before assuming coverage.
3. The service provider's register() vs boot() — the "global component converter" is registered during boot, and knowing where it hooks in tells you how to override it.

First use case: drop a cache widget onto an existing dashboard page and translate its labels.

<x-dashboard>
    <x-package::cache-widget :ttl="60" />
</x-dashboard>

If the widget renders empty or throws, you have a config/publishing problem, not an integration problem — run php artisan vendor:publish again and confirm the config file exists in config/.

Implementation Patterns

Caching widget output. The cache widget is the headline feature, and it will almost certainly accept a TTL and honour your default cache store. Prefer explicit TTLs over defaults so behaviour is visible in code review:

// config/<package>.php
'cache' => [
    'enabled' => env('<PACKAGE>_CACHE', true),
    'ttl'     => env('<PACKAGE>_CACHE_TTL', 300),
    'store'   => env('<PACKAGE>_CACHE_STORE', null), // null = default store
],

Disable it in local and drive it from the default store in production rather than introducing a second cache backend.

Translation overrides. Publish the lang files, then override only the keys you need in lang/vendor/<package>/{locale}/. Keeping overrides in your app's lang/ directory means package upgrades don't clobber your copy — never edit vendor/ directly.

// lang/vendor/<package>/de/messages.php
return [
    'cache.updated_at' => 'Zuletzt aktualisiert :time',
];

Global component converter. Registration belongs in a service provider's boot(), not register() — the converter needs the view/component registry to be ready. Register it once, globally, rather than per-view:

public function boot(): void
{
    Package::convertComponents([
        // map or configure the conversion here
    ]);
}

If you only need conversion in one area of the app, prefer a scoped registration over the global helper to avoid surprising behaviour in unrelated views.

Dashboards and Livewire. Widgets that render cached fragments and Livewire components interact awkwardly: a Livewire re-render may bypass your HTTP-level cache or serve a stale widget inside a fresh component. Wrap widgets in their own component boundary and let the widget own its cache key.

Testing. Assert on rendered output, not on cache internals, and swap the cache store to array in phpunit.xml so tests don't inherit a warm production-like cache.

Gotchas and Tips

• Stale widgets after deploy. Cached widget output survives config:cache and view:clear. Add the widget to your deploy script's invalidation step, or key the cache on a value that changes per release.
• Cache key collisions. If two widgets share a key namespace, one will silently render the other's output. Give each instance a discriminator (user ID, tenant, locale) and verify in a multi-tenant or multi-language setup.
• Locale in the cache key. Translated widget output cached under a locale-agnostic key will leak one language into another. Confirm the package includes the locale in the key; if not, disable caching for multi-locale dashboards or append the locale yourself.
• vendor:publish --force overwrites your translation overrides and config. Use it deliberately and diff afterwards — this is the most common way to lose customisations.
• Converter registration order. Globally registered converters run for every component resolution. A converter that throws will break unrelated pages, so validate inputs defensively rather than assuming well-formed components.
• Debugging a blank widget: php artisan view:clear && php artisan cache:clear && php artisan config:clear, then re-render. If it appears, it was cached output; if not, it's a registration issue.
• Extension points to check first: the config file's documented keys, the widget base class (for custom widgets), and whatever callback/array the converter accepts — these are the three seams you'll actually use. Read them before writing a custom widget; the built-in cache widget usually covers 80% of dashboard needs.
• Version pinning. Now that 1.0.0 is out, pin ^1.0 and watch for 1.x minor releases adding converter options or cache strategies — those are the most likely to introduce behavioural (if not breaking) changes.