Blacksmith Laravel Package

Technical Evaluation

• Architecture fit: Blacksmith is a build-time scaffolder, not a runtime library. It consumes a schema definition (models, fields, relationships) and emits migrations, Eloquent models, controllers, routes, factories, and optionally PHPUnit tests. The artifact reaching production is generated source code we review and commit — the package itself never sits in the request path. That keeps blast radius small and makes the adopt/borrow/reject decision reversible, which is the single most important architectural fact for planning.
• Where the value actually lives: the schema grammar and the publishable stubs/ directory. Everything else is plumbing. Any investment we make should target those two surfaces, whether we adopt the package or not.
• Integration feasibility: mechanically trivial on a compatible stack — composer require --dev, vendor:publish for config and stubs, and a confirmed Artisan command name. The gating step is composer why-not mpociot/blacksmith against the target app. On PHP 8+ / Laravel 8+ expect a hard stop; there is no maintenance path to resolve those constraints.
• Technical risk (ranked):
  1. Abandonment. Last release November 2016. No upstream, no security path, no compatibility work.
  2. Metadata mismatch. Package metadata calls this "the unofficial Laravel Forge API"; the repository and docs describe a schema-to-CRUD scaffolder. Two different products with different risk profiles. The code and majority of evidence indicate the scaffolder, but this must be confirmed before any roadmap item cites "Blacksmith." Stale metadata is itself a trust signal.
  3. Silent correctness drift. A misdeclared relationship yields a plausible belongsTo with the wrong foreign key — it compiles, it runs, and it surfaces weeks later. Relationship declarations require explicit migration-and-model review, not a skim.
  4. Destructive regeneration. No three-way merge. Re-running overwrites hand edits.
  5. Dependency-lock drag. Even dev-only, an old framework constraint can block composer update across the app long after the motivating feature is gone.
  6. Zero ecosystem. 103 stars, 0 dependents, no issue activity, no vendor, no searchable corpus. Every edge case is ours alone.
• Key questions to answer before any commitment:
  • Which artifact are we evaluating — the scaffolder or a Forge API client? (Correct the metadata record first.)
  • Is the target stack legacy Laravel 5.x, or are we modern? If modern, this is a read-only reference.
  • Who is the named PHP/Laravel owner who would fork, patch, and eventually retire it?
  • What is the stated exit criterion — "working internal admin CRUD in an afternoon," or "validated reference for an internal generator"? If neither, this is the wrong tool.
  • Is the actual goal schema-first development, or boilerplate reduction? They have different buy/build answers.

Integration Approach

• Stack fit: genuinely viable only in a legacy Laravel 5.x / pre-PHP 8 codebase already pinned to that era. On a modern stack it fits as a reference implementation: read the schema parser, the Artisan command class, and the stubs, and use them to shape a generator we own. That path costs nothing and carries no ongoing obligation.
• Three viable paths, in order of preference:
  1. Borrow the design (recommended). Read the schema grammar and stubs, then write a small internal Artisan command (make:resource-style) with our own templates. Roughly a few days of engineering; gives us conventions control and an upgrade path the package does not have.
  2. Fork and own. Only if a legacy app makes reimplementation uneconomic and a named owner accepts indefinite maintenance. Treat every patch as ours forever.
  3. Adopt as-is. Defensible only for throwaway demos, spikes, and internal admin tooling on a legacy stack, with rewrite expected.
• Compatibility checklist (run before planning anything):
  • composer show mpociot/blacksmith and open vendor/mpociot/blacksmith/ to confirm what was actually installed.
  • composer why-not mpociot/blacksmith against the target app's PHP and Laravel versions.
  • Expect 2016-era conventions in generated output: no typed properties, no constructor promotion, older Blade syntax, controller-level validation rather than FormRequests, pre-class factories, Route::resource-era routing. Generated code that compiles but violates our conventions is a maintenance cost we are choosing.
• Sequencing for a spike:
  1. Confirm the artifact identity and correct the internal package record.
  2. Install as a dev dependency in a sandbox app, never the app we care about. Never wire into CI or a Composer post-install script.
  3. Publish config and stubs; capture the real command name (php artisan list | grep blacksmith).
  4. Model one resource end to end (Post with title, body, published_at, user_id → belongsTo User) and diff the output against a hand-written equivalent. That diff answers "usable verbatim?" better than any README: migration style, $fillable vs $guarded, relationships, casts, validation placement, route registration, Blade scaffolding.
  5. Review generated files line by line. We own them on commit.
  6. Decide: reference, fork, or discard — and record the exit criterion that drove it.
• Generation discipline: generate in dependency order (parents before children, or migrations reference nonexistent tables); one resource at a time so review stays honest; customize the stubs once and commit them rather than patching output file by file; generate into a scratch directory when re-running and diff by hand.
• Keep it out of the lockfile of any application we intend to upgrade, regardless of which path we take.

Operational Impact

• Maintenance: functionally zero upstream maintenance, which means 100% of the maintenance is ours the moment we patch anything. The durable, low-cost asset is the stub design — team-wide consistency in model style, migration naming, controller structure, and validation placement survives even if the package is rejected. Budget the real investment as "a small internal generator or a maintained alternative" (a few days), not as "adopt Blacksmith."
• Support: no vendor, no SLA, no community. No issue activity, no Stack Overflow corpus, no third party hitting the same edge cases. Debugging is source-reading: run the command with -v to see what it writes where, check published config for output-path overrides before assuming files vanished, and inspect the schema parser's type map (not the stub) when a field type is silently ignored.
• Scaling: poor for org-wide use and fine for individuals. Multiple developers generating from drifting stubs produces inconsistent code — which is the opposite of the standardization goal that usually motivates this evaluation. Review cost scales linearly with schema size and is the real bottleneck; small batches keep it honest and make a bad generation cheap to discard. Generated PHPUnit tests are endpoint scaffolding (status codes, happy paths), not coverage — they will pass while validation is wrong.
• Failure modes to plan for:
  • Destructive regeneration silently overwriting hand-edited files.
  • Silent correctness drift in relationships and foreign keys, discovered late.
  • Composer constraint lock blocking framework upgrades long after adoption.
  • Metadata mislabeling causing a decision to be logged against the wrong product.
  • Generated tests creating false confidence in coverage.
  • A fork accumulating unowned patches.
• Ramp-up: low to install and run (~an hour in a sandbox); moderate to understand the schema grammar and type map well enough to trust output; high to own long-term. Timebox any spike explicitly, isolate to local dev, and require line-by-line review before merge — generation accelerates the first draft, never the review.
• Recommendation for stakeholders: endorse the concept — schema-driven scaffolding measurably speeds the earliest phase of a Laravel build (MVPs, internal admin tools, demos) — and decline the artifact as a foundation. Fund a small internal generator with stubs we control, use Blacksmith as a free design reference, and correct the package metadata before anyone cites it in a roadmap.