Daimakuai Laravel Package

Getting Started

Daimakuai is a Laravel-era admin scaffolding package: it ships Blade page components (list/detail/edit layouts) and form elements so a CRUD screen is mostly markup plus a thin controller. Treat it as a view-layer toolkit, not a full admin framework — there is no Nova/Filament-style resource generator.

v2.0.0 is the important new fact, and it arrives with an empty changelog. A major version bump away from the long-lived 2017 line is either (a) a genuine modernization — new Laravel/PHP constraints, Vite, Bootstrap 5 — or (b) a repackaging/rename with breaking changes to view names and config keys and nothing else. The release notes don't say. Do not assume either; verify before you plan.

1. Verify constraints before you assume a fork. The old assessment's central premise — that you must fork to escape laravel/framework: 5.4.*|5.5.* — is now unproven. Start with composer show jblv/daimakuai --all (or the Packagist page) and read the v2.0.0 composer.json: framework/PHP constraints, extra.laravel.providers, and whether assets are shipped via Mix, Vite, or raw files. If constraints reach Laravel 9/10/11, you can composer require jblv/daimakuai:^2.0 directly and skip the whole fork dance.
2. Reconstruct the changelog yourself. With no release notes, the diff is the documentation: git diff <last-1.x-tag>..v2.0.0 -- composer.json resources/views config in a clone. Look specifically for renamed view paths, changed config keys, new/removed publish tags, and CSS framework swaps. Budget an hour for this — it will save you a day of "why is the layout broken."
3. Register the provider. Check extra.laravel.providers for auto-discovery; otherwise add it to config/app.php (or bootstrap/providers.php on Laravel 11+). Run php artisan vendor:publish and confirm the tags it exposes — v2 may have renamed them.
4. Read these three things before writing code, in order: the README (still likely Chinese-only and the only real documentation), the service provider in src/ (view namespaces, Blade directives, routes, config keys), and the published resources/views/vendor/daimakuai tree. The view namespace is the API; there is no PHPDoc worth trusting.
5. First use case: one list page + one form page. Create a controller that returns two package views, point two routes at it, and extend the package layout. If you can render a table of User::paginate() and a form that posts back successfully, you have validated the whole integration — everything else is variations on that.

Implementation Patterns

• Layout inheritance over composition. The package's pages assume you extend a master layout (@extends('daimakuai::layouts.app')) and fill named sections for content, breadcrumbs, and scripts. Adopt that layout as your admin shell and put your sidebar/menu in the published copy rather than building a parallel one — mixing layouts is where most of the CSS breakage comes from. Re-check the namespace prefix in v2; a daimakuai:: → daimakuai-v2:: rename is exactly the kind of thing a major bump carries.
• Form elements as Blade partials/includes. The value proposition is that inputs, selects, date pickers, and file uploads are pre-wrapped with label, error slot, and validation-state classes. Use them uniformly, and pass old input through old('field', $model->field) yourself — the package generally does not do model binding for you.
• Thin controller, fat view. The intended workflow is: controller loads the model/collection and returns a view; the view composes package components. Keep query logic in scopes/repositories so the view stays declarative — otherwise these templates become the place where business rules go to die.
• Per-resource integration. One controller per admin resource (Admin\UserController, Admin\PostController), each returning an index/form view pair, wrapped in an admin route group with your auth middleware. Do not let the package register its own public routes in production without reviewing them.
• Publish-and-own. Publish views and assets into your app, commit them, and treat the vendor copy as a starting point. Editing vendor/ is the fastest path to a broken deploy; a published, version-controlled view layer is the only way this package stays maintainable.
• Asset pipeline. Verify what v2 actually ships. If it's still jQuery + Bootstrap 3 with pre-built CSS/JS copied by vendor:publish, pull its CSS in as a separate stylesheet scoped to admin pages and load its JS after your own bundle — do not merge it into your main bundle. If v2 moved to Vite, you can integrate properly, but check whether it expects your Vite config or ships its own manifest.
• Extension points worth knowing: view namespace overrides (publish and edit), a config file for menu/layout/pagination options, Blade @include of individual form element partials (so you can swap one input type without forking), and route middleware applied at your group level. There is no documented plugin/registry API — assume none.

Gotchas and Tips

• An empty changelog on a major bump is itself a risk signal. Semver gives you no information about what broke. Treat v2.0.0 as a new dependency, not an upgrade: spike it in a branch, diff the published view/config trees against your 1.x copy, and only then decide. If the repo has no tags between the 2017 release and v2.0.0, be extra careful — the jump may be bulk-edited code that was never run against a modern Laravel.
• Re-test the dependency wall rather than repeating the old verdict. If constraints are still 5.4/5.5 + PHP 7.0, fall back to the fork: a path repository with "options": {"symlink": true}, bump the framework/PHP constraints, then fix what actually breaks (usually str_*/array_* helpers and Blade $loop assumptions — mostly fine on 5.6–5.8, rougher on 8+).
• Package discovery does not retroactively apply. If composer.json lacks an extra.laravel.providers block, nothing loads and you get "View [daimakuai::...] not found." Register manually — that error almost always means provider-not-registered or views-not-published, in that order. On Laravel 11+, remember the provider goes in bootstrap/providers.php, not config/app.php.
• Debugging checklist for blank/ugly pages: php artisan view:clear after publishing; php artisan vendor:publish --tag=... --force to re-copy assets (confirm the tag name — v2 may have renamed it); check that the published JS/CSS path is actually web-accessible; open the browser console for a missing jQuery or a 404 on the v2 asset bundle, which will silently no-op the package's JS.
• Namespace every view reference. Use daimakuai::pages.index, never a bare pages.index. Once you publish, your local resources/views/vendor/daimakuai/... silently shadows the package copy — that is both the fix and the trap when debugging with a colleague who hasn't published.
• Stale published views after upgrading. If you adopt v2 over an existing 1.x install, your committed resources/views/vendor/daimakuai copy masks every view change in the new release. Do the upgrade with published views deleted first, then re-publish and re-apply your customizations — otherwise you are running 1.x markup against 2.x PHP and will chase phantom bugs.
• Chinese defaults leak into the UI. Labels, pagination text, and validation messages may be hardcoded or come from a lang/zh-CN file. Grep the published views for CJK characters and replace them, or set up a translation file if the package supports one.
• CSRF and method spoofing. Forms built from the package's partials may not include @csrf/@method. Verify every generated form posts correctly — a silently failing 419 on save is the classic symptom.
• Escape hatch before you commit. Spike one screen in Daimakuai and one in a maintained alternative (Filament, Backpack, or plain Blade components). If the package's form partials are the only thing you actually want, copy them into resources/views/components and drop the dependency — you keep the markup value and lose the abandoned-vendor liability.
• Pin exactly. Use ^2.0 once verified — never dev-master, and never an unconstrained * on a package whose release history is sparse. If v2 turns out to be unusable and you keep a fork, tag it and reference it by commit.