php-builder-generator

Installation Guide

This guide provides detailed installation instructions for PHP Builder Generator.

Requirements

• PHP: 8.2 or higher
• Composer: 2.0 or higher

Installation

composer require maxbeckers/php-builder-generator

Plugin Configuration

Allow Plugin

After installation, you must allow the plugin in your composer.json:

{
  "config": {
    "allow-plugins": {
      "maxbeckers/php-builder-generator": true
    }
  }
}

Why is this required? Composer 2.2+ requires explicit permission for plugins to run for security reasons.

Auto-allow During Installation

Alternatively, you can allow the plugin during installation:

composer require maxbeckers/php-builder-generator --with-dependencies
composer config allow-plugins.maxbeckers/php-builder-generator true

Autoload Configuration for Generated Builders

Required: You must add the generated builder path to your autoload.psr-4 section in composer.json. The path must include your namespace.

Example Configuration

If your classes are in the App namespace:

{
  "autoload": {
    "psr-4": {
      "App\\": ["src/", "generated/php-builder-generator/App/"]
    }
  }
}

If you have multiple namespaces:

{
  "autoload": {
    "psr-4": {
      "App\\": ["src/", "generated/php-builder-generator/App/"],
      "Domain\\": ["domain/", "generated/php-builder-generator/Domain/"]
    }
  }
}

Important Notes

• The path must include the namespace (e.g., generated/php-builder-generator/App/)
• Do not use just generated/php-builder-generator/
• Each namespace requires its own entry in the autoload configuration

Apply Changes

After updating your composer.json, regenerate the autoload files:

composer dump-autoload

Verification

Verify Installation

Check that the plugin is installed correctly:

composer show maxbeckers/php-builder-generator

Test Generation

Create a simple test class:

<?php
// test/TestUser.php

namespace Test;

use MaxBeckers\PhpBuilderGenerator\Attributes\Builder;

#[Builder]
class TestUser
{
    public function __construct(
        public string $name,
        public string $email
    ) {}
}

Run generation:

./vendor/bin/php-builder-generator --src-dirs=test

Check that the builder was created in the output directory.

Configuration

Basic Configuration

Add basic configuration to your composer.json:

{
    "extra": {
        "php-builder-generator": {
            "src-dirs": ["src"],
            "output-dir": "generated/php-builder-generator/",
            "auto-generate": true
        }
    }
}

Advanced Configuration

For more complex projects:

{
    "extra": {
        "php-builder-generator": {
            "src-dirs": ["src", "app/Models", "lib"],
            "output-dir": "generated/builders/",
            "namespace-suffix": "\\Builder",
            "php-version": "8.2",
            "auto-generate": true
        }
    },
    "config": {
        "allow-plugins": {
            "maxbeckers/php-builder-generator": true
        }
    }
}

Troubleshooting

Common Issues

Plugin Not Allowed

Error: maxbeckers/php-builder-generator contains a Composer plugin which is blocked by your allow-plugins config

Solution: Add the plugin to your allow-plugins configuration:

composer config allow-plugins.maxbeckers/php-builder-generator true

Command Not Found

Error: ./vendor/bin/php-builder-generator: No such file or directory

Solutions:

1. Check installation: composer show maxbeckers/php-builder-generator
2. Reinstall: composer install --no-dev=false
3. Check permissions: ls -la vendor/bin/php-builder-generator

Auto-generation Not Working

Symptoms: Builders not generated during composer install/update

Solutions:

1. Verify plugin is allowed in composer.json
2. Check auto-generate is true in configuration
3. Verify classes have #[Builder] attribute
4. Check source directories are correct

Permission Denied

Error: Permission denied when writing generated files

Solutions:

1. Check write permissions on output directory
2. Create output directory: mkdir -p generated/php-builder-generator
3. Fix permissions: chmod 755 generated/php-builder-generator

Namespace Issues

Error: Class 'UserBuilder' not found

Solutions:

1. Verify autoload configuration includes namespace-specific path
2. Run composer dump-autoload
3. Check that the generated builders exist in the correct namespace directory
4. Ensure the path format is generated/php-builder-generator/YourNamespace/

Getting Help

If you encounter issues:

1. Check the troubleshooting section
2. Search existing issues
3. Create a new issue with:
   • PHP version (php --version)
   • Composer version (composer --version)
   • Full error message
   • Your composer.json configuration

Next: Basic Usage Guide

This site is open source. Improve this page.