Dev Tool Laravel Package

Getting Started

juzaweb/dev-tool is a dev-only Artisan toolkit for Juzaweb projects. It is not a general-purpose Laravel package: if you are not on Juzaweb CMS (or building modules/packages that follow its conventions), most of what ships here is irrelevant to you. For a Juzaweb developer, though, it removes a meaningful amount of repeated scaffolding work.

Minimal setup:

composer require --dev juzaweb/dev-tool
php artisan vendor:publish --tag=dev-tool-config   # only if you need to override stub paths / output namespaces
php artisan list | grep -i dev

That php artisan list step matters more than usual because the package registers a mix of generator commands (make:page-block, module/package scaffolders, publish-agents), maintenance commands (dump), asset helpers (DownloadStyleCommand) and a GitHub release command (GithubReleaseModuleCommand). You want to see exactly what got registered in your app, because command-name collisions with framework make:* and dump are a real risk in a CMS codebase that already stacks packages.

Where to look first:

1. The published config — stub paths, output namespaces, download targets. Almost every "the generator produced something wrong" bug traces back here.
2. The stubs/ directory — generators are only as good as their stubs. Note that 2.0.5 specifically fixed .stub files being mangled by Pint, so if you published stubs from 2.0.4, re-publish.
3. php artisan help make:page-block — read the signature before wrapping it or guessing flags.

First use case: scaffold one page block in a real module, inspect the generated files, and diff them against what you would have written by hand. That diff tells you whether to customise the stub, wrap the command, or ignore the tool for that task. Doing this once is far more informative than reading the README.

Implementation Patterns

Customise stubs, don't fork commands. Publish stubs into your app and edit them. Generators read stubs at runtime, so you keep the upstream command logic (and its test coverage) while controlling the output shape. Fork a command only when you genuinely need different arguments or a different file set — otherwise you inherit maintenance for every patch release.

Wrap generators in app-level task commands. In a team, a thin php artisan app:make-block {name} that calls the package command with your defaults (namespace, path, registration, stub) means developers don't memorise flags, and package upgrades stay invisible. This is the single highest-leverage pattern here: the package becomes an implementation detail of your tooling.

Treat DownloadStyleCommand as a build step, not an ad hoc command. PR #23 added file-content caching, so repeat runs are cheap — which is exactly why you should call it from composer run setup or a provisioning script rather than by hand. Cache behaviour is deterministic when it runs the same way every time.

Pair generators with a CI style gate. 2.0.5 added a Pint check to the package's own workflow and fixed .stub formatting by Pint. Mirror that in your pipeline: run pint --test on application code, and keep .stub files excluded from normal Pint formatting (placeholder syntax in stubs is not valid PHP and will be reformatted destructively).

Keep release automation in CI only. GithubReleaseModuleCommand belongs in a tag-push workflow with a repo-scoped token. Never wire it to a local habit — one stray invocation publishes from a laptop.

Generator-then-review, never generator-then-commit. Scaffolded output is a starting point. The value is in the review diff, not the scaffolding itself; a block generator that saves five minutes but ships unreviewed registration code is a net loss.

Gotchas and Tips

• Strictly require-dev. If any service provider or command boot leaks into production, gate registration behind $this->app->environment('local', 'testing'). A dev tool registering dump in production is both a security smell and a footgun.
• Command shadowing. dump and generic make:* names can collide with the framework or other packages. Run php artisan list after install and after every upgrade; if a command behaves differently than the package docs suggest, check whether something else won the name.
• Stubs and Pint are the recurring upgrade hazard. 2.0.5 fixed stubs being reformatted, but if your project pins its own Pint config or published stubs earlier, verify a freshly generated file against a known-good one after upgrading. This is the most likely place a "safe patch" bites you.
• Download cache can cache failure. A partial or failed first download is now cached, so weird CSS output is a cache problem more often than a network problem. Clear the cache directory before debugging the HTTP layer.
• 2.0.5 is internal-only. Tests added across DumpCommand, FileGenerator, PublishAgentsCommand, GithubReleaseModuleCommand, MakePageBlockCommand::handle() simplified, caching in DownloadStyleCommand, Pint in CI. Signatures and options unchanged — safe patch bump. Re-read those classes only if you subclassed or monkey-patched them.
• Debugging a bad generator run, in order: resolved stub path first (most common cause), then the placeholder values handed to FileGenerator::generate, then the config. The 2.0.5 tests are a good reference for expected input/output shapes if you need to reason about the generator directly.
• Prefer extension points over overrides. Config values, published stubs, and your own wrapper commands are stable across releases. Subclassing package classes is brittle when the package ships frequent small refactors — and it ships them often.
• Pin ^2.0 and let patches through. Low-risk release cadence, no migration burden, but always sanity-check one generated file after the bump given the .stub/Pint history.
• Assess fit honestly. One star and a single maintainer means the bus factor is the maintainer's release schedule. If your workflow depends heavily on these commands, your wrapper layer is also your insurance policy.