Core Laravel Package

Getting Started

Install and boot in four steps

composer require gp247/core
php artisan vendor:publish --provider="GP247\Core\Providers\CoreServiceProvider"   # check the provider name in composer.json / src/Providers
php artisan migrate
php artisan gp247:user:create        # or seed/insert the first admin row manually

Then hit /admin (prefix is configurable in config/gp247-core.php). A separate admin guard/provider is registered by the package — confirm it lands in config/auth.php after publishing, otherwise login silently fails.

Where to look first, in this order

1. composer.json → autoload.files and extra.laravel.providers. The helper file(s) listed there are the real public API of this package; nearly everything else is internal plumbing.
2. config/gp247-core.php (name may differ slightly) — admin prefix, guard, middleware stack, template/layout, model bindings, pagination sizes.
3. src/Providers/ — what gets registered where, and which publishes() tags exist.
4. routes/ — the admin route group and its middleware; this is where your own routes must attach.
5. src/Controllers/Admin + src/Models — the base admin controller and the AdminUser/permission models you will extend.
6. resources/views/admin — the Blade layout you will extend and later override.

First use case: build one custom admin CRUD screen for an existing domain model (e.g. Order or Article) rather than a full app — scaffold the listing, the edit form, permissions, and the menu entry. That single vertical slice exercises auth, menu, grid, form, and translation layers and tells you within an hour whether the package fits.

Implementation Patterns

CRUD screens — extend, don't reimplement. The package is built around a base admin controller with a listing definition (columns, filters, sortable fields, per-row actions) and a form definition (field types, validation, language tabs). Your controller subclasses it and returns those definitions; the package renders the grid, handles pagination/search, and processes the submit. Keep business logic in your own service/repository and let the controller only describe fields — this is the difference between a 50-line and a 500-line screen.

Menu registration. Admin menu entries are typically contributed by config merge or a menu-registration hook from your module's service provider. Register items with an explicit permission key at the same time as you register the route; adding them in two separate places is the #1 source of "menu visible, 403 on click". If your sidebar is cached, clear the cache after adding entries.

Routing. Attach your routes inside the package's admin group so you inherit prefix + auth + permission middleware:

Route::group([
    'prefix'    => config('gp247-core.admin_prefix', 'admin'),
    'middleware' => ['web', 'admin'],
], function () {
    Route::get('articles', [ArticleController::class, 'index'])->name('admin_article.index');
});

Use the helper that builds admin URLs instead of hardcoding the prefix — the prefix is user-configurable, and hardcoded /admin/... links break on the first deploy where someone changes it.

Auth and permissions. Keep the package's admin guard separate from your front-end guard. For permissions, model them as roles → permission keys, and check them both in the menu and in the controller/middleware. Wrap destructive actions (delete, status change) in a permission check plus a POST/PATCH verb — GET-based deletes are a common pattern in admin scaffold packages and will bite you.

Multi-language fields. Text fields are usually stored per-language (one row per lang/code, or JSON columns). Use the package's form field type for translatable inputs so the tab UI and validation come free, and centralize a single currentAdminLang() helper in your app rather than scattering app()->getLocale() calls.

View overrides. Override, never edit vendor files: publish views and place them under resources/views/vendor/{package-namespace}/..., matching the original path exactly. Keep overrides to layout/navigation first; overriding grid internals couples you to the package's rendering internals and will break on upgrade.

Integration with the wider GP247 family. This package is the base layer for companion modules (front/shop/plugin/api-style packages). Register yours as a provider that publishes config, migrations, views, and lang under its own namespace, then add one line to config/app.php or bootstrap/providers.php. Version-lock the whole family together — mixing module versions across a major bump is where most breakage lives.

Assets. Admin CSS/JS is usually published into public/vendor/.... Don't hand-edit published assets; put your customizations in a separate file loaded after the package's layout section.

Gotchas and Tips

• You are effectively the only integration test. 4 stars and 0 dependents means upstream breakage won't be reported by anyone else. Pin an exact version ("gp247/core": "1.2.3", not ^1.2), commit composer.lock, and keep a three-step smoke test: admin login → open a grid → save a form.
• Treat every release as potentially breaking, even patch versions. Before upgrading, diff src/ and resources/views rather than reading the changelog; small packages like this often ship behavior changes without notes. Check that the tag you install actually exists on Packagist — release metadata for low-traffic packages is frequently stale or mis-dated.
• Publishing config/migrations is a one-way door. Published migrations live in your app forever; new package migrations won't appear after an upgrade. Prefer running the package's own migrations (unpublished) for schema you don't need to change, and publish only the config.
• Global helper function collisions. autoload.files helpers define global functions. If a name clashes with your app or another package you get a fatal "cannot redeclare" that surfaces only at boot. Grep your codebase before adding helpers of your own, and consider namespacing yours in a class.
• Silent failures in admin forms. Validation/exception handling in admin controllers often redirects back with withErrors or a flash message, so a broken save looks like "nothing happened". Reproduce with APP_DEBUG=true, tail storage/logs/laravel.log, and temporarily dd() in the base controller's processFormData/save hook to see whether your override is even called.
• Config and route caching. After changing the admin prefix, adding a menu item, or republishing config, run php artisan config:clear && php artisan route:clear && php artisan view:clear. A stale bootstrap/cache/config.php is the usual culprit for "my config change did nothing".
• Guard misconfiguration presents as an infinite login loop. Verify config/auth.php has the admin guard and provider, and that the provider's model points at the package's AdminUser (or your subclass) — not App\Models\User.
• Uploads and images need php artisan storage:link and a correctly configured disk/URL; admin thumbnails 404ing is almost always the symlink or APP_URL, not the package.
• Missing translations render raw keys. Keep one lang file per module and always add your keys to at least the fallback locale, or the admin UI shows admin.article.title to your client.
• Extension points to prefer: service-provider config merges, model binding via config (swap AdminUser for your subclass), view overrides, and event/listener hooks. Avoid subclassing deep internals or copying base-controller methods into your own code — that's the code that breaks on the next release.
• Onboarding cost is the real risk. With no community, your team's source of truth is the package source. Budget half a day for one developer to read src/ end-to-end and write a short internal note on the controller/menu/form lifecycle before the second developer touches it.