Skip to content

advanced.md

Latest commit

 

History

History
345 lines (255 loc) · 7.17 KB

advanced.md

File metadata and controls

345 lines (255 loc) · 7.17 KB

Advanced Usage

This guide covers advanced scenarios for using make-bundle.

Command Options

Interactive Mode

Force interactive configuration even when providing arguments:

bin/console make:bundle acme/my-bundle lib --interactive
# or
bin/console make:bundle acme/my-bundle lib -i

Non-Interactive Mode (Default)

When providing vendor-package and target-folder, the bundle uses defaults:

bin/console make:bundle acme/my-bundle lib

Default configuration:

  • Symfony 6.4 LTS
  • Unit and integration test structure
  • Documentation structure included
  • No optional features (services, commands, controllers, etc.)

Using Generated Bundles in Your Project

Path Repositories

Add the bundle as a local repository in your project's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "./lib/acme/my-bundle"
        }
    ]
}

Install the Bundle

composer require acme/my-bundle @dev

The @dev version allows Composer to use your local development version.

Enable the Bundle

Symfony Flex usually auto-registers bundles, but if not:

// config/bundles.php
return [
    // ...
    Acme\MyBundle\AcmeMyBundleBundle::class => ['all' => true],
];

Remove the Bundle

composer remove acme/my-bundle

Bundle Configuration

Optional Features

When using interactive mode, you can select:

Dependencies:

  • Symfony Console (for commands)
  • Twig Bundle (for Twig extensions)
  • Asset Component (for asset management)
  • Security Bundle (for security features)
  • Doctrine Bundle (for ORM integration)
  • Messenger (for message handling)
  • Validator (for data validation)
  • Serializer (for data serialization)
  • HTTP Client (for HTTP requests)
  • Mailer (for email sending)

Features:

  • Compiler passes
  • Event subscribers
  • Twig functions/filters
  • Custom form types
  • Custom validators

Components:

  • Services
  • Console commands
  • Controllers
  • Twig extensions

Testing:

  • Unit tests
  • Integration tests
  • Functional tests

Vendor Auto-Discovery

The command tries to auto-discover your vendor name from:

  1. Existing vendor directories (vendor/, lib/, packages/, etc.)
  2. composer.json in current directory
  3. Git configuration (git config user.name)
  4. System username
  5. Random generation (fallback)

Configuring Vendor Discovery

Create config/make_bundle.yaml in your project:

vendor_discovery:
    vendor_directories:
        - vendor
        - lib
        - packages
        - bundles
    excluded_directories:
        - node_modules
        - .git
        - var
        - tmp
    preferred_vendors:
        - acme
        - my-vendor

package_generation:
    prefixes:
        - bundle
        - component
        - library
    adjectives:
        - awesome
        - cool
        - smart
    nouns:
        - utils
        - helpers
        - tools

Multiple Bundles in Same Vendor

You can create multiple bundles under the same vendor:

bin/console make:bundle acme/utils lib
bin/console make:bundle acme/helpers lib
bin/console make:bundle acme/widgets lib

Structure:

lib/
├── acme/
│   ├── utils/
│   ├── helpers/
│   └── widgets/

Each bundle can be required separately:

composer require acme/utils @dev
composer require acme/helpers @dev

Working with Monorepos

Strategy 1: Single Target Folder

# All bundles in lib/
bin/console make:bundle acme/bundle-one lib
bin/console make:bundle acme/bundle-two lib
bin/console make:bundle acme/bundle-three lib

Strategy 2: Separate Vendor Folders

# Different vendors in different folders
bin/console make:bundle acme/bundle lib
bin/console make:bundle vendor-two/bundle packages

Strategy 3: Per-Bundle Repositories

# Each bundle in its own top-level folder
bin/console make:bundle acme/bundle-one repos
bin/console make:bundle acme/bundle-two repos

Customizing Templates

Using Custom Template Directory

Override the template directory in your project:

# config/packages/make_bundle.yaml
parameters:
    neuralglitch_make_bundle.template_dir: '%kernel.project_dir%/my-templates'

Forking Templates

  1. Copy templates from vendor/neuralglitch/make-bundle/templates/
  2. Modify as needed
  3. Configure custom template directory
  4. Generate bundles with your templates

See templates.md for template customization guide.

Troubleshooting

Bundle Not Created

Problem: Command succeeds but no bundle directory

Solutions:

  • Check target folder exists and is writable
  • Verify vendor/package name format (vendor/package)
  • Check for permission errors

Invalid Vendor/Package Name

Problem: Invalid vendor/package format

Solution: Use lowercase letters and dashes only:

  • ✅ acme/awesome-utils
  • ❌ Acme/AwesomeUtils
  • ❌ acme_corp/awesome_utils

Composer Can't Find Bundle

Problem: composer require can't find your bundle

Solution: Add path repository to composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "./lib/vendor/package"
        }
    ]
}

Wrong Symfony Syntax Generated

Problem: Bundle has attributes but project uses Symfony 6.4

Solution:

  • Regenerate bundle with correct Symfony version
  • Or manually convert attributes to annotations

See symfony-versions.md for version migration guide.

Examples

Minimal Bundle (Symfony 6.4)

bin/console make:bundle acme/minimal lib
# Accept all defaults

Result: Basic bundle with annotations, no optional features.

Full-Featured Bundle (Symfony 7.1)

bin/console make:bundle acme/full-bundle lib --interactive

Then select:

  • Symfony 7.1 LTS
  • Services: Yes
  • Commands: Yes
  • Controllers: Yes
  • Twig Extensions: Yes
  • All test types

Result: Complete bundle with all features and attributes.

API Client Bundle

bin/console make:bundle acme/api-client lib --interactive

Select:

  • Services: Yes (for API client service)
  • HTTP Client dependency
  • Unit + Integration tests

Form Bundle

bin/console make:bundle acme/custom-forms lib --interactive

Select:

  • Form types feature
  • Twig extensions (for form rendering)
  • Validators (for form validation)

Next Steps

After generating a bundle:

  1. Read the generated README.md in the bundle directory
  2. Install dependencies: cd lib/vendor/package && composer install
  3. Add your code to the generated structure
  4. Write tests in tests/Unit/ and tests/Integration/
  5. Configure your bundle in src/DependencyInjection/Configuration.php
  6. Add services to src/Resources/config/services.yaml

Related Documentation

See Also