Core Laravel Package

Getting Started

craftile/core is a read-only subtree split of the monorepo at craftile/php. Treat this repo as a reading surface, not an install target.

• Do not composer require craftile/core. The canonical composer.json, tags, issue tracker, and PR flow live in craftile/php. Requiring the split directly gives you a package with no issues, no PRs, and version tags that may lag the parent. Install via composer require craftile/php (verify the exact install line against the parent README — the split provides no require hints of its own).
• Where to look first: craftile/php README and CHANGELOG, then the src/ tree of this split for the concrete class layout. The split is genuinely the fastest place to git log a diff of what changed in core between two versions — the folder history is cleaner here than in the monorepo.
• After install: publish the config (php artisan vendor:publish --provider="Craftile\...") and any migrations the parent docs mention. Confirm the service provider registers via auto-discovery; if it doesn't, add it to bootstrap/providers.php (Laravel 11+) or config/app.php.
• First use case: wire up one Resource against an existing Eloquent model — pick something already policy-governed like a Post or Product. Define the resource, point it at its model, and confirm you get a route, an index table, and a create/edit form out of the box. That single vertical slice tells you more about fit than reading the whole source tree.
• Prerequisite: skim the config file before writing any resource class. Everything (resource registration, panel mounting, field defaults) is wired through it, and the day-to-day ergonomics are entirely dictated by how that config is shaped.

Implementation Patterns

Craftile is declarative — you describe what a resource is, and it produces the routing, tables, forms, and validation. Day-to-day work happens almost entirely in resource classes plus a bit of panel configuration.

• Resource-per-model. One resource class per Eloquent model, holding the table definition (columns, filters, search fields) and the form schema (fields, validation rules). This is the primary extension point — reach for it before writing any Blade.
• Policy-driven authorization. Craftile maps to Laravel policies and gates you already have. Define the policy on the model as usual; Craftile picks it up. Don't hand-roll authorization in the resource unless the policy can't express it — this is the package's strongest "Laravel-native" promise and it's cheap to honor.
• Validation belongs in the form schema, not the request. Define rules on the form fields so both the create and update flows get them for free. If you find yourself writing FormRequest classes for admin CRUD, you're working against the grain.
• Table builders before custom columns. Reach for filters, search, and declarative columns first. Only drop to a custom field/view when the built-in column types don't express what you need — the extension API exists for that, but it's the escape hatch, not the default.
• Custom fields and actions as isolated classes. When you do need custom field types or row/bulk actions, keep them in their own classes under your app's namespace and register them explicitly. This is where you contain upgrade blast radius — when the upstream API shifts, your custom-field classes are the first thing to audit.
• Wrap everything behind your own interface. Even in a greenfield use of the package, define thin contracts (BlockRepository, ContentRenderer, or resource-registrar equivalents) that your app code calls. Craftile sits behind them. This is the difference between a breaking upstream change costing you an afternoon and costing you a sprint.
• Multi-panel setups. If the config supports multiple panels (verify against the parent docs), namespace resources per panel rather than conditionalizing a single resource. It keeps routes, policies, and menus isolated.
• Seed and test through the resource layer. Integration tests that hit the generated routes and assert on the generated table/form behavior catch upstream regressions in one place — cheaper than asserting on Craftile's internals directly.

Gotchas and Tips

• You are on a read-only split. No issues, no PRs, no releases here. Every bug report, feature request, and changelog entry belongs on craftile/php. Pin exact versions in composer.json — pre-1.0 with unproven semver means a caret range can bite you on a patch bump.
• Split lag. The mirror can fall behind the monorepo, and patches always land upstream. If you depend on a freshly merged fix, confirm the split tag actually includes it before you upgrade.
• Verify the frontend half matches. If Craftile ships a JS/asset component, pin the frontend and PHP versions to the same release. Mismatched halves are the most likely subtle runtime failure and the hardest to diagnose.
• Config quirks. Read the published config top-to-bottom once. Resource registration, panel mounting, field defaults, and route prefixes usually all live there — most "why isn't my resource showing up" symptoms resolve to a missing registration or a namespace mismatch in the config.
• Debugging rendering issues. When a page renders wrong, first check the resource's table/form schema, then the underlying model's relations (N+1 in table rows is a common surprise with declarative tables). Only after that reach for Craftile's internals — the failure is almost always in your declaration.
• Schema ownership. If Craftile publishes migrations, keep them under your app's control: publish, then edit, rather than relying on upstream migration updates. Silent schema changes across upgrades are a common integration hazard with packages that own their own tables.
• Escape hatch hygiene. Keep every custom field, action, and widget in its own class under your namespace, registered through a single registration point. That single file is your upgrade checklist and your replacement seam if you ever swap Craftile out.
• Testing discipline. Write contract tests against the specific Craftile surface you touch — resource registration, generated routes, table rendering, form validation — so upstream changes fail your build, not production.
• Don't reach into undocumented internals. The split makes internal classes look temptingly stable because they're right there in src/. They aren't. Stay on the public surface, wrap it, and treat anything not exposed in the parent docs as subject to change without notice.