Backend Laravel Package

Getting Started

The package is a backend admin layer (routes + controllers + views + menus) for the iBrand e-commerce stack, built on top of encore/laravel-admin. You are not learning a new framework — you are learning which laravel-admin conventions it bundles. Read in this order:

1. composer.json — the hard version pins are the real story (laravel/framework, encore/laravel-admin, ibrand/component).
2. src/Providers/*ServiceProvider.php — what is registered (routes, views, migrations, menu) and under what config keys.
3. config/*.php — route prefix, middleware, table names, feature toggles.
4. routes/ — every admin URL the package owns.
5. src/Http/Controllers/ — the grid/form layout you will be copying.

Typical install (expect to pin an old PHP/Laravel):

composer require ibrand/backend
# service provider (Laravel <5.5 or no discovery)
php artisan vendor:publish --provider="iBrand\\Backend\\Providers\\BackendServiceProvider"
php artisan migrate
php artisan admin:publish
php artisan admin:install   # creates the admin guard + default user
php artisan admin:menu       # if menus are seeded/migrated

First use case: boot a Laravel 5.5–5.7 app, install laravel-admin, add this package, log into /admin, create a product via the grid, then place a test order and inspect the order detail screen. That single flow touches the package's real surface: product CRUD, SKU/attribute handling, and order state management. If that flow works, the rest of the package is variations on it.

If the install fights you, do not debug composer on PHP 8 — build the environment first (see Gotchas) and only then evaluate.

Implementation Patterns

Treat it as a scaffold, not a library. With 12 stars, a 2018 last release, and zero dependents, you should not be at the mercy of its release cadence. Two viable patterns:

• Dependency mode — acceptable only if you will never upgrade Laravel. Lock the versions and accept the package as-is.
• Vendor/fork mode (recommended) — copy src/, resources/views/, routes/, and migrations into your app under a Backend namespace, then delete the composer requirement. You get the admin screens and full freedom to change them. This is what nearly everyone ends up doing when a base package goes dormant.

Extending a controller is the normal day-to-day move: subclass the package controller, override grid() / form() / detail(), and register your class in app/Admin/routes.php after the package's routes so yours win.

// app/Admin/Controllers/ProductController.php
class ProductController extends \iBrand\Backend\Http\Controllers\ProductController
{
    protected function grid()
    {
        $grid = parent::grid();
        $grid->column('sales', '销量')->sortable();
        $grid->model()->withCount('orders');
        return $grid;
    }
}

Use the same subclass trick for form() when you need a field the vendor omitted, and detail() for order timelines.

Menu wiring. laravel-admin renders the sidebar from the admin_menu table, not from code. Whatever the package seeds, you will re-point it at your overridden controllers. Seed menus idempotently by uri, or you get duplicate entries every deploy.

Override views before you override classes. resources/views/vendor/<pkg>/... (publish with vendor:publish) covers most cosmetic needs — money formatting, status badges, table columns — without touching PHP.

Bind, don't patch. The package resolves models/repositories through the container. Where a binding exists, app()->bind() your own implementation in a service provider; it survives package updates where a hacked file would not.

Feature-flag at the route level. If you only need products and orders, do not delete code — wrap unused route groups in a config check so route:list shows a lean surface and the RBAC permission list stays honest.

Pair it with ibrand/component deliberately. The backend is thin; domain logic (cart, pricing, stock, order transitions) lives in the component package. Business rules belong there (or in your app), never in the admin controller. Admin controllers are HTTP/UI shells.

Gotchas and Tips

The version cliff is the main risk. A 2018-12 release means Laravel 5.x, laravel-admin 1.x, and PHP 7.1–7.2. On modern PHP, composer install dies on transitive pins. Don't force it with --ignore-platform-reqs unless you enjoy runtime deprecation noise — run it in a PHP 7.2 container, or just vendor the source. It will not work on Laravel 9+/laravel-admin 2.x; the admin APIs changed (Encore\Admin vs Dcat\Admin is a different package entirely).

Migrations collide. Check for create_products_table-style names and table prefixes before php artisan migrate on an existing DB. If names clash, publish migrations and rename/guard with Schema::hasTable().

Menu and route caches bite. After changing menus or routes: php artisan admin:menu (or clear the menu cache), and php artisan route:clear. A stale admin_menu row pointing at a controller you deleted gives a 404 with no error — check the uri column, not the logs.

Assets look broken until you publish. php artisan admin:publish is required for CSS/JS. A blank sidebar is usually an asset 404, not an auth problem.

Auth guard mismatch. The package assumes laravel-admin's admin guard and its admin_users table. If your config/admin.php uses a different guard/model, everything 403s while login "succeeds". Verify config/auth.php guards before touching package code.

RBAC is opt-in and easy to forget. Registering new routes does not create permissions. Under laravel-admin's role system, add permission nodes or a non-super-admin sees an empty menu — a classic "it works for me (super admin)" bug.

Debugging order. route:list (did routes register?) → php artisan tinker on the model binding → view source path (php artisan view:clear) → config dump. Nine times out of ten the answer is a service provider loading in the wrong order or a cached config.

Extension points, ranked by safety: config file → view override → controller subclass → container binding → editing vendor code (never). If you find yourself at the last one, switch to vendor/fork mode.

Don't expect zh-CN→multi-language to be free. Copy is Chinese-first and often hardcoded in views. Budget for translation files or view overrides if you need i18n; the admin's locale setting alone won't cover it. Same for currency and date formatting in grids.

Treat it as reference material. Its genuine value is a worked example of laravel-admin grids/forms for an e-commerce domain — product/SKU/order shapes. Read it, copy the good parts, and keep your app in control.