Uranus Laravel Package

Getting Started

Confirm you qualify first. Uranus is only relevant if the project is already Laravel + Filament (or mid-decision on Filament). It is a Lara Zeus-family package built on the TALL stack with panel-scoped registration and Blade/Tailwind views. If the front end is Inertia/React/Vue, or the backend is not Laravel, stop here — the integration cost exceeds anything the package saves.

Do not composer require into the main application. The repo is archived (last release 2024-04-01), so there will be no upstream fixes. Clone it into a sandbox branch instead:

git clone https://github.com/lara-zeus/uranus /tmp/uranus && cd /tmp/uranus

Read in this order, before writing any integration code:

1. composer.json — the php, laravel/framework, and filament/filament constraints. This is the single highest-signal file: it tells you which Filament major the package is frozen against and whether it resolves against your lockfile at all.
2. src/ — find the service provider and, if present, the panel plugin class (the family convention is a UranusPlugin-style class implementing Filament\Contracts\Plugin; verify the actual name). This is also where you resolve the description contradiction.
3. config/ — what is publishable, what defaults are baked in.
4. README.md — last, not first. The available descriptions disagree about what the package even is.

Resolve the purpose contradiction as your first deliverable. One description says "convert any admin panel to filamentphp" (a conversion/codegen tool with write access to existing admin surfaces). The other describes a generic config-driven Laravel package with service provider and config publishing. Those are different products with different risk profiles and different day-to-day usage. Everything downstream — how you spike it, how you gate it, how you roll back — depends on which one it actually is. If half a day of source reading does not settle it, that is itself the answer.

First use case: one throwaway panel, one screen. Not a migration. Register the plugin on a scratch panel provider in a sandbox branch, run php artisan filament:assets, and confirm three things in order — the nav item appears, the route resolves, an authenticated request renders. That is the whole of day one. Anything beyond it is earned.

Implementation Patterns

Vendor a fork; pin to the commit SHA. Because upstream is archived, the only coherent integration is an owned fork under MIT with a named internal owner. Pin to the exact v1.0.0 commit in composer.json as a VCS repository. Never float ^1.0 — the constraint advertises a maintenance guarantee that does not exist, and composer update will eventually resolve against an untested combination or fail outright.

Register on a specific PanelProvider, never globally. This is the pattern that matters most and the one most likely to be got wrong. Registration belongs in the concrete provider for the panel that needs it:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(UranusPlugin::make()) // verify class name in src/
        // ...
}

Registering in AppServiceProvider or a global boot hook means a customer-facing panel can accidentally inherit the plugin. Scope it, and gate it:

->when(config('uranus.enabled'), fn (Panel $p) => $p->plugin(UranusPlugin::make()))

Ship with URANUS_ENABLED=false as the default so nothing is live by accident.

Treat the spike as a read-only reference implementation. The highest-value pattern here is extraction, not adoption: install in an isolated branch, port one representative screen, then write the same screen as a hand-rolled Filament resource. Compare them. The delta is the real answer to build-vs-fork, and it is the number that should drive the decision — not the licence price of zero. Budget two days, time-boxed, fully reversible.

Publish config, then override in the app. Follow the family convention: publish the config file into config/ and edit there rather than reaching into the package. Same for Blade views — publish and override in resources/views/vendor/... if the package registers a view namespace. Overrides in your app survive a fork bump; overrides inside the vendor directory do not.

Write the smoke tests the package probably does not have. There are no coverage claims in the supplied artefacts. Before any pilot, add: one authenticated render test for a page the plugin provides, one negative 403 test to establish what the default authorization behaviour actually is, and one test that asserts the plugin is absent from the panel when the env flag is off. That third test is the one that protects production.

If it turns out to be a conversion/codegen tool, invert the workflow. Run it against a clean git tree, on a branch, with the diff reviewed before anything is committed. Never point a codegen step at a live admin surface on a dirty working copy — a partially converted panel is materially worse than a broken page and much harder to roll back. If the output is not reversible via git checkout, stop and reconsider.

Extract, then drop the dependency. The durable pattern for an archived package: harvest the approach into your own application code (a Filament resource, a bespoke conversion layer), delete the composer require, and keep the spike branch as documentation. You get the prior art without carrying the maintenance.

Gotchas and Tips

Archived status dominates every other signal. No security fixes, no disclosure process, no CVE response, no PHP floor bumps, no compatibility work for future Laravel or Filament majors. If the question "who fixes this when Filament ships its next major?" is answered "we do, indefinitely," you are running a fork evaluation, not a dependency evaluation — and it needs to be priced as a build decision.

Filament major coupling is the most probable failure point. Panel plugins bind tightly to Filament internals. A package frozen in April 2024 is almost certainly pinned to one major, which caps your own upgrade path from the day you adopt it. Check composer.json against your lockfile in a throwaway branch before scoping anything.

The v1.0.0 release notes are an auto-generated changelog link. No features, no breaking changes, no migration guide. A 1.0.0 whose only changelog entry is a commit link, immediately followed by archival, means the semver commitment was a formality. There is no pre-1.0 → 1.0 upgrade path documented; do not assume one exists.

Zero dependents means zero de-risking. Fifteen stars and no dependent projects is not "early," it is "unexercised." There is no production corpus to find defects before you do, no issue history to search, no third-party write-ups to calibrate against. Every debugging hour is unbudgeted and yours alone. Build that into the estimate rather than discovering it.

Check what it writes. Unknown until you read the source: does it publish migrations, routes, views, or assets? Does it own database tables? Are auth, tenancy, or multi-panel assumptions baked in? Migration rollback and route/view namespace collisions with existing panels are both real failure modes. Confirm the migration ordering and that migrate:rollback is clean before any non-scratch use.

Do not trust the README as a capability claim. The two available descriptions describe two different products and neither is corroborated by the release notes. Treat every claim — including the "convert any admin panel" headline — as a hypothesis until read from src/.

Extension points, in order of preference: config overrides → published view overrides → service container bindings in your own provider → patching the fork. Reaching for the fourth before exhausting the first three is how a spike turns into an unowned fork.

If you proceed past the spike, name an owner. An archived fork with no named internal owner is a future incident nobody is accountable for. That is the whole lesson this package teaches, and it is worth more than the package.