Laravel Package Maker Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev backtheweb/laravel-package-maker
   

   Ensure the package is registered in composer.json under require-dev.

2. Publish Assets (if needed):

   php artisan vendor:publish --provider="Backtheweb\PackageMaker\PackageMakerServiceProvider"
   

   (Optional: Customize default templates or configurations.)

3. First Use Case: Generate a basic Laravel package scaffold:

   php artisan package:make MyVendor/MyPackage
   

   This creates a new package directory (packages/MyVendor/MyPackage) with:

   • Standard Laravel package structure (src/, config/, routes/, etc.).
   • Pre-configured composer.json with Laravel autoloading.
   • Basic README.md and phpunit.xml.

4. Where to Look First:

   • Command Reference: Run php artisan package:make --help for all available options (e.g., --no-interaction, --config-path).
   • Templates: Default templates are in vendor/backtheweb/laravel-package-maker/src/Resources/stubs/. Override by publishing assets and modifying config/package-maker.php.

Implementation Patterns

Core Workflows

1. Package Generation:

   • Basic: php artisan package:make Vendor/Package (interactive prompts for namespace, description, etc.).
   • Non-Interactive:

     php artisan package:make Vendor/Package --namespace=App --author="John Doe" --no-interaction
     

   • Custom Path:

     php artisan package:make Vendor/Package --path=custom/packages/
     

2. Template Customization:

   • Publish the package’s stubs:

     php artisan vendor:publish --tag=package-maker.stubs
     

   • Modify stubs in resources/stubs/ (e.g., composer.json.stub, README.md.stub).
   • Extend with your own stubs by overriding the stubs config array in config/package-maker.php.

3. Integration with CI/CD:

   • Use the package in a monorepo or multi-package project:

     # Example: Generate all packages in a single command
     php artisan package:make Package1 --path=packages/
     php artisan package:make Package2 --path=packages/
     

   • Automate package generation in CI (e.g., GitHub Actions) for boilerplate consistency.

4. Post-Generation Hooks:

   • Use the --post-generate option to run custom scripts after package creation:

     php artisan package:make Vendor/Package --post-generate="php artisan vendor:publish --tag=package-config"
     

Advanced Patterns

1. Dynamic Package Configuration:

   • Pass environment variables or config values during generation:

     php artisan package:make Vendor/Package --config="database.default=mysql"
     

   • Access these in stubs via {{ config('database.default') }}.

2. Package Dependencies:

   • Auto-add dependencies to composer.json:

     php artisan package:make Vendor/Package --dependency="laravel/framework:^10.0"
     

   • Support dev dependencies with --dev-dependency.

3. Modular Packages:

   • Generate a modular package (e.g., with sub-packages) by chaining commands or using a custom script:

     php artisan package:make Vendor/Package --path=packages/
     cd packages/Vendor/Package && php artisan package:make SubPackage --path=src/SubPackages/
     

4. Testing Integration:

   • Include PHPUnit/Pest templates by enabling the --with-tests flag:

     php artisan package:make Vendor/Package --with-tests
     

   • Customize test templates via published stubs.

Gotchas and Tips

Pitfalls

1. Namespace Collisions:

   • Ensure the generated package’s namespace (Vendor\Package) doesn’t conflict with existing code.
   • Fix: Use unique vendor names (e.g., Company\Package instead of App\Package).

2. Composer Autoloading Issues:

   • If the package isn’t auto-discovered, manually add it to config/app.php under providers.
   • Debug: Run composer dump-autoload after generation.

3. Stub Overrides Not Applying:

   • If custom stubs aren’t used, verify the stubs path in config/package-maker.php is correct.
   • Fix: Clear published assets:

     rm -rf resources/stubs && php artisan vendor:publish --tag=package-maker.stubs
     

4. Permission Errors:

   • Writing to packages/ may fail if permissions are restrictive.
   • Fix: Use --path to point to a writable directory or adjust folder permissions:

     chmod -R 775 packages/
     

5. Laravel Version Mismatches:

   • The package assumes compatibility with the host Laravel app’s version.
   • Fix: Pin Laravel dependencies in the generated composer.json:

     "require": {
         "laravel/framework": "10.0.*"
     }
     

Debugging Tips

1. Dry Run: Use --dry-run to preview changes without generating files:

   php artisan package:make Vendor/Package --dry-run
   

2. Log Output: Enable verbose mode for debugging:

   php artisan package:make Vendor/Package --verbose
   

3. Check Config: Validate config/package-maker.php for custom settings:

   return [
       'stubs' => resource_path('stubs'), // Override default stubs path
       'default_namespace' => 'App',
   ];
   

Extension Points

1. Custom Commands: Extend the package by creating a custom command that uses PackageMaker:

   use Backtheweb\PackageMaker\PackageMaker;
   
   class CustomPackageCommand extends Command {
       protected function handle() {
           $maker = new PackageMaker();
           $maker->setStub('custom.stub')->make('Vendor/Package');
       }
   }
   

2. Dynamic Stub Loading: Load stubs from a remote source (e.g., GitHub) by overriding the getStub() method in a custom PackageMaker class.

3. Post-Processing: Use the postGenerate event to run additional logic after package creation:

   // In a service provider
   PackageMaker::postGenerate(function ($packagePath) {
       // Run custom scripts, e.g., git init
   });
   

4. Template Inheritance: Extend existing stubs by copying them to your project’s resources/stubs/ and modifying only the necessary parts.

Pro Tips

1. Template Versioning: Commit custom stubs to version control to maintain consistency across projects.

2. Package Metadata: Use the --license, --description, and --keywords flags to auto-populate composer.json:

   php artisan package:make Vendor/Package --license=MIT --description="A cool package" --keywords="laravel,api"
   

3. CI/CD Optimization: Cache generated packages in CI to avoid re-running the command on every build:

   # .github/workflows/package.yml
   steps:
     - uses: actions/cache@v3
       with:
         path: packages/
         key: ${{ runner.os }}-packages-${{ hashFiles('**/composer.json') }}
   

4. Monorepo Support: Generate packages in a monorepo by setting a base path:

   php artisan package:make Vendor/Package --path=../monorepo/packages/