Quark Admin Laravel Package

Getting Started

Prerequisites. A Laravel 8/9-era application (PHP 8.0/8.1), MySQL, Composer, and Node 14/16 for the Ant Design Pro frontend. Because the last release was September 2022, start in a scratch Laravel project pinned to a compatible version before touching production — modern Laravel 10/11 will likely trip dependency constraints.

Install and wire up.

1. composer require quarkcms/quark-admin in the Laravel app.
2. Publish the package assets/config (php artisan vendor:publish and pick the quark-admin provider tags; confirm exact tags against the package's README, since tag names have shifted between Quark releases).
3. Run php artisan migrate to create the admin tables, then seed or create your first administrator account via the provided command or seeder.
4. Register the package service provider if it isn't auto-discovered, and check config/quark-admin.php for the API prefix, auth guard, and middleware stack.

Frontend. The admin UI is a separate Ant Design Pro SPA. Either use the bundled frontend directory or clone the Ant Design Pro scaffold the docs point to, then set the API base URL and dev proxy (config/proxy.ts in Ant Design Pro) to your Laravel host. npm install && npm run dev.

Where to look first.

• config/quark-admin.php — routing prefix, auth driver, menu registration.
• The package's base Controller / Resource classes — this is the extension surface you'll subclass.
• routes/ inside the package — shows the actual API contract the SPA expects.
• The generated app/Admin (or similarly named) directory after publishing — your day-to-day code lives here.

First use case. Take an existing Eloquent model (e.g. Product) and expose it as a CRUD screen: create a resource class declaring table columns and form fields, point a route at it, and the Ant Design Pro frontend will render list/form pages from the JSON schema without you writing React.

Implementation Patterns

Schema-driven resources. The core pattern is declarative: a PHP resource class defines the table columns, form fields, validation rules, and actions, and the API returns that as JSON for the SPA to render. Treat these classes as configuration, not logic — keep business rules in models/services and let the resource describe presentation and validation.

Standard CRUD flow.

• Resource class per model, subclassing the package base resource.
• index returns paginated rows with the declared columns; store/update validate against the declared form rules; destroy handles single and batch deletes.
• Override the base query method to add eager loading, global scopes, or tenant filters rather than post-processing in the controller — this is where N+1 problems get fixed.

Relationships. belongsTo fields typically render as searchable selects, hasMany as nested tables or repeatable sub-forms. Declare the relation name and display column on the field; avoid hand-rolling relation queries in the controller, since the frontend expects the schema's shape for option loading.

Custom actions and batch operations. Add toolbar buttons or row actions by registering them on the resource with a label, confirmation text, and an endpoint. Keep the endpoint idempotent and return the standard response envelope so the SPA can toast success/failure and refresh the table.

Auth and permissions. The package ships a token/session-based admin guard with role/menu tables. Wire your existing user model in via config if you don't want a second user table, and gate resources behind permission checks in the resource definition so the menu and API enforce the same rules.

Frontend extension. When the schema can't express a screen, drop a custom React page into the Ant Design Pro src/pages tree and register the route. Custom pages talk to ordinary Laravel controllers — you don't have to route everything through the package's resource layer.

Integration tips.

• Run the SPA as a standalone app behind the same domain (or with CORS configured) so auth cookies/tokens work without proxy hacks in production.
• Version the API prefix so you can run the admin alongside an existing public API.
• Use Laravel's api middleware group and keep the admin routes in a separate guard.

Gotchas and Tips

Maintenance and version drift. Last release 2022-09-09 with 166 stars means you are effectively adopting a semi-dormant package. Pin your Laravel, PHP, and Node versions in composer.json/.nvmrc, and commit the lockfiles. Expect to fork for bug fixes; budget for it up front.

License is NOASSERTION. GitHub couldn't classify the license. Before commercial use, read the repo's LICENSE file and, if it's ambiguous or absent, get clarification from the maintainer — don't assume MIT because it's on Packagist.

Chinese-first documentation. Docs, comments, and issue threads are largely in Chinese and the active community lives on Gitee/QQ groups rather than GitHub issues. Machine translation works for setup guides but be careful with nuanced config explanations; cross-check against the actual source.

Publishing collisions. The migrations may create tables that overlap with your app's (users, roles, menus). Read the published migrations before running them, and rename or skip conflicting ones. Similarly, the config publish can overwrite an existing config/quark-admin.php on upgrade — diff before re-publishing.

Frontend/backend contract drift. The SPA expects exact JSON shapes (pagination keys, field metadata, response envelope). If you upgrade the backend without the matching frontend build, tables render blank or forms lose fields. Keep the two versioned together, and treat the API responses as a public contract.

Debugging.

• Empty tables usually mean a schema mismatch or a permissions filter — inspect the list endpoint response in the network tab first, then the resource's query method.
• Form validation failures that don't surface in the UI are often Laravel validation errors in a different envelope than the SPA expects; check the raw 422 body.
• Use Telescope or the Laravel log for the API side; the SPA's console rarely shows backend exceptions.
• For auth loops, verify the guard name in config matches the middleware applied to the admin routes.

Extension points to prefer. Subclass the base resource/controller and register custom field types via the package's service provider rather than editing vendor code — you will need to composer update or fork eventually. Custom field classes are the cleanest way to add widget types without forking the frontend.

Performance. List endpoints are the usual culprit: the default query doesn't eager-load relations displayed as columns. Add with() in the resource query method, and watch SELECT ... WHERE id IN (...) storms from select-field option loading on large tables — cache those option lists.

Plan an exit ramp. Because the frontend is a standalone Ant Design Pro app, you can vendor it into your repo and maintain it independently of the PHP package. That decoupling is the package's best long-term asset — lean on it rather than depending on upstream releases.