Kernel Laravel Package

Getting Started

xblock/kernel is a Lumen-oriented admin scaffolding kernel — think "laravel-admin's core, trimmed down for Lumen's micro-framework footprint." Before you write a single line, confirm you're actually on Lumen (or a Lumen-flavored Laravel) and not a full Laravel app; the kernel assumes Lumen's bootstrap/app.php registration model, not Laravel's package discovery.

Minimal setup path:

1. composer require xblock/kernel — pin a specific version, since the ecosystem signal here is thin (26 stars, 0 dependents) and API surface is likely to shift between releases.
2. Register the service provider in bootstrap/app.php:

   $app->register(XBlock\Kernel\KernelServiceProvider::class);
   $app->configure('xblock');
   

3. Publish the kernel config (php artisan vendor:publish --provider="XBlock\Kernel\KernelServiceProvider") and set the admin route prefix, middleware stack, and auth guard driver.
4. Enable facades and Eloquent in bootstrap/app.php if you haven't already ($app->withFacades(); $app->withEloquent();) — the kernel's resource layer depends on both.
5. Define your first admin route inside the kernel's route group, then hit /admin and confirm the scaffold renders.

Where to look first: the package's src/ for the Kernel base class and route registrar, then the README's quickstart (usually a php artisan xblock:install or equivalent). First real use case: a single CRUD screen (e.g. Users) wired through the kernel's resource controller before you attempt multi-model admin navigation.

Implementation Patterns

Extend, don't fork. The intended pattern is to subclass the kernel's base Controller/Resource classes per admin module. You define a UserAdmin class that declares columns, form fields, and filters; the kernel handles rendering and request dispatch. Keep your subclasses thin — business logic belongs in your domain services, not admin controllers.

Route groups as the module boundary. Register admin modules as isolated route groups with their own middleware stack:

$router->group(['prefix' => 'admin', 'middleware' => ['xblock.auth']], function ($router) {
    $router->resource('users', UserAdminController::class);
});

This mirrors laravel-admin's module isolation and lets you gate whole admin sections behind different guards without touching the kernel.

Grid/form declarative config. Most day-to-day work is declarative — $grid->column('name'), $form->text('email')->rules('required|email'). Treat the declarative layer as the public API and avoid reaching into the kernel's internals for custom renderers unless you're building a new field type.

Auth integration via Lumen's guard. Point the kernel at an auth guard you already control. If your app uses JWT (common in Lumen APIs), wrap the kernel middleware in a guard adapter rather than swapping the kernel's own auth. This keeps session-based admin and token-based API auth from fighting.

Bootstrap/asset pipeline. The kernel likely serves its own backend assets. In Lumen you'll typically need to either (a) let the kernel publish assets to public/vendor/xblock and serve them through your web server, or (b) run a dedicated admin entrypoint. Decide early, because mixing asset strategies mid-project causes 404s that are painful to trace.

Testing seam. Write feature tests against your admin controllers (HTTP-level), not the kernel internals. The kernel's behavior on a given Lumen version is what you actually depend on; internal unit tests will be brittle across patch releases.

Gotchas and Tips

• Lumen ≠ Laravel. Package auto-discovery does not exist. Every service provider, facade alias, and config file must be registered manually in bootstrap/app.php. Missing $app->configure('xblock') is the #1 silent-failure cause — the kernel boots but sees an empty config.
• Config caching kills dynamic values. Lumen's php artisan config:cache will freeze your admin route prefix, guard names, and pagination settings. If admin behavior changes unpredictably after a deploy, clear the cache first.
• Middleware ordering matters. The kernel's auth middleware must run after your session/JWT middleware. If the admin returns 401 for a logged-in user, check $app->routeMiddleware ordering before you debug the kernel itself.
• Facades + Eloquent are prerequisites, not optional. The resource/grid layer assumes DB and Eloquent facades. Enabling them late means half the kernel works and half throws Class 'DB' not found.
• Sparse ecosystem = read the source. With 0 dependents and low stars, there's no Stack Overflow safety net. When a method signature surprises you, open vendor/xblock/kernel/src/ — it's the fastest path, and the source is the only authoritative docs for edge cases.
• Pin the version and lock it in CI. Because the package is pre-1.0-ish in adoption, minor bumps may rename config keys or field methods. Add a Composer constraint (e.g. ^0.1) and a smoke test that hits the admin index route on every deploy.
• Extension points to prefer: custom field types (subclass the base field), custom grid filters (implement the filter contract), and route middleware adapters. Avoid overriding the kernel's Kernel class or its request dispatcher — those are the most likely to change.
• Debugging tip: when a form/grid renders blank, first dump $kernel->toArray() or equivalent in a tinker session — the declarative layer usually fails silently on a malformed column/field definition rather than throwing.
• Lumen logging. Admin exceptions can vanish if the kernel catches and renders them. Set LOG_CHANNEL=stack and watch storage/logs/lumen.log while developing admin flows; the kernel tends to convert fatals into a styled error page without logging the trace.