README

Easy creation of Laravel packages with customizable stub templates.

Features

Generate complete Laravel package structure
Customizable stub templates for all generated files
Support for conditional content (e.g., test files)
Configurable template paths
Automatic stub file discovery
Template syntax validation

Installation

composer require purwantoid/package-generator

Usage

Basic Package Generation

php artisan make:package VendorName PackageName

Generate Package with Tests

php artisan make:package VendorName PackageName --with-tests

Template System

The package generator uses external stub files for all templates, making it easy to customize the generated package structure.

Stub File Structure

stubs/
├── php/
│   ├── service-provider.stub
│   ├── main-class.stub
│   ├── test-case.stub
│   └── example-test.stub
├── config/
│   ├── config.stub
│   └── phpunit.stub
├── composer/
│   └── composer.json.stub
├── docs/
│   ├── readme.stub
│   └── license.stub
└── routes/
    └── web.stub

Template Variables

All stub files support the following placeholder variables:

{{PACKAGE_NAME}} - Original package name
{{PACKAGE_NAME_KEBAB}} - Package name in kebab-case
{{PACKAGE_NAME_STUDLY}} - Package name in StudlyCase
{{VENDOR_NAME}} - Original vendor name
{{VENDOR_NAME_KEBAB}} - Vendor name in kebab-case
{{VENDOR_NAME_STUDLY}} - Vendor name in StudlyCase
{{NAMESPACE}} - Full namespace (VendorName\PackageName)
{{NAMESPACE_ESCAPED}} - Escaped namespace for JSON (VendorName\\PackageName)
{{COMPOSER_NAME}} - Composer package name (vendor-name/package-name)
{{CLASS_NAME}} - Main class name
{{SERVICE_PROVIDER_CLASS}} - Service provider class name
{{CURRENT_YEAR}} - Current year
{{WITH_TESTS}} - Boolean indicating if tests should be included

Conditional Content

Stub files support conditional blocks for optional content:

{{#WITH_TESTS}}
// This content will only be included when --with-tests option is used
class ExampleTest extends TestCase
{
    // Test methods...
}
{{/WITH_TESTS}}

Customizing Templates

You can customize the generated package structure by modifying the stub files in the stubs/ directory. Changes to stub files will be reflected immediately in newly generated packages.

Custom Stub Paths

You can configure custom paths for specific stub files:

// In a service provider or configuration
$loader = new StubFileLoader(
    $filesystem,
    $defaultStubsPath,
    [
        'service-provider' => '/path/to/custom/service-provider.stub',
        'main-class' => '/path/to/custom/main-class.stub'
    ]
);

Template Validation

The system includes built-in validation for template syntax:

$engine = new StubTemplateEngine($loader, $processor, $filesystem);

// Validate template syntax
$errors = $engine->validateTemplateIntegrity('service-provider');
if (!empty($errors)) {
    // Handle validation errors
}

// Validate required variables
$engine->processTemplate('service-provider', $variables, false, true);

Configuration

The package supports various configuration options for customizing the template system:

Stub Directory Configuration

// Configure custom stubs directory
$loader = new StubFileLoader($filesystem, '/custom/stubs/path');

// Enable fallback to default stubs
$loader = new StubFileLoader(
    $filesystem,
    '/primary/stubs/path',
    [],
    true, // fallback enabled
    '/fallback/stubs/path'
);

Template Discovery

The system automatically discovers new stub files without requiring code changes:

$engine = new StubTemplateEngine($loader, $processor, $filesystem);

// Get all available stub files
$availableStubs = $engine->getAvailableStubs();

// Check for new stub files
$newStubs = $engine->getNewStubs($previousStubList);

Error Handling

The template system provides comprehensive error handling:

Missing stub files: Clear error messages with troubleshooting steps
Invalid template syntax: Detailed syntax validation with line numbers
Undefined variables: Validation of required template variables
File permissions: Graceful handling of permission errors
Path security: Protection against path traversal attacks

Requirements

PHP 8.3 or higher
Laravel 9.0, 10.0, 11.0, or 12.0
Illuminate Filesystem package

License

This package is open-sourced software licensed under the MIT license.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

Version 2.0.0

Refactored to use external stub template system
Added template syntax validation
Improved error handling and user feedback
Added support for conditional content blocks
Implemented configurable template paths
Added automatic stub file discovery

Version 1.0.0

Initial release with hardcoded templates

purwantoid / package-generator

Maintainers

Details