Getting Started

Minimal Setup

Install via Composer
```
composer require common-gateway/open-catalogi-bundle:dev-main
```
- Ensure your project is a Symfony Flex-based application (default for Laravel-like workflows in PHP).
- Verify composer.json includes the package under require.
Run the Installer Command
```
php bin/console commongateway:install common-gateway/open-catalogi-bundle
```
- This generates entities, migrations, and config files for the bundle.
- Confirm the command outputs success (e.g., Bundle installed successfully).
Verify Installation
- Check config/packages/ for new bundle configs (e.g., common_gateway_open_catalogi.yaml).
- Run migrations:
```
php bin/console doctrine:migrations:migrate
```

First Use Case: Extending a Bundle

Example: Add a custom entity to the bundle’s schema.

Locate the bundle’s Resources/config/doctrine/ directory.

Extend an existing entity (e.g., CatalogItem.php) by:

// src/Entity/CustomCatalogItem.php
namespace App\Entity;

use CommonGateway\OpenCatalogiBundle\Entity\CatalogItem;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class CustomCatalogItem extends CatalogItem {
    #[ORM\Column]
    private string $customField;
}

Update the bundle’s config/doctrine/orm/auto_mapping.xml to include your namespace.

Implementation Patterns

Workflow: Plugin Development

Template-Based Creation
- Use the BRPBundle template to scaffold a new bundle.
- Replace placeholders (e.g., CommonGateway\OpenCatalogiBundle → YourVendor\YourBundle).

Dependency Injection

Leverage Symfony’s DI container to inject bundle services:

# config/services.yaml
services:
    YourVendor\YourBundle\Service\YourService:
        arguments:
            $catalogService: '@common_gateway_open_catalogi.catalog_service'

Command Integration

Extend the commongateway:install command for custom logic:

// src/Command/YourInstallCommand.php
namespace YourVendor\YourBundle\Command;

use CommonGateway\BRPBundle\Command\InstallCommand;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class YourInstallCommand extends InstallCommand {
    protected function execute(InputInterface $input, OutputInterface $output): int {
        $this->installEntities($output); // Custom logic
        return Command::SUCCESS;
    }
}

commands:
    YourVendor\YourBundle\Command\YourInstallCommand: ~

Event Listeners

Hook into bundle events (e.g., common_gateway.catalog.item.created):

// src/EventListener/CatalogListener.php
namespace YourVendor\YourBundle\EventListener;

use CommonGateway\OpenCatalogiBundle\Event\CatalogItemEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class CatalogListener implements EventSubscriberInterface {
    public static function getSubscribedEvents(): array {
        return [
            CatalogItemEvent::CREATED => 'onItemCreated',
        ];
    }

    public function onItemCreated(CatalogItemEvent $event) {
        // Custom logic (e.g., log, notify)
    }
}

Integration Tips

Doctrine Migrations: Use make:migration after modifying entities:
```
php bin/console make:migration
```

Flex Recipes: Override bundle recipes in config/bundles.php:

return [
    // ...
    YourVendor\YourBundle\YourBundle::class => ['all' => true],
];

Testing: Mock bundle services in PHPUnit:

$this->container->set(
    'common_gateway_open_catalogi.catalog_service',
    $this->createMock(CatalogService::class)
);

Gotchas and Tips

Pitfalls

Namespace Collisions
- Ensure your bundle’s namespace (e.g., YourVendor\YourBundle) doesn’t conflict with existing bundles.
- Fix: Use unique vendor names (e.g., Acme instead of App).
Command Registration
- Forgetting to register custom commands in Resources/config/services.yaml will make them unavailable.
- Fix: Verify the commands section includes your command class.
Doctrine Entity Generation
- Manually editing src/Entity/ without running make:entity or make:migration can break schema updates.
- Fix: Use Symfony’s CLI tools for entity changes:
```
php bin/console make:entity YourEntity
```
Flex Autoloading
- New classes in src/ may not autoload if composer dump-autoload isn’t run post-install.
- Fix: Add this to your composer.json scripts:
```
"post-install-cmd": [
    "@composer/symfony-scripts",
    "composer dump-autoload"
]
```

Debugging

Command Errors: Use --verbose to debug:

php bin/console commongateway:install --verbose common-gateway/open-catalogi-bundle

Entity Mapping Issues: Check for @ORM\Entity annotations and mappings in config/packages/doctrine.yaml:
```
doctrine:
    orm:
        mappings:
            YourBundle: ~
```
Service Not Found: Verify the service ID matches the class name (e.g., your_vendor.your_bundle.service).

Extension Points

Custom Install Steps

Override InstallCommand to add pre/post-install logic (e.g., database seeding):

protected function installEntities(OutputInterface $output): void {
    $this->installDefaultEntities($output);
    $this->seedDefaultData($output); // Custom method
}

Dynamic Configuration
- Use Symfony’s ParameterBag to load bundle-specific configs:
```
$this->container->getParameter('your_bundle.config.key');
```
- Define in config/packages/your_bundle.yaml:
```
your_bundle:
    config:
        key: value
```

API Extensions

Extend bundle controllers via traits or inheritance:

// src/Controller/CatalogController.php
namespace YourVendor\YourBundle\Controller;

use CommonGateway\OpenCatalogiBundle\Controller\CatalogController as BaseController;

class CatalogController extends BaseController {
    public function customAction(): Response {
        // Extend logic
    }
}

Route in Resources/config/routing.yaml:

your_bundle_custom:
    path: /custom
    controller: YourVendor\YourBundle\Controller\CatalogController::customAction

Asset Management
- Override bundle assets (e.g., CSS/JS) by placing files in Resources/public/ and using Symfony’s asset system:
```
{{ asset('bundles/yourbundle/css/style.css') }}
```

Brp Bundle Laravel Package