Package Generator Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require purwantoid/package-generator
   

   Publish the default stubs (optional but recommended for customization):

   php artisan vendor:publish --provider="Purwantoid\PackageGenerator\PackageGeneratorServiceProvider" --tag="stubs"
   

2. First Use Case: Generate a basic package structure:

   php artisan make:package YourVendor YourPackage
   

   This creates a folder YourPackage with:

   • src/ (main PHP classes)
   • config/ (config files)
   • tests/ (empty by default)
   • composer.json
   • README.md

3. Where to Look First:

   • Stub Files: Check resources/stubs/ (or published location) for template customization.
   • Artisan Command: Inspect app/Console/Kernel.php for registered commands.
   • Service Provider: Review Purwantoid\PackageGenerator\PackageGeneratorServiceProvider for core logic.

Implementation Patterns

Core Workflows

1. Standard Package Generation:

   php artisan make:package vendor/package-name --with-tests
   

   • Automatically generates:
     • src/ServiceProvider.php
     • src/PackageNameServiceProvider.php
     • config/package.php
     • tests/Feature/ (if --with-tests)

2. Custom Stub Integration:

   • Override stubs in resources/stubs/ (e.g., php/main-class.stub).
   • Use template variables like {{PACKAGE_NAME_STUDLY}} for dynamic content.
   • Example customization for main-class.stub:

     <?php
     
     namespace {{VENDOR_NAME}}\{{PACKAGE_NAME_STUDLY}}\;
     
     class {{PACKAGE_NAME_STUDLY}} extends \Illuminate\Support\ServiceProvider
     {
         public function register()
         {
             $this->mergeConfigFrom(
                 __DIR__.'/../../config/{{PACKAGE_NAME_KEBAB}}.php', 'package'
             );
         }
     }
     

3. Conditional Logic:

   • Use {{#if}} and {{/if}} in stubs for optional files (e.g., tests):

     {{#if with_tests}}
     tests/Feature/ExampleTest.php
     {{/if}}
     

4. Post-Generation Hooks:

   • Extend Purwantoid\PackageGenerator\Commands\MakePackageCommand to add custom logic:

     protected function postGenerate(string $packagePath): void
     {
         // Add custom files or run migrations
     }
     

5. Template Validation:

   • Run php artisan package:validate-stubs to check for syntax errors in stubs.

Gotchas and Tips

Pitfalls

1. Stub Path Conflicts:

   • If stubs are published to a non-standard location, update the stubs_path config in config/package-generator.php.
   • Fix: Ensure stubs/ exists in the published location before generation.

2. Variable Name Mismatches:

   • Typos in {{VARIABLE_NAME}} (e.g., {{PACKAGE_NAME}} vs. {{package_name}}) will cause silent failures.
   • Debug: Use php artisan package:validate-stubs to catch errors early.

3. Composer Autoloading:

   • Generated composer.json may not auto-discover namespaces if src/ is misconfigured.
   • Tip: Verify autoload.psr-4 includes:

     "autoload": {
         "psr-4": {
             "{{VENDOR_NAME}}\\{{PACKAGE_NAME_STUDLY}}\\": "src/"
         }
     }
     

4. Test File Generation:

   • The --with-tests flag only creates the tests/ directory structure; you must manually implement test classes.
   • Workaround: Extend the example-test.stub to include boilerplate test code.

5. Namespace Collisions:

   • Avoid using reserved Laravel namespaces (e.g., Illuminate) in package stubs.
   • Tip: Use {{VENDOR_NAME}} as a prefix in all generated namespaces.

Debugging Tips

1. Dry Run:

   • Set debug=true in config/package-generator.php to log generated file paths and content.

2. Stub Overrides:

   • To test custom stubs without republishing:

     php artisan package:generate --stubs=/path/to/custom/stubs
     

3. Command Options:

   • Use --no-interaction for CI/CD pipelines:

     php artisan make:package vendor/package --no-interaction --with-tests
     

Extension Points

1. Custom Commands:

   • Register additional commands in PackageGeneratorServiceProvider:

     $this->commands([
         \Purwantoid\PackageGenerator\Commands\MakePackageCommand::class,
         \App\Commands\CustomPackageCommand::class,
     ]);
     

2. Dynamic Stub Loading:

   • Load stubs from a remote source (e.g., GitHub) by extending Purwantoid\PackageGenerator\StubLoader.

3. Post-Processing:

   • Use Laravel’s post-update-cmd in the generated composer.json to run scripts after installation:

     "scripts": {
         "post-update-cmd": [
             "@php artisan package:post-install"
         ]
     }
     

4. Template Inheritance:

   • Combine stubs using {{include 'partials/header.stub'}} for reusable components (e.g., license headers).

Config Quirks

• Default Values:
  • The package assumes stubs are in resources/stubs/. Override with:

    'stubs_path' => base_path('custom/stubs'),
    

• Case Sensitivity:
  • Template variables are case-sensitive ({{PACKAGE_NAME}} ≠ {{package_name}}).