Larament Laravel Package

Getting Started

Larament is a scaffold, not a library you require and call. The first decision is when you adopt it, because it only pays off on greenfield work.

laravel new my-admin --using=codewithdennis/larament

For an existing app, composer require codewithdennis/larament then php artisan larament:install. Treat that second path as a diff-and-merge exercise — you are pulling generated files into a codebase that already has opinions, and the drift risk is real.

After scaffolding, in order:

1. composer install && npm install && npm run build — get the Vite manifest real before you touch the panel, otherwise you'll chase "Unable to locate file in Vite manifest" while debugging something unrelated.
2. Read app/Providers/Filament/*PanelProvider.php. This is the file you will edit most. Panel path, auth guard, login/registration toggles, colors, navigation groups, middleware all live here.
3. Read app/Models/User.php and the policies/permissions wiring together. Larament ships role and permission management; before you add your own authorization layer, work out which one you now have. Duplicating it is the most common early mistake.
4. Skim composer.json scripts and .github/workflows/ — the quality gates (Pint, Larastan, Rector, Pest) are the part of the scaffold that actually costs money to reproduce, and they're the part most likely to be quietly disabled later. Don't be that team.
5. Open the generated profile and settings pages. They are your worked examples of Filament page classes, form schemas, and actions in whatever style the current major uses — copy that style rather than the Filament docs' older examples.

First use case: a CRUD surface over a small domain model. Create the model and migration, then:

php artisan make:filament-resource Customer --generate

--generate reads the table and drafts the form and table for you. You now have a working list/create/edit/delete page behind the panel's auth in under five minutes. That loop — model, resource, policy, test — is the entire day-to-day of this package.

Implementation Patterns

Model → Resource → Policy → Test, in that order. The scaffold's value compounds when each Filament resource lands with a policy in the same commit. Filament auto-discovers policies by naming convention; if a resource renders for a user who shouldn't see it, the policy is usually missing rather than misconfigured.

Group by domain, not by resource type. Use ->navigationGroup() consistently so the sidebar stays navigable past twenty resources. Decide the grouping vocabulary in week one; retrofitting it across forty resources is grunt work nobody wants.

Keep business logic out of the resource. Filament resources are presentation. Actions, services, and observers belong in app/Actions or app/Services. The moment you write a twelve-line ->action(function (Customer $record) { ... }) closure, you've made logic that no unit test can reach and no second surface can reuse.

Split large forms into schema classes. Filament supports extracting form(Schema $schema) into dedicated classes. Do this as soon as a form passes roughly one screen — it keeps the resource readable and makes the schema testable in isolation.

Use the panel provider for cross-cutting concerns. Tenancy, global middleware, auth guard changes, and render hooks belong there. Scattering them across resources produces a panel that behaves differently depending on which page you're on — a class of bug that is miserable to diagnose.

Let the test suite carry the weight. Pest is preconfigured; use it for the things Filament makes easy to break:

it('forbids a viewer from listing customers', function () {
    $this->actingAs(User::factory()->create())
        ->get(CustomerResource::getUrl('index'))
        ->assertForbidden();
});

Because authorization failures in admin panels are silent by design (the resource just vanishes from the nav), a test per resource per role is cheap insurance.

Run the quality gates locally before pushing.

vendor/bin/pint --dirty
vendor/bin/phpstan analyse
vendor/bin/rector --dry-run
php artisan test --compact

--dirty and --dry-run keep these from becoming a surprise in CI. Rector especially: it will happily rewrite code you didn't intend to touch, so preview before applying.

Use the local dev script. composer run dev (or the generated equivalent) runs the queue listener, Vite, and the server together. Forgetting the queue worker and then debugging why dispatched jobs never run is a rite of passage you can skip.

If the repo ships .ai/rules and agents/AGENTS.md, read them before generating code. They encode this project's conventions — file structure, naming, PHP style — and they override whatever a generic tool or assistant would default to.

Gotchas and Tips

There is no upstream to update to. Once scaffolded, you own the files. composer update codewithdennis/larament gets you the installer, not fixes to code already in your repo. Plan for a fork into an internal template repository, pinned to a minor version, with lockfiles committed — that is the difference between a template and an unmaintained skeleton.

Upgrades are a branch, not a merge button. Even a maintenance-only release (v7.0.8 was Composer, npm, and GitHub Actions bumps with no functional changes) needs a lockfile refresh, a green CI run, a production npm run build, and a smoke test of the admin and auth surfaces. Transitive dependency bumps surface in builds even when package code is untouched. Note that composer install succeeding tells you nothing about whether npm run build will.

Major-version boundaries are where work lives. Laravel and Filament alignment shifts concentrate risk at v7 → v8-style boundaries, not patches. Don't try to ride a patch release as a migration vehicle — read the major's changelog and plan a workstream.

Strict types plus Larastan is a floor, not a ceiling. The scaffold enables strict typing and static analysis; new code that ignores it will get waved through review and then fail the gate later. Keep the baseline level where it is and fix forward, rather than lowering it to accommodate one awkward file.

Permission caches bite after seeding. Role and permission data is frequently cached. If a fresh db:seed doesn't change what a user can see, clear the cache before you start debugging policies that were never wrong.

Filament navigation is authorization-aware, which hides bugs. A missing policy makes a resource silently disappear rather than error. When something "isn't showing up," check the policy and the user's roles before you check the resource registration.

Check your versions before copying examples. The agents/AGENTS.md guidance applies directly: run composer show --direct and read package.json rather than assuming an API. Filament majors change schema and action APIs meaningfully, and a lot of blog content and model training data predates what's installed.

Vite manifest, again. "Unable to locate file in Vite manifest" means the frontend wasn't built for the current environment — run npm run build locally, and make sure your deploy pipeline builds assets rather than shipping a gitignored public/build.

Don't fight the opinionated structure without a reason. The scaffold's defaults are the argument for using it. New base folders, a parallel authorization layer, or a second admin panel fragment the template and make the next project harder to bootstrap. If you disagree with a default, change it once at the template level, not per project.

Exit cost is low — behave like it. Worst case is refactoring code you already possess, not migrating off a vendor. Keep a thin layer of your own conventions on top of the scaffold so that abandonment by the maintainer costs configuration and template maintenance, rather than a rewrite. Name an owner for the fork and a pinned-version policy while the team is still small enough to remember them.