Scaffold Laravel Package

Getting Started

Scaffold is a starter kit, not a library you require into an existing app. Treat the first hour as a fork-and-own exercise, not an integration.

Minimal steps

1. Confirm the Laravel version the Scaffold branch targets before you commit. The repo is version-branched (5.x, 6.x, etc., depending on the tag) and the boilerplate is pinned to the framework generation it shipped for. Pull the branch that matches your target Laravel version, or plan to upgrade it yourself.
2. Create the project in a throwaway directory first:

   composer create-project grafite/scaffold myapp --stability=dev
   # or, if the package ships as an installer:
   composer require grafite/scaffold && php artisan scaffold:install
   

   Check the README for the exact command for your tag — this is the single most version-sensitive step.
3. Configure .env (DB, APP_URL, mail), then php artisan migrate --seed. The seeders are what create the admin user, roles, and any sample content — a fresh install without seeding often leaves you with an empty dashboard and confusing 403s.
4. Log in at the dashboard route and click through every menu item once. You are looking for broken routes, missing assets, and permission errors; you want to find those now, not after you've added your own code.

Where to look first

• composer.json — this tells you what "opinionated" actually means for your tag. Scaffold is largely a curated assembly of other Grafite packages (roles/permissions, CRUD, forms, attributes) plus a theme. Enumerate those dependencies before designing anything; half of your app's behaviour lives in them, not in app/.
• routes/ — get a real map with php artisan route:list and note which routes are yours vs. package-registered.
• config/ — anything published by Scaffold and by its Grafite dependencies. These are your real tuning knobs.
• app/Http/Controllers/ and resources/views/ — find the dashboard/home controller and the layout blade. That layout is the thing you will edit most.
• database/migrations + database/seeds — the schema and role/permission seed data you inherit.

First use case

The canonical day-one task is: replace the sample resource with your own. Take whatever demo CRUD the boilerplate ships (posts, pages, whatever), run the Grafite CRUD generator against one of your models, and diff the generated output against the demo. That single exercise teaches you the generator's conventions, the view structure, and where the generated code expects to be customized — which is the whole mental model of the package.

Implementation Patterns

Follow the generation workflow, then edit the output. The intended loop is: write model + migration → generate controller/requests/views via the Grafite CRUD tooling → hand-tune the generated files. Generated code is meant to be edited, not re-generated. If you find yourself needing to regenerate often, you're fighting the conventions and should reconsider the schema instead.

Customize through the base classes and traits, not around them. Scaffold's models and controllers typically inherit from Grafite base classes and compose traits (roles, attributes, form helpers). Put cross-cutting behaviour — audit fields, scoping, formatting — into those traits or into an app-level base class that extends the Grafite one. Overriding framework-level behaviour by copying methods into each controller is the fastest route to an unmaintainable fork.

Publish, then override. For any vendor views/config you need to change, use vendor:publish once and commit the published files. Keep vendor overrides in resources/views/vendor/* and config/* rather than editing inside vendor/. This is also your only sane upgrade story if you ever pull upstream boilerplate changes.

Separate the admin surface from the public surface early. The boilerplate ships with an authenticated dashboard; decide on day one whether your app is (a) admin-first, where everything lives behind the dashboard, or (b) public-first with an admin back office. Roles/middleware wiring differs meaningfully between the two, and retrofitting is painful.

Version-pin and lock everything. Because Scaffold is a snapshot, composer update on day 30 can move Grafite dependencies underneath you. Commit composer.lock, and when you do update, do it on a branch with the test suite (or at minimum a manual click-through) as the gate.

Record your divergences. Keep a short SCAFFOLD.md at the repo root listing every file you changed from the original scaffold, and the upstream tag you started from. With no dependents and low activity, there is no upgrade path handed to you — you are the maintainer now.

Gotchas and Tips

• The boilerplate/packaging ambiguity. Some install paths give you a project skeleton; others give you a package plus an install command. These have completely different upgrade semantics. Verify which one you actually got by checking whether vendor/grafite/scaffold exists after install — if it does, you're carrying a dependency that may re-register routes and providers you didn't expect.
• Stale dependency risk is the headline concern. Low stars, no dependents, and an "opinionated boilerplate" framing mean the scaffolding is likely pinned to older Laravel/PHP versions. Audit composer.json constraints against your PHP version before you invest, and budget for an upgrade of the skeleton if you're not on the matching Laravel major.
• Route collisions. Package-registered routes can shadow yours (or vice versa) depending on provider boot order. Symptom: a controller action that "isn't being hit." Fix: php artisan route:list --path=your/segment and check which provider owns the route.
• Permission caching. Role/permission packages in this family commonly cache the permission map. After seeding or editing roles, a stale cache produces 403s that look like middleware bugs. Clear the app cache before debugging anything else.
• Missing assets. Theme assets frequently require a publish step (vendor:publish --tag=assets or similar) or a build step. A dashboard that renders unstyled is almost always this, not a broken layout.
• Seeders are load-bearing. Many "it 500s on first login" reports trace back to skipping --seed. Run migrations and seeds, then create your own user deliberately.
• Debugging order of operations: (1) is the provider registered? config/app.php / bootstrap/providers.php. (2) Is the route registered? route:list. (3) Are the views published? resources/views/vendor. (4) Is the cache stale? php artisan optimize:clear. That sequence resolves the large majority of "Scaffold isn't working" issues.
• Extension points worth knowing: the base model/controller classes, the form/attribute traits, the published config files, and Blade layout sections. Those four are where 90% of legitimate customization should land.
• When not to use it. If you need a maintained upgrade path, a modern Laravel version, or a team unfamiliar with the Grafite ecosystem, a first-party starter kit plus a handful of explicit packages will cost less than adopting and then maintaining an opinionated fork. Scaffold's value is highest for a solo dev or small team who wants a working admin panel and CRUD generator today and accepts ownership of the skeleton in exchange.