System Module Laravel Package

Getting Started

This is a Streams Platform module (the engine behind PyroCMS/OpenClassify), not a standalone Laravel package — install it only inside an existing Streams application.

composer require visiosoft/system-module
php artisan migrate
php artisan module:install system

First places to look after install:

1. vendor/visiosoft/system-module/src/SystemModuleServiceProvider.php — routes, bindings, and admin navigation registration point into the Streams admin.
2. resources/views/admin/ — the actual admin panels (system info, PHP/server info, cache, logs) you’ll be customizing.
3. src/Http/Controllers/Admin/ — the endpoints behind those panels; these are the least magic and most useful to read first.
4. config/ — anything publishable (php artisan vendor:publish --tag=system) before you edit it, since vendor files are overwritten on composer update.

Your first real use case is the admin diagnostics screen: log in to /admin, find the System section in the sidebar, and use it to confirm PHP version, extensions, database connectivity, write permissions on storage/ and bootstrap/cache/, and disk usage after a deploy. That single screen replaces a lot of manual php -i / df -h / SHOW VARIABLES triage.

Implementation Patterns

Admin health dashboard as a deploy gate. After deploy, have a step (script or checklist) that loads /admin/system and verifies the environment. If you don’t want humans in the loop, wrap the same underlying checks in a command:

// app/Console/Commands/SystemCheck.php
use Illuminate\Console\Command;

class SystemCheck extends Command
{
    protected $signature = 'system:check';
    protected $description = 'Assert runtime environment against expectations';

    public function handle(): int
    {
        // Prefer the module's own services if exposed; otherwise mirror the checks
        $checks = [
            'php'   => version_compare(PHP_VERSION, '7.4', '>='),
            'db'    => rescue(fn () => \DB::connection()->getPdo(), false, false) !== false,
            'cache' => rescue(fn () => \Cache::put('probe', 1, 10) && \Cache::get('probe') === 1, false, false),
            'writes'=> is_writable(storage_path()),
        ];
        foreach ($checks as $name => $ok) {
            $this->line(sprintf('%-8s %s', $name, $ok ? 'OK' : 'FAIL'));
        }
        return in_array(false, $checks, true) ? self::FAILURE : self::SUCCESS;
    }
}

Run it in your deploy pipeline before traffic is shifted; the module’s admin view is for humans, the command is for CI.

Registering a custom panel. The module is built on Streams, so extend rather than fork: add your own Streams module with a section bound to the same admin navigation group, and render a view that pulls from the system module’s data via the container. Keep custom panels in your app module so upstream updates don’t clobber them.

Reuse the environment data in support tooling. The values you see in the admin UI (PHP version, DB driver/version, loaded extensions, cache driver) are exactly the fields support tickets need. Pipe the same data into a GET /support/bundle route (admin-only) that emits JSON, and attach it to bug reports. This is the biggest day-to-day win: one canonical environment snapshot instead of asking users to paste php -i.

Cache clearing as a first-class action. The management side typically includes cache/config clear buttons. Mirror them in a deploy hook (php artisan cache:clear, php artisan config:clear) and treat the admin button as the emergency path — not the routine one — so you don’t develop a habit of clearing cache manually in production.

Gotchas and Tips

• This package is effectively unmaintained (last release 2021-06-15, zero stars). Pin it exactly ("visiosoft/system-module": "1.0.x" — check composer show for the actual version) and commit composer.lock. Audit its provider and views before using it in production; do not assume it tracks current Laravel or Streams versions.
• Version-lock the Streams platform first. These modules break on Streams major bumps more often than on Laravel bumps. Confirm the compatible pyrocms/streams major in the module’s composer.json before adding it to an app you plan to upgrade.
• Publishing vs. editing in place. Only change config/views via vendor:publish. Vendored edits vanish on the next composer update and are invisible in code review.
• Permissions are the usual cause of “blank system page.” If the admin panel renders empty, check storage/ and bootstrap/cache/ writability and the admin role’s ACL for the system section before assuming a code bug.
• Cache-driver surprises. The cached data may be driver-specific (file vs. redis vs. array). In local with CACHE_DRIVER=array, “cache OK” checks pass but persist nothing useful; run health checks against the same driver prod uses.
• Migration ordering. Because it migrates into the shared Streams schema, run php artisan migrate after module:install completes installing its own dependencies; install fresh apps in the documented order (streams → modules → app).
• Extension points beat patches. Add panels/sections through Streams bindings in your own module rather than editing system-module source. If you must patch, fork the repo and switch the composer dependency to your fork with a repositories entry.
• Debugging the module itself: set APP_DEBUG=true locally and watch storage/logs/laravel.log; Streams swallows view/render exceptions aggressively, so most failures show as an empty panel and an entry in the log, not a stack trace page.
• Don’t rely on it as a security control. It’s a diagnostics/informational module — treat visible paths, versions, and config values as sensitive and confirm those endpoints are behind admin middleware before exposing the app beyond a trusted network.