Getting Started

Minimal Steps

Installation

composer require black/common-bundle

Add to config/bundles.php (Symfony):

return [
    // ...
    Black\CommonBundle\BlackCommonBundle::class => ['all' => true],
];

First Use Case: Events

Trigger an event:

use Black\CommonBundle\Event\CommonEvent;

$event = new CommonEvent();
$dispatcher->dispatch($event, CommonEvent::NAME);

Listen to an event (in a service or controller):

use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class MySubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            CommonEvent::NAME => 'onCommonEvent',
        ];
    }

    public function onCommonEvent(CommonEvent $event)
    {
        // Handle event logic
    }
}

First Use Case: Transformers

Use a transformer to convert an entity to an array:

use Black\CommonBundle\Transformer\TransformerInterface;

$transformer = new MyTransformer();
$data = $transformer->transform($entity);

Implementation Patterns

Workflows

Event-Driven Architecture

Workflow: Use events for cross-cutting concerns (e.g., logging, notifications).

// Dispatch an event after saving an entity
$entityManager->persist($entity);
$entityManager->flush();

$event = new CommonEvent($entity);
$dispatcher->dispatch($event, CommonEvent::ENTITY_SAVED);

Subscriber Pattern: Centralize logic in subscribers for maintainability.

// Example: Log all entity saves
class LoggingSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [CommonEvent::ENTITY_SAVED => 'logEntitySave'];
    }

    public function logEntitySave(CommonEvent $event)
    {
        \Log::info('Entity saved:', ['entity' => $event->getEntity()]);
    }
}

Data Transformation

Workflow: Standardize API responses or internal data formats.

// Define a transformer for a User entity
class UserTransformer implements TransformerInterface
{
    public function transform($user)
    {
        return [
            'id' => $user->getId(),
            'name' => $user->getName(),
            'email' => $user->getEmail(),
        ];
    }
}

Usage in Controllers:

public function show(User $user, UserTransformer $transformer)
{
    return $this->json($transformer->transform($user));
}

Type Safety with Interfaces

Workflow: Enforce contracts for services or entities.

// Define an interface for a service
interface UserServiceInterface
{
    public function findByEmail(string $email): ?User;
}

Implementation:

class UserService implements UserServiceInterface
{
    public function findByEmail(string $email): ?User
    {
        // Logic here
    }
}

Extensions

Workflow: Extend bundle functionality via traits or decorators.

// Example: Extend a transformer with additional fields
class ExtendedUserTransformer extends UserTransformer
{
    public function transform($user)
    {
        $data = parent::transform($user);
        $data['roles'] = $user->getRoles();
        return $data;
    }
}

Gotchas and Tips

Pitfalls

Archived Status
- The bundle is archived (no active maintenance). Evaluate risks before adoption, especially for production-critical projects.
- Mitigation: Fork the repo if you need modifications or long-term support.
Limited Documentation
- The Resources/doc/index.md is the primary source, but it may lack depth or examples.
- Tip: Explore the Symfony EventDispatcher and Hateoas (inspiration) for patterns.
Event Naming Collisions
- Custom events might conflict with Symfony’s built-in events.
- Tip: Prefix event names (e.g., COMMON_BUNDLE.ENTITY_SAVED).
Transformer Flexibility
- Transformers are basic; complex nested transformations may require manual handling.
- Tip: Combine with API Platform’s Serializer or JMS Serializer for advanced use cases.

Debugging

Event Dispatching Issues
- Verify subscribers are registered and tagged correctly in Symfony’s DI container.
- Debug:
```
php bin/console debug:event-dispatcher
```
- Check for typos in event names or subscriber methods.

Transformer Output

Use var_dump() or dd() to inspect transformed data:

$transformed = $transformer->transform($entity);
dd($transformed);

Config Quirks

Bundle Configuration
- The bundle may not require config/packages/black_common.yaml, but check for optional settings in the docs.
- Tip: Override services in config/services.yaml if needed:
```
services:
    Black\CommonBundle\Transformer\UserTransformer:
        tags: ['black.common.transformer']
```
Dependency Injection
- Ensure services implementing TransformerInterface are tagged or autowired properly.
- Example:
```
# config/services.yaml
_defaults:
    autowire: true
    autoconfigure: true
```

Extension Points

Custom Events

Extend the CommonEvent class for domain-specific events:

class OrderProcessedEvent extends CommonEvent
{
    public const NAME = 'order.processed';

    public function __construct(private Order $order)
    {
        parent::__construct();
    }

    public function getOrder(): Order
    {
        return $this->order;
    }
}

Transformer Decorators

Decorate transformers to add logic without modifying original classes:

class CachingUserTransformer implements TransformerInterface
{
    private $decorated;

    public function __construct(TransformerInterface $decorated)
    {
        $this->decorated = $decorated;
    }

    public function transform($user)
    {
        $data = $this->decorated->transform($user);
        // Add caching logic
        return $data;
    }
}

services:
    App\Transformer\CachingUserTransformer:
        decorates: 'black.common.transformer.user'
        arguments: ['@App\Transformer\CachingUserTransformer.inner']

Event Listeners as Services

Define listeners as services for better testability:

# config/services.yaml
services:
    App\EventListener\OrderListener:
        tags:
            - { name: kernel.event_listener, event: order.processed, method: onOrderProcessed }

Common Bundle Laravel Package