Crazyphp Laravel Package

Getting Started

CrazyPHP is not a library you composer require into an existing Laravel app — it is an opinionated scaffold plus CLI code generator that wants to own the project layout. Treat your first hour as reconnaissance, not integration.

Minimum steps

1. Isolate. Create a throwaway repo. Do not install this into a shared or production repository until the spike below completes.
2. Pin exactly. Install kekefreedog/crazyphp at 0.10.0 (or use composer create-project if the repo documents one). Never float to ^0.10 — pre-1.0 minors are permitted to break.
3. Read the layout before the docs. Open composer.json, then the console entry point at the project root, then the app directory (controllers/views), the routes file, and the config directory. Names differ from Laravel; map them once on paper.
4. Enumerate the CLI. Run the console entry point with no arguments and with --help. The generator commands are the actual product — list them, note which ones create entities, controllers, routes, and migrations.
5. Build one vertical slice. One entity → its table/migration → one controller action → one route → one view that renders the record. Stop there. That single slice tells you more than the README.

Where to look first (in order): composer.json (PHP ceiling, Illuminate range, template engine) → console --help → routes file → a generated controller/view pair → the database/config layer.

First use case: an internal admin/back-office CRUD screen against one table, built entirely with the generator and then lightly customized. It is the workload this package is shaped for, it is cheap to throw away, and it exercises routing, views, DB access, and the CLI in a single pass.

Implementation Patterns

Greenfield-or-nothing. Let CrazyPHP scaffold the project root. The pattern that fails is bolting it beside a hand-written Laravel skeleton: duplicated service providers, competing autoload maps, two conventions for the same job. If you cannot start greenfield, use the generator only as a build-time tool (see below) and keep the runtime dependency out.

Draw the generated/hand-written boundary on day one. Write it down in the repo: which paths are generator output, which are yours. The durable pattern is:

• Generated files are treated as read-only artifacts.
• Customization happens in a subclass, a separate file, or a clearly marked block — never by editing the generated file in place.
• Regeneration is a scripted command, so a template change upstream produces a reviewable diff instead of a merge war.

Vertical-slice workflow. Generate entity → inspect the produced migration/model → adjust the schema by hand in the migration (not the model) → generate the controller → move business logic out of the controller into a plain PHP class → wire the view. Keeping domain logic in framework-free classes is the single cheapest insurance policy against this package stalling at 0.x.

Build-time adoption (lowest-exposure pattern). Run the generators once in a scratch checkout, commit the output as ordinary source, and remove the package from require. You keep the conventions and the scaffold, you drop the upgrade burden, and future maintenance is normal PHP. Worth doing for any project where the CLI's value is front-loaded.

CLI in CI. If you keep the package as a dev dependency, pin it in CI as well as in composer.json, install with --no-dev in the runtime image, and run the generator non-interactively only in scaffolding jobs — never as part of a deploy that could silently rewrite source.

Integration seams. Wrap the framework's request/response and DB access in thin adapters at the edges (a repository per table, a single place that reads config). When the package's API moves, you patch one file. When you migrate off, the adapters are the only rewrite.

Testing. Prefer HTTP-level tests against routes over unit-testing generated controllers. The routes → controller → view path is the contract you actually depend on, and it is the part most likely to shift between 0.x minors.

Gotchas and Tips

The changelog is a link. v0.10.0 ships only v0.9.0...v0.10.0 — no breaking-change callouts. When you upgrade, git diff v0.9.0 v0.10.0 in a local clone is the changelog. Schedule this as a ritual before every bump; it is the entire cost of the dependency and you should price it in up front.

Composer will betray you. ^0.10 admits 0.11, 0.12, … with breaking changes allowed by SemVer's 0.x rules. Pin "kekefreedog/crazyphp": "0.10.0" and commit composer.lock. Audit transitive drift with composer why and composer audit at each bump.

Namespace and autoload surprises after generation. New classes from the CLI may not be picked up until you regenerate the autoloader. If a freshly generated controller 404s or a class isn't found, run composer dump-autoload before you start debugging routing — it is the most common false alarm with generator-based frameworks.

Stale caches masquerade as bugs. If route or view caches exist, a new route silently won't resolve and an edited template won't re-render. Clear caches after every generation or config edit. Verify the web server rewrite rules too — a 404 on a route that --help-listed correctly is usually a rewrite/cache problem, not a code problem.

Config quirks. Config lives in dedicated files, typically environment-keyed. Don't scatter env()-style reads through controllers; funnel everything through the config layer so you have one place to change when the package's config schema shifts. Debug mode belongs in local config only — check it is off before anything reaches a shared environment.

Don't hand-edit generated files. This is the failure mode that quietly kills the project: someone patches a generated controller, the next regeneration overwrites it, and the fix is re-applied by hand forever. Enforce the boundary in code review.

Laravel muscle memory is a liability. Directory names, base classes, and helper conventions deliberately differ from Laravel. Strong Laravel developers will "fix" things that aren't broken and burn a day. Budget explicit ramp-up and write an internal one-pager: where routes go, where views go, how to add a controller.

Extension points worth knowing. The template set used by the generator is your highest-leverage customization — edit templates rather than post-processing generated output. The config layer and the console command registry are the other two places the framework expects you to work. Anything else is a fork.

Vendor or mirror it. Single maintainer, no security-disclosure process documented, one star. If this reaches anything you care about, mirror the repo internally and name an owner who is willing to read and patch the source. Abandonment then costs a maintenance ticket, not an outage.

Know what you'd lose. The generated output is portable PHP; the coupling is in base classes, config conventions, and template expectations. If you cannot state in one sentence which of those your app depends on, you don't yet have an exit plan — and at 0.10.0 with an unsummarized release, you need one.