Admin Module Laravel Package

Getting Started

This package is still in the 0.0.x line, so treat every release as potentially breaking and pin an exact version in composer.json ("hafijul233/admin-module": "0.0.7") rather than using ^0.0.

1. Install and register. Require the package, then confirm the service provider is discovered (Laravel 5.5+ auto-discovery) or add it manually to config/app.php. If the provider is not listed after install, run composer dump-autoload before debugging anything else — a stale classmap is the single most common cause of "class not found" in this kind of module package.
2. Publish the scaffolding. Run php artisan vendor:publish and select the admin-module provider tag. You typically get a config file (config/admin-module.php), migrations, and possibly view/asset stubs. Read the config file top to bottom before running anything — route prefix, middleware stack, guard, and table names are usually all in there, and changing them after migrations have run is painful.
3. Migrate, then install. Run php artisan migrate, then any install/seed command the README documents (commonly php artisan admin:install). Do this on a fresh database first; this package writes to auth/role tables and a half-populated database makes failures hard to read.
4. First use case: scaffold one CRUD module end-to-end. Pick a throwaway resource (e.g. Post) and run the module generator. The point of the first run is to see the generated file layout — controller, model, requests, routes, views — so you know what the package owns versus what you own. Everything it generates is yours to edit; the package is a scaffolder, not a runtime framework.

Where to look first: the README's command list, config/admin-module.php, and the src/Helpers directory. That helpers directory is exactly what 0.0.7 touched, so it is worth a five-minute read before you build on it.

Implementation Patterns

Generate, then own the output. The healthy workflow is: run the generator once per domain entity, immediately commit the generated files, then edit them freely. Do not plan to re-run the generator over existing code — scaffolders of this type overwrite or skip silently, and you will lose customisations. If you need a second pass, generate into a scratch namespace and diff.

Wrap helpers behind your own layer. Because the helper class was the subject of a bugfix in 0.0.7, do not call package helpers directly from Blade views and controllers scattered across the codebase. Add a thin app-level helper file or a small facade that proxies to the package's helpers, and call that. When a 0.0.x release changes a signature, you fix one file instead of grepping fifty views.

Module-per-domain, registered explicitly. If the package supports module route/menu registration, prefer registering each module's routes and menu entries from your own service provider or a small ModuleRegistry class rather than relying on auto-scanning of a modules directory. Auto-discovery is convenient but opaque — when a route 404s you want a single file to open.

Keep generated controllers thin. The generated controllers usually contain the full resource flow inline. Split validation into FormRequests and move any query logic into the model or a repository as you touch each module, otherwise the second feature request on any module means editing a 200-line controller method.

Layer on your auth, don't fight it. Point the package's guard/middleware config at your existing web guard and role setup. If you already use Gates/Policies, wire the generated controllers through $this->authorize() rather than adding a second permission system in the admin module's config.

Test the generated surface once. Write one feature test per generated module hitting index/store/update/destroy. These catch the majority of breakage when you bump the package, because generator output changes are usually visible in routing, request validation, and redirect targets.

Gotchas and Tips

• Version pinning is not optional. 0.0.7 fixing a "helper class issue" tells you the helper API is still in flux. Use "0.0.7" exactly and review each changelog before bumping. A ^0.0.6 constraint can pull in a patch that renames a helper.
• Run composer dump-autoload after every upgrade. Helper classes in these packages are frequently loaded via a files autoload entry or a classmap rather than PSR-4. Composer caches both; a "helper not found" error after upgrading is almost always a stale autoloader, not a broken release.
• Republish vs. merge. vendor:publish --force will clobber your edited config. Diff the package's config/admin-module.php against yours after each upgrade and merge new keys manually — silently missing config keys show up later as null-pointer style errors deep in the package.
• Migration ordering. Published migrations get timestamped at publish time, not at package release time. If you publish 0.0.7's migrations into an app that already ran 0.0.6's, check for duplicate table creation before running migrate.
• Namespace collisions on generated classes. Generating two modules with similar names produces two PostController classes; if they land in the same namespace you get a fatal redeclare. Confirm the generator namespaces by module before generating more than a couple.
• Debugging generated routes. Use php artisan route:list --path=admin (adjust to your configured prefix) to confirm what was actually registered. Most "the module doesn't work" reports resolve to a route that was never registered because the module's route file wasn't included.
• Extension points. The config file and the published views are the intended extension surface. Prefer overriding a published view or config value over subclassing package internals — internal classes in a 0.0.x package move without deprecation notices.