Workbench Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require larastarscn/workbench
   

   Add to config/app.php:

   'providers' => [
       Larastarscn\Workbench\WorkbenchServiceProvider::class,
   ],
   

   Register the command in app/Console/Kernel.php:

   protected $commands = [
       \Larastarscn\Workbench\Console\WorkbenchMakeCommand::class,
   ];
   

2. Publish Config

   php artisan vendor:publish --provider="Larastarscn\Workbench\WorkbenchServiceProvider"
   

   Update config/workbench.php with your author details (e.g., name, email, github).

3. First Use Case Generate a basic package structure:

   php artisan workbench vendor/package-name
   

   Example:

   php artisan workbench larastarscn/test-package
   

Implementation Patterns

Workflows

1. Package Scaffolding

   • Run php artisan workbench vendor/package to generate:
     • Standard Laravel package structure (src/, config/, tests/, etc.).
     • Placeholder files (e.g., ServiceProvider, Facade, Config, README.md).
   • Customize via config/workbench.php (e.g., disable certain files like tests/).

2. Integration with Package Development

   • Use the generated composer.json as a template for your package.
   • Leverage the src/ directory for core logic (e.g., classes, traits, interfaces).
   • Publish config files for end-users:

     php artisan vendor:publish --tag="config"
     

3. Extending Templates

   • Override default templates by publishing and modifying:

     php artisan vendor:publish --tag="workbench-templates"
     

   • Place custom templates in resources/views/vendor/workbench/ (e.g., config.stub, readme.stub).

4. Automating Releases

   • Use the generated README.md and CHANGELOG.md stubs as starting points.
   • Hook into post-create scripts in composer.json to run tests or linting:

     "scripts": {
         "post-create-package": [
             "@php artisan test",
             "@php artisan lint"
         ]
     }
     

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • Forgetting to publish config/workbench.php will default to empty author fields, causing warnings in generated files.
   • Fix: Always run php artisan vendor:publish after installation.

2. Namespace Conflicts

   • If your package name conflicts with an existing Composer package, the generator may fail.
   • Fix: Use a unique vendor/package format (e.g., yourcompany/unique-package).

3. Template Path Issues

   • Custom templates in resources/views/vendor/workbench/ must match the stub names exactly (e.g., config.stub).
   • Fix: Verify stub filenames in config/workbench.php under templates.

4. Permission Errors

   • Running php artisan workbench in a directory without write permissions will fail.
   • Fix: Use sudo or ensure proper permissions for the target directory.

Debugging

• Dry Run Mode Use --dry-run to preview changes without writing files:

  php artisan workbench vendor/package --dry-run
  

• Verbose Output Enable debug mode for detailed logs:

  php artisan workbench vendor/package --verbose
  

Extension Points

1. Custom Commands Extend the WorkbenchMakeCommand to add pre/post-creation hooks:

   // app/Console/Commands/CustomWorkbenchCommand.php
   use Larastarscn\Workbench\Console\WorkbenchMakeCommand;
   
   class CustomWorkbenchCommand extends WorkbenchMakeCommand {
       protected function getStubContents() {
           // Modify stubs or add logic here
       }
   }
   

2. Dynamic Templates Use Laravel’s blade syntax in stubs to inject dynamic data:

   // resources/views/vendor/workbench/config.stub
   <?php echo '<?php'; ?>
   return [
       'author' => '@authorName',
       'version' => '@packageVersion',
   ];
   

3. Post-Creation Scripts Add scripts to composer.json to automate post-generation tasks:

   "scripts": {
       "post-create-package": [
           "php artisan workbench:post-create vendor/package"
       ]
   }
   

Tips

• Template Organization Group related stubs (e.g., src/, tests/) in subdirectories within resources/views/vendor/workbench/ for clarity.

• CI/CD Integration Use Workbench in CI pipelines to scaffold packages before running tests:

  # .github/workflows/package-ci.yml
  steps:
    - run: php artisan workbench vendor/package
    - run: composer test
  

• Git Ignore Add generated files to .gitignore if they’re not part of the package’s public API:

  /vendor
  /node_modules
  /tests/