Mojito Laravel Package

Getting Started

Mojito is a self-contained admin SPA (Laravel API + Vue 2 + Element UI) that gives you menu management, RBAC, and CRUD scaffolding without building an admin from scratch. Before installing, confirm the package's composer.json constraints against your app — the last release is from September 2023, so expect it to target Laravel 8/9/10 and PHP 7.4–8.1 rather than the newest framework.

Minimal path:

1. composer require moell/mojito
2. Publish config, migrations, and compiled assets: php artisan vendor:publish --provider="Moell\Mojito\MojitoServiceProvider"
3. php artisan migrate — creates the admin, role, permission, menu, and log tables.
4. Create the first administrator (the package ships an installer/console command; otherwise insert a row via tinker using the MojitoAdmin model with a hashed password).
5. Open the configured admin prefix (default /admin), log in, and use the built-in Menu / Role / Permission / Admin screens.

Where to look first:

• config/mojito.php — route prefix, auth guard/provider, middleware stack, upload disk, and pagination. This is where 80% of "why isn't it working" answers live.
• The package's routes/ file — shows the guard and middleware protecting the JSON API.
• resources/js in the package (after publishing) — the Vue entry point, router, and view registry you extend for custom pages.
• The bundled admin controllers under src/Http/Controllers — they are the reference implementation for your own resource controllers.

First real use case: point it at an existing Eloquent model (e.g. Product), register a menu entry, assign the permission to a role, and get list/filter/create/edit/delete in the admin for free instead of hand-rolling Blade CRUD screens.

Implementation Patterns

Guard and provider wiring. Mojito ships its own mojito guard backed by an admins table, separate from your web guard. Keep it isolated so front-end users and back-office users never share sessions, and attach mojito.auth + mojito.permission middleware to any route you add yourself.

Permission-driven menus. The day-to-day workflow is: create a permission node (usually named after the route or resource.action), attach it to a role, then attach a menu item that references that permission. If a menu appears but 403s on click, the permission is missing from the role; if the route 403s but works when hit directly, the menu cache is stale.

Resource/CRUD controllers. Follow the shape of the built-in controllers: a controller per model, index returning paginated JSON, store/update using FormRequest-style validation, and destroy. The frontend expects a consistent response envelope, so copy the pagination and error-response format from an existing Mojito controller rather than inventing your own — mismatched envelopes are the most common cause of empty tables.

Scaffolding. Use the package's resource generator (if available in your version) to produce the controller/model/menu/permission skeleton, then edit. It saves the tedious part — permission and menu registration — even when you rewrite the query logic.

Custom Vue pages. Anything the built-in generator can't express (dashboards, charts, multi-step forms) is added by dropping a component into the published resources/js/mojito tree, registering it in the router, and rebuilding assets. Treat this as a fork of the frontend: pin your Node version and commit the lockfile.

Integration tips.

• Use Mojito for internal/back-office surfaces only; don't try to serve a public-facing API from it.
• Reuse your existing models via relationships rather than duplicating tables for the admin.
• For file uploads, point the config at an S3 or public disk and run storage:link; the upload endpoint returns paths the frontend expects verbatim.
• Add the activity-log trait to models where audit trails matter — it's cheaper than bolting on a separate package.
• For anything the UI can't do (bulk imports, report exports), add a small JSON endpoint behind the same guard and trigger it from a custom Vue page.

Gotchas and Tips

Version drift is the main risk. Vue 2 and Element UI are end-of-life, and the frontend build assumes Webpack-era tooling. Expect npm install failures on Node 18+; use nvm with Node 14/16, or vendor the compiled assets and avoid rebuilding unless you must. Similarly, on newer Laravel you may need --ignore-platform-reqs or a fork.

Guard misconfiguration. The admin guard needs its own provider entry in config/auth.php and, if you use password resets, its own broker. A login that "succeeds" but immediately 401s on every API call usually means the session guard name in the axios request doesn't match the route's middleware.

CSRF on the SPA. Custom axios calls need the X-XSRF-TOKEN header; the built-in client handles it, hand-written fetch calls won't, and the resulting 419 looks like an auth bug.

Cache clearing. Permission and menu lookups are cached. After changing roles, permissions, or menu order in the database (especially via seeders), run php artisan cache:clear or the UI will lie to you.

Route caching conflicts. The admin SPA needs a catch-all route for client-side routing. If you enable route:cache, place the admin catch-all carefully so it doesn't swallow your app's API routes — a very common production-only bug.

Never edit vendor/. Published views can be overridden in resources/views/vendor/mojito; config in config/mojito.php; frontend in the published resources/js. Upgrades overwrite published assets on every vendor:publish, so re-publish deliberately and diff before committing.

Migration ordering. Run Mojito's migrations before any of your own migrations that reference its tables, and avoid editing the published migrations — add new ones instead.

Config caching surprises. If the admin prefix or guard changed but nothing moved, you have a stale bootstrap/cache/config.php. php artisan config:clear before debugging further.

Debugging 403s. Log the permission name the menu resolves to, then confirm it exists and is attached to the current admin's role. The gap between "menu visible" and "route authorized" is almost always a naming mismatch, not a middleware bug.

Extension points to prefer. The Mojito facade (menu/permission helpers), model traits, and the config file — these survive upgrades, whereas patched vendor controllers do not.