Laravel Craftsman Laravel Package

Getting Started

Laravel Craftsman is a scaffolding CLI that predates (and in several ways inspired) Laravel’s native make:* ergonomics. It installs as a dev dependency and registers an Artisan namespace of craft:* commands alongside Laravel’s own.

composer require --dev codedungeon/laravel-craftsman

Publish its config if you plan to customize output:

php artisan vendor:publish --provider="Codedungeon\LaravelCraftsman\CraftsmanServiceProvider"

Where to look first: run php artisan list craft to see the full command surface on your Laravel version. Then read config/craftsman.php — it’s where stub (template) paths, default namespaces, and output locations live. Any behavior you want to change is almost always there or in a custom template, not in code.

First use case: replace a multi-step make: sequence with one command. Instead of:

php artisan make:model Post -mfs
php artisan make:controller PostController --resource
php artisan make:request StorePostRequest
php artisan make:resource PostResource
php artisan make:test PostTest

you run a single craft:model (or craft:controller) invocation with the associated flags, and get a coherent set of files in one pass. The first-week value is consistency of file sets — the model, migration, factory, seeder, controller, request, resource, and test all arrive with matching names and the same template conventions.

If you’re on Pest: craft:test supports a --pest flag (added in 1.10.1) that emits Pest-formatted tests instead of PHPUnit classes:

php artisan craft:test PostTest --pest
php artisan craft:test PostTest --pest --unit

Make sure Pest is actually installed in the project before relying on this — Craftsman only writes the file, it won’t add the dependency or tests/Pest.php.

Implementation Patterns

1. Scaffold-a-resource in one command. The most common day-to-day pattern is generating the whole vertical slice for a new entity:

php artisan craft:model Post --migration --factory --seeder --controller --request --resource --test

Use this at the start of a feature branch — before writing a line of logic — so the boilerplate is uniform across the team.

2. Batch sibling generation via shell wrappers. Because Craftsman commands compose cleanly, teams wrap them in a bin/new-resource script or a Makefile target:

#!/usr/bin/env bash
php artisan craft:model "$1" --migration --factory --seeder
php artisan craft:controller "${1}Controller" --resource
php artisan craft:request "Store${1}Request"
php artisan craft:request "Update${1}Request"
php artisan craft:resource "${1}Resource"
php artisan craft:test "${1}Test" --pest

This is where Craftsman earns its keep over native make: — the wrapper becomes the team’s vocabulary, and the test style (--pest vs. PHPUnit) is encoded once instead of remembered per developer.

3. Custom templates for house style. Publish the config, then point Craftsman’s template directory at your own folder. Every generated class then inherits your team’s traits, declare(strict_types=1), base controller, docblocks, or DTO conventions automatically. This is the single highest-leverage customization — it turns scaffolding from “Laravel default” to “our default.” Note the templates are Mustache files (e.g. templates/model.mustache), not plain PHP stubs — see Gotchas.

4. Wire into routes and tests at generation time. Generating a controller and its test skeleton in the same invocation means feature tests get started before the controller is finished, which nudges the team toward test-first even if they don’t formally adopt TDD. Pairing craft:test --pest with craft:controller keeps the test file idiomatic for whichever framework the repo uses.

5. Integration with CI/schema tooling. Since generated migrations follow Craftsman’s naming convention, php artisan migrate and migrate:fresh --seed in CI behave predictably. Keep Craftsman generation out of CI — it’s a developer-time tool; CI should only consume what’s committed.

6. Pair with native make: for anything Craftsman doesn’t cover. Craftsman is not a replacement for make:model -a on Laravel 9/10; use both. The pattern that works: Craftsman for multi-file cohorts (model + factory + seeder + request + resource in one go), native make: for single files.

Gotchas and Tips

• Unmaintained since 2020. The current release is 1.10.1 (2020-07-03) — the last one ever published — and there are essentially zero dependents in the wild. Treat it as a legacy-project tool. On Laravel 10/11 the service provider may not auto-register cleanly and template syntax will be out of date (e.g. attribute-based casts, new test stubs, Route::controller() changes). Test on a scratch branch before adopting. If you’re on Laravel 10+, native php artisan make:model Post -mfsc --requests --resources --tests covers most of what Craftsman historically did.

• Templates are Mustache, not PHP. The stub files Craftsman renders are .mustache (e.g. templates/model.mustache). If you copy a native stub:publish stub in and expect it to work, it won’t — Mustache placeholders and sections are a different syntax. When overriding, start from Craftsman’s own published templates and edit those.

• $table bug — check generated models on anything below 1.10.1. Prior versions emitted protected $tablename = "users"; instead of protected $table = "users"; in the model template, which silently breaks any model that relies on Eloquent’s $table guessing or a non-conventional table. 1.10.1 fixes the typo. If your app predates this release, grep generated models for $tablename and fix them — the broken property fails silently, not loudly. The companion fix makes craft:migration --tablename use the flag correctly when deriving the CreateXXXTable class name, so verify the class name and the filename when using that flag on older versions.

• Config path resolution is picky. Craftsman resolves template files relative to the published config. If you run it from a subdirectory, or use a monorepo with non-standard app/ placement, template lookups silently fall through to defaults. Verify with a dry run: generate one file to a temp name and inspect its contents for your custom markers before trusting it across the team.

• Migration ordering. Generated migrations use timestamp-based names, but if you generate several in one shell script they can land in the same second and lose ordering fidelity. Insert a sleep 1 between generations in wrapper scripts, or generate migrations separately from other artifacts.

• --force overwrites silently. There is no interactive confirmation on overwrite in most versions. Never put --force in a shared wrapper script. If you do, git is your only safety net — commit before running any bulk generation.

• Namespacing pitfalls with subdirectories. Generating craft:model Admin/User usually works, but the corresponding factory/request/test paths may not mirror the subdirectory the way make: does. Verify the entire cohort lands correctly, not just the primary file.

• --pest caveats. The flag only changes the emitted file’s formatting; it doesn’t install Pest, register tests/Pest.php, or update phpunit.xml. It also landed when Pest was still pre-1.0, so the generated skeleton reflects that era’s API — expect to adjust uses()/test() scaffolding by hand for modern Pest versions.

• Debugging generation failures. When a command fails mid-cohort, you often get a partial output set with no rollback. Run with -v to see the actual template resolution path; that’s the fastest way to spot a config/template mismatch.

• Extension points to lean on:

  • Template overrides — replace any .mustache file under the template directory via config.
  • Shell wrapper scripts — the cleanest way to encode team conventions (including --pest) without touching the package.
  • A custom app/Console/Commands/* that calls Craftsman commands — useful if you want a single make:feature entry point with your own validation and post-processing (e.g., auto-registering routes or updating a menu config).

• The migration-to-Craftsman decision. If your project isn’t already on it, don’t introduce it. The value proposition (batch generation + custom templates) is now largely covered by native make:model flags and stub:publish. 1.10.1 adds nothing that changes this calculus — a Pest variant of craft:test is nice, but php artisan make:test FooTest --pest does the same thing natively on modern Pest installs. The only strong reason to adopt in 2024+ is an existing codebase with Craftsman templates and wrapper scripts already baked into the workflow.