System Laravel Package

Getting Started

amplify/system is a module for Amplify CMS, not a standalone package. Its job is the operational layer of a CMS install: environment/system info, settings and configuration screens, cache/maintenance actions, and the admin surface that binds them together. That framing should drive how you adopt it — you are adding an ops console to an existing Amplify application, not a library you can drop into any Laravel app.

Prerequisites and install

1. Confirm you already have the Amplify core installed and booting (composer show | grep amplify). A module's service provider typically assumes core contracts, view namespaces, and admin layout components are present.
2. Install with an explicit, pinned constraint — with zero dependents there is no ecosystem pressure to keep the API stable:

composer require amplify/system:"<exact-version>"

3. Check how the module registers itself before writing any code:

# Is it auto-discovered or manually registered?
cat vendor/amplify/system/composer.json | grep -A5 '"extra"'

# What does the provider actually bind?
sed -n '1,120p' vendor/amplify/system/src/*ServiceProvider.php

If extra.laravel.providers is absent, you must add the provider to config/app.php (or bootstrap/providers.php on Laravel 11+) manually. Do this deliberately rather than relying on discovery — module packages frequently ship a provider that registers routes, migrations, views, and translations all at once, and you want to know that before php artisan serve.

Where to look first

Read the package directory in this order, because it answers 90% of the questions you'll have later:

First use case

The fastest meaningful win is exposing the module's settings screen and wiring it to something your app already reads from config. Publish what's publishable, boot the app, and enumerate what appeared:

php artisan vendor:publish --provider="Amplify\System\SystemServiceProvider"
php artisan route:list --path=system
php artisan migrate --pretend   # inspect before running

Then log in as an admin and confirm the module renders inside the CMS shell. If it renders standalone or 500s on a missing layout, you've learned that your Amplify core version is out of step with the module — stop and resolve that first, because everything downstream depends on the admin shell being available.

If you only need one or two of its features (say, a health/status panel), consider reading the source as a reference implementation instead of depending on it. At this maturity level, copying 150 lines into your own application is often cheaper than owning an unmaintained dependency.

Implementation Patterns

Treat it as an admin surface, not a domain layer. Business logic should never call into the system module. The dependency arrow points one way: your app reads settings/config; the system module reads your app only through framework primitives (config, cache, DB). Keep it that way and swapping it out later is a one-file change.

Wrap settings access behind your own typed accessor. System modules usually store settings in a database table with a key/value shape, which means untyped reads and null surprises spread everywhere. Introduce a thin adapter on day one:

namespace App\Support;

use Amplify\System\Facades\Settings; // verify actual facade/class name in vendor/

final class AppSettings
{
    public function maintenanceBanner(): ?string
    {
        return Settings::get('system.maintenance_banner');
    }
}

Now every call site is typed, greppable, and fakeable in tests, and a future replacement only touches this class.

Cache the reads, invalidate on write. DB-backed settings are read on nearly every request in a CMS. If the package doesn't cache internally, wrap it:

public function get(string $key, mixed $default = null): mixed
{
    return Cache::rememberForever("settings.{$key}", fn () => Settings::get($key, $default));
}

Then listen for the module's save event (check src/Events/ — if none exists, that's a fork candidate) and Cache::forget() the key. A settings screen that "doesn't work" is almost always a stale cache, not a broken form.

Gate the entire module behind an explicit authorization layer. Do not assume it ships with sensible middleware. Verify with route:list -v, then add your own:

Route::middleware(['web', 'auth', 'can:manage-system'])
    ->prefix('admin/system')
    ->group(base_path('vendor/amplify/system/routes/web.php'));

Register the routes yourself instead of letting the provider do it if you need control over prefix, middleware, or domain. This is the single most important integration decision in the package — an ops console that clears caches and toggles maintenance mode is a privilege-escalation surface if it's reachable by non-admins.

Prefer your own artisan commands over the UI for repeatable ops. Anything an operator clicks should also be runnable from a runbook or CI:

class FlushSystemCaches extends Command
{
    protected $signature = 'app:flush-system-caches';

    public function handle(): int
    {
        Cache::flush();
        Artisan::call('view:clear');
        Artisan::call('config:clear');
        $this->info('Flushed.');
        return self::SUCCESS;
    }
}

Schedule it, log it, and let the admin UI be a convenience layer over the same code path.

Extension points over edits. If the module exposes contracts, events, or a driver-style config ('driver' => 'database'), bind your implementation in a service provider:

$this->app->bind(
    \Amplify\System\Contracts\SettingsRepository::class,
    \App\System\DatabaseSettingsRepository::class
);

Never edit vendor/. With a package this young, you will need to patch it eventually — do that via a fork ("repositories": [{"type": "vcs", ...}]) so the change survives composer update and is visible in review.

Testing. DB-backed settings make tests order-dependent. Use RefreshDatabase plus a seeder that establishes a known settings baseline, and bind a fake repository in TestCase::setUp() for unit tests so you're not hitting the settings table to assert unrelated behavior.

Gotchas and Tips

You are the maintainer now. Zero stars and zero dependents means there is no community to have already hit your bug, no Stack Overflow answers, and no guarantee the next release won't break you. Pin the exact version, commit composer.lock, and read the diff of every upgrade. Budget for a fork.

Treat the release metadata as untrustworthy until you verify it. The advertised last release date is in the future relative to a normal release cadence, which usually signals a mis-tagged commit, a rewritten tag, or a metadata artifact. Before pinning, confirm the tag and the manifest agree:

git ls-remote --tags https://github.com/amplify-plugin/system-module
composer show amplify/system --all

If the tag and composer.json version disagree, pin to a commit SHA instead of a version.

config:cache will freeze your published config. Settings that look configurable in the admin UI but are actually read from config/system.php will silently stop responding after php artisan config:cache in production. Decide early whether a setting is config (deploy-time, env-driven) or data (DB, runtime-editable), and never let the module blur the two.

Duplicate migrations and table collisions. Module migrations often publish into database/migrations/ rather than running from the package. If you install, publish, then later upgrade, you can end up with two migrations creating the same table. Check php artisan migrate:status after publishing, and prefer package-hosted migrations (loadMigrationsFrom) if the provider offers it.

Route and asset collisions with your admin panel. A module that registers admin/* or publishes assets to public/vendor/system can clash with your own admin routes or an existing asset pipeline (Vite). Namespace the prefix, and check whether the module assumes a specific CSS framework version from the Amplify shell.

Published views shadow package views forever. Once you vendor:publish the views to customize one blade file, all of them are yours, and upgrades to the package's views will not reach you. Publish selectively with --tag, or override a single view via a view namespace prepend instead.

Authorization defaults are the likeliest vulnerability. Audit before exposing: does the provider register routes with web only? Are destructive actions (cache clear, maintenance mode, log truncation) POST-only and CSRF-protected? Are they logged? If the answer to any of these is no, put the whole module behind your own middleware and add an activity log.

Debugging checklist when something 500s or silently no-ops:

php artisan about                       # provider bootstrapped? env correct?
php artisan route:list --path=system -v # middleware actually applied?
php artisan event:list | grep -i system # are save events firing?
tail -f storage/logs/laravel.log
php artisan view:clear && php artisan cache:clear

Nine times out of ten it's a stale config/view cache, a missing published asset, or a provider registered after the one that defines the admin layout.

Plan your exit before you need it. Confine every touchpoint to App\Support\AppSettings and one service provider binding. If the package stalls — and at this adoption level, assume it might — replacing it with a 60-line settings table plus a Blade form should be an afternoon, not a sprint. That isolation is worth more than any feature the module ships.