Zapcraft Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Run:

   composer require holdmyglass/zapcraft
   

   The package auto-installs nwidart/laravel-modules if missing.

2. Publish Config & Assets Publish the package config and stubs:

   php artisan vendor:publish --provider="HoldMyGlass\ZapCraft\ZapCraftServiceProvider"
   

3. Configure Modules Edit config/zapcraft.php to define your module structure (e.g., modules/ path, namespace prefixes).

4. Generate First Entity Run the zapcraft:make command with a basic entity name:

   php artisan zapcraft:make Post
   

   This creates:

   • Model (app/Modules/Post/Entities/Post.php)
   • Migration (database/migrations/xxxx_create_posts_table.php)
   • Controller (app/Modules/Post/Http/Controllers/PostController.php)
   • Repository interface/implementation (app/Modules/Post/Repositories/PostRepositoryInterface.php, PostRepository.php)
   • DTO (app/Modules/Post/Dtos/PostDto.php)
   • Request/Resource (app/Modules/Post/Http/Requests/StorePostRequest.php, PostResource.php)
   • Routes (routes/web.php or routes/api.php stubs)

5. Register Module Add the module to config/modules.php:

   'Post' => \Modules\Post\PostServiceProvider::class,
   

   Then publish the module:

   php artisan module:publish Post
   

Implementation Patterns

Core Workflows

1. Standard Entity Creation

Use zapcraft:make for full-stack entity scaffolding:

php artisan zapcraft:make User --api --with-tests

• --api: Generates API-specific resources (e.g., PostResource).
• --with-tests: Includes PHPUnit test stubs.

2. Modular Project Structure

Leverage nwidart/laravel-modules patterns:

• Namespace Isolation: Each module lives in app/Modules/{Entity}/.
• Service Providers: Register module bindings in PostServiceProvider:

  public function register()
  {
      $this->app->bind(
          \Modules\Post\Repositories\PostRepositoryInterface::class,
          \Modules\Post\Repositories\PostRepository::class
      );
  }
  

3. Customizing Generators

Extend default stubs by publishing and overriding:

php artisan vendor:publish --tag=zapcraft.stubs

Edit stubs in resources/views/vendor/zapcraft/stubs/.

4. Integration with Existing Code

• Repositories: Inject PostRepositoryInterface into controllers:

  public function __construct(PostRepositoryInterface $repository) {
      $this->repository = $repository;
  }
  

• DTOs: Use in requests or services:

  $dto = new PostDto($request->validated());
  $this->repository->create($dto);
  

• Resources: Transform responses:

  return PostResource::collection($this->repository->all());
  

5. API Routes

Generated routes are stubs. Customize in routes/api.php:

Route::apiResource('posts', \Modules\Post\Http\Controllers\PostController::class)
    ->middleware('auth:api');

6. Testing

Use --with-tests flag to generate test stubs:

php artisan zapcraft:make Comment --with-tests

Test files appear in tests/Module/Comment/.

Gotchas and Tips

Pitfalls

1. Module Autoloading

   • Issue: Classes not autoloaded if composer dump-autoload isn’t run after publishing.
   • Fix: Add modules/ to composer.json autoload:

     "autoload": {
         "psr-4": {
             "Modules\\": "app/Modules/"
         }
     }
     

     Then run:

     composer dump-autoload
     

2. Stub Overrides

   • Issue: Custom stubs may break if not placed in the correct directory (resources/views/vendor/zapcraft/stubs/).
   • Fix: Verify stub paths in config/zapcraft.php under stubs_path.

3. Route Conflicts

   • Issue: Generated routes may clash with existing ones.
   • Fix: Manually adjust routes/web.php or routes/api.php after generation.

4. Repository Binding

   • Issue: Forgetting to bind the repository interface in the module’s ServiceProvider.
   • Fix: Always register bindings in register():

     $this->app->bind(
         \Modules\Post\Repositories\PostRepositoryInterface::class,
         \Modules\Post\Repositories\PostRepository::class
     );
     

5. DTO Validation

   • Issue: DTOs may not validate input properly if not synced with the request.
   • Fix: Extend PostDto to include validation logic or use StorePostRequest for validation.

Debugging Tips

• Check Generated Files: Verify files are created in the correct module directory.
• Clear Config Cache: After publishing config, run:

  php artisan config:clear
  

• Log Commands: Enable debug mode in config/zapcraft.php to log generator output:

  'debug' => env('ZAPCRAFT_DEBUG', false),
  

Extension Points

1. Custom Commands Extend the generator by creating a custom command:

   php artisan make:command CustomZapcraftCommand
   

   Extend HoldMyGlass\ZapCraft\Console\MakeEntityCommand.

2. Additional File Types Add new file templates by:

   • Creating stubs in resources/views/vendor/zapcraft/stubs/custom/.
   • Updating config/zapcraft.php to include them in the generator.

3. Dynamic Naming Use --name or --singular flags to customize generated class names:

   php artisan zapcraft:make "Blog Post" --singular
   

4. Seeding Integrate with Laravel’s seeder by extending the generator to include a seeder stub:

   php artisan zapcraft:make Post --with-seeder
   

Performance

• Batch Generation: For multiple entities, consider scripting the zapcraft:make command.
• Exclude Files: Use --skip={migration,controller,...} to generate only needed files:

  php artisan zapcraft:make User --skip=migration