Laravel Stub Generator Laravel Package

Getting Started

1. Install the package

   composer require touhidurabir/laravel-stub-generator
   

   The service provider should be auto-discovered on Laravel 5.5+. If not, register Touhidurabir\StubGenerator\StubGeneratorServiceProvider manually in config/app.php.

2. Publish config and stubs

   php artisan vendor:publish --provider="Touhidurabir\StubGenerator\StubGeneratorServiceProvider"
   

   If that publishes everything, re-run with --tag= to separate the config from the stub files. Confirm the available tags with php artisan vendor:publish --list (or by reading the provider's publishes() array).

3. Look here first

   • config/stub-generator.php — stub locations, target paths, namespace mappings, and any placeholder configuration.
   • The published stubs/ directory — one stub per artifact type (service.stub, repository.stub, trait.stub, etc.).
   • php artisan list | grep -i stub — the actual command signature is the fastest way to learn the package's public API.

4. First use case: scaffold an app service Create stubs/service.stub with placeholders such as {{ namespace }}, {{ class }}, and {{ extends }}, point the config at it, then generate:

   php artisan stub:generate service UserService
   

   The generated file should land in app/Services/UserService.php with the correct namespace. Once that round-trip works, you have validated path resolution, placeholder replacement, and namespace derivation in one shot — the three things that typically break.

Implementation Patterns

• Config-driven template registry. Treat the config as a map of artifact type → stub file + destination namespace. Adding a new artifact type (e.g. action, dto, policy) should mean adding a stub and a config entry, not writing code.
• Wrap the generator in domain-specific commands. Rather than exposing the raw API to your team, create thin Artisan commands (make:service, make:action, make:repository) that validate the name, call the generator, and optionally register the class in a service provider. This keeps the package as an implementation detail you can swap out.
• Programmatic use inside generators. Call the generator from your own command's handle():

  $generator->from('stubs/service.stub')
      ->to(app_path('Services'))
      ->with(['namespace' => 'App\\Services', 'class' => $name])
      ->generate();
  

  Exact method names vary by version — read the source of the facade/class once and pin your wrapper around it so upgrades are contained.
• Layered stubs for team conventions. Keep package defaults untouched and publish project-specific overrides into stubs/. On upgrade, diff the package's default stubs against your overrides to catch renamed placeholders.
• Compose with framework make:* commands. A common pattern is to have your custom command call Artisan::call('make:model', ...) first, then run the stub generator for the service/repository layer, giving you a single "feature scaffold" command.
• Test the output, not the package. In CI, run your generator command into a temp directory and assert on the generated file contents:

  $this->artisan('make:service', ['name' => 'Foo']);
  $this->assertFileContains('app/Services/FooService.php', 'class FooService');
  

  This catches broken stubs and placeholder regressions without testing third-party internals.
• Idempotency in scaffolding workflows. If your command is part of a larger setup script, guard with File::exists() or expose a --force flag so repeated runs don't silently overwrite hand-edited code.

Gotchas and Tips

• Placeholder syntax collisions. If stubs use {{ }} and you also run them through Blade or any templating layer, the two will fight. Verify whether the package replaces placeholders itself or compiles the stub; escape or change delimiters if needed.
• Exact placeholder spelling matters. {{class}} vs {{ class }} or {{ ClassName }} will silently leave the literal token in the output. Grep generated files for {{ in a post-generation test.
• Namespace ↔ path mismatch. The most common failure is a file at app/Services/X.php declaring namespace App\Service. Derive namespace from the configured PSR-4 root, not from a hardcoded string, and confirm composer.json maps the target directory.
• Overwrite semantics. Check whether the generator overwrites, skips, or fails on existing files before letting it into a scaffold script. Assume it overwrites until proven otherwise.
• Config caching. After changing stub paths or namespace mappings, run php artisan config:clear. In production-style environments with cached config, new stub entries appear to be ignored.
• Directory creation. The target directory may need to exist first, or the package may create it — test both on a clean checkout. On case-sensitive filesystems (Linux CI vs macOS local), class-name casing bugs surface only after deploy.
• Windows paths. Backslashes in stub paths plus namespace separators are a frequent source of doubled escapes. Prefer base_path()/app_path() over string concatenation.
• Path traversal input. If the artifact name flows straight into a path, validate it (^[A-Z][A-Za-z0-9]*$ or similar) to prevent ../ escaping the target directory.
• Extension points. Before forking, check for: a bindable generator contract in the container, a Generator/Stub facade, events fired around generation, and config keys for custom placeholder replacers. These are the cleanest hooks for project-specific behavior.
• Maintenance risk. This is a small (~54-star) package with no confirmed upstream repository and a release date that should be verified on Packagist. Pin an exact version in composer.json, keep your own thin wrapper around it, and be prepared to replace it with a ~50-line internal generator if it goes unmaintained — the core feature (read stub, replace tokens, write file) is not large.