Framework Laravel Package

Getting Started

• Fastest path: composer create-project lavalite/lavalite myapp rather than adding lavalite/framework to a vanilla Laravel app. The framework alone is a thin layer — you also want lavalite/core, lavalite/user, lavalite/menu, lavalite/setting, and the admin theme for a working panel.
• Check the platform baseline first. The latest framework tag (v10.2.2) is documented as the first release for the 12.x line, i.e. it targets Laravel 12. On an existing project pin to an older tag that matches your Laravel/PHP version rather than forcing the upgrade; on a new project start from a skeleton that already ships the 12.x-compatible module set.
• First places to look: config/lavalite.php, the packages/ directory (one folder per module), Lavalite\Framework\Providers in vendor, and the active theme under public/themes/ (or resources/themes/).
• Run migrations with seeders (php artisan migrate --seed), then log in at /admin with the seeded admin account. If the panel 404s, check that the framework/module service providers are registered and routes aren't cached.
• First use case that exercises the whole stack: create a Page, attach it to a menu, and verify access via the user/team permissions. This touches model → repository → admin view → menu registration → ACL, which is the day-to-day loop.

Implementation Patterns

• Modules as packages. Build features in packages/<vendor>/<name> with the conventional layout: Providers/, Http/Controllers, Models, Repositories, resources/views, routes/web.php, config/, database/migrations. Register the service provider in config/app.php (or the framework's module loader if enabled).
• Repository pattern is the backbone. Extend the base repository, bind interface → concrete in a service provider ($this->app->bind(PageInterface::class, PageRepository::class)), and resolve through the container in controllers. Presenters/transformers are convention-based — a mismatched name silently yields empty output instead of an error.
• Admin CRUD reuse. Lean on the admin blade partials/layout and the framework's base request classes for validation/authorization. Don't hand-roll form markup; theme overrides get painful.
• Menus and permissions are DB-driven. Register menu entries in your module provider's boot() (or ship seeders), and gate controllers with can:permission middleware tied to the team/workflow tables.
• Workflow for state changes. Attach the workflow trait to models that need approvals/publishing, define states and transitions, and guard transitions in policies. Avoid ad-hoc status columns — you lose the audit trail and the admin UI wiring.
• Theming. Override a module view by placing a same-named file in the active theme. Use the theme() helper / Theme facade for asset paths, and keep custom CSS/JS in the theme's asset folder, not in the package.
• Settings. Declare keys in module config, persist via the admin, and read at runtime with the setting('group.key') helper. Cache reads but invalidate on save.
• Multi-guard auth. Assume Auth::guard('user') or 'admin' explicitly — don't rely on the default guard. Middleware and policy can() checks must match the guard the route uses.
• Integration tip. Wrap third-party SDK calls in a module "service" class resolved via the container, and expose data to Blade through view composers so theme overrides stay clean.
• Upgrade path in practice. When moving to the 12.x-targeted release, upgrade Laravel first, then the lavalite/* module set as a batch, then re-seed permissions/menus. Keep custom code confined to your own module and theme folders so the framework bump stays a composer update.

Gotchas and Tips

• lavalite/framework is not standalone. It expects sibling packages (core, user, menu, setting, workflow/team). Installing it alone produces a half-broken admin — pull the metapackage or the full project.
• The version numbers don't line up. The tag v10.2.2 is described as the first release for the 12.x line, so the package tag does not track the Laravel version it supports. Don't infer Laravel compatibility from the tag — read the release notes for each tag and pin by constraint, not by "looks recent."
• A framework-only bump is not a safe upgrade. The 12.x line is a platform change; modules, theme assets and published config can lag behind. Confirm each lavalite/* dependency has a release supporting the same Laravel version before updating, and expect to re-run vendor:publish for changed tags.
• Layout assumptions are strict. Module auto-discovery, theme resolution, and admin route prefixes depend on directory conventions. Moving or renaming packages without updating the loader fails silently.
• Clear caches constantly in dev. Run php artisan config:clear and route:clear after adding modules, menus, or settings — cached config/routes routinely make new registrations invisible. This bites hardest immediately after a version upgrade, where stale cached config masks new keys.
• Migration order matters (user → team → menu → page). On a scratch DB, prefer migrate:fresh --seed over debugging individual migration failures.
• Naming conventions are unforgiving. Interface names, Presenter classes, and transformer methods must match what the base repository expects, or you get blank/null output with no exception thrown.
• Menus and permissions live in the DB. Editing code alone won't change access. If a menu item "disappears," inspect the menus/permissions tables before suspecting your service provider — and re-seed them after a major upgrade.
• Workflow transitions fail quietly when the current state doesn't map to a transition. Log the transition name and current state, and verify the guard in the policy matches the route guard.
• Debugging toolkit: php artisan route:list --path=admin, Log::debug() inside provider boot(), and dd() on the resolved repository. Vendor source is the real documentation — search for the base classes when the docs are thin.
• Extension points to prefer over editing vendor: module provider boot()/register(), any Action/Filter-style hooks your version exposes, theme view composers, and repository boot() methods.
• Version drift is the top breakage source. Pin lavalite/framework and every lavalite/* module to a compatible constraint in composer.json, and smoke-test /admin after every bump — login, one CRUD save, one menu render, one permission-gated route.
• Publish assets. Missing admin CSS usually means unpublished theme/module assets — run vendor:publish for the relevant tags and clear the public/ cache.