Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bro-world/core-bundle
   

   Ensure your composer.json includes:

   "require": {
       "bro-world/core-bundle": "^0.2.5",
       "lexik/jwt-auth-bundle": "^2.16",  # Auto-added by the bundle
       "automapper/automapper": "^2.0"     # Auto-added by the bundle
   }
   

2. Bundle Registration: Add to config/bundles.php:

   BroWorld\CoreBundle\BroWorldCoreBundle::class => ['all' => true],
   

3. First Use Case: Use the UTCDateTimeType for Doctrine entities:

   use BroWorld\CoreBundle\Doctrine\Types\UTCDateTimeType;
   
   #[ORM\Entity]
   class MyEntity {
       #[ORM\Column(type: UTCDateTimeType::NAME)]
       private ?\DateTimeInterface $createdAt = null;
   }
   

Implementation Patterns

Core Workflows

1. AutoMapper Integration: Define mappings in config/packages/automapper.php:

   automapper:
       mappings:
           App\Entity\User:
               to: App\DTO\UserDTO
               type: entity_to_dto
   

   Use in services:

   $mapper = $this->get(MapperInterface::class);
   $dto = $mapper->map($entity, UserDTO::class);
   

2. JWT Authentication: Configure Lexik JWT in config/packages/lexik_jwt_auth.yaml:

   lexik_jwt_authentication:
       secret_key: '%env(JWT_SECRET_KEY)%'
       public_key: '%env(JWT_PUBLIC_KEY)%'
   

   Secure routes with annotations:

   #[Route('/api/protected', methods: ['GET'])]
   #[IsGranted('ROLE_USER')]
   public function protectedRoute(): JsonResponse { ... }
   

3. UTC DateTime Handling: Use UTCDateTimeType for consistent timezone handling:

   $entity->setCreatedAt(new \DateTime('now', new \DateTimeZone('UTC')));
   

Integration Tips

• Doctrine Events: Extend UTCDateTimeType for custom logic:

  use BroWorld\CoreBundle\Doctrine\Types\UTCDateTimeType;
  use Doctrine\DBAL\Types\Type;
  
  Type::addType('custom_utc_datetime', CustomUTCDateTimeType::class);
  

• API Proxy Tooling: Leverage the bundle’s proxy configuration for external API calls:

  # config/packages/bro_world_core.yaml
  bro_world_core:
      api_proxies:
          stripe:
              base_uri: 'https://api.stripe.com/v1'
              auth: 'Bearer %env(STRIPE_SECRET_KEY)%'
  

Gotchas and Tips

Pitfalls

1. AutoMapper Alias Fix: Ensure automapper service alias is correctly registered in services.yaml:

   services:
       Automapper\Automapper:
           alias: automapper
   

   (Fixed in v0.2.4, but may still cause issues in older setups.)

2. UTCDateTimeType Compatibility:

   • Doctrine Version: Ensure compatibility with Doctrine DBAL 3.x+.
   • Return Type: Methods must return \DateTimeInterface (fixed in v0.2.2).

3. JWT Bundle Dependency:

   • Lexik JWT is auto-installed but requires manual configuration.
   • Verify JWT_SECRET_KEY and JWT_PUBLIC_KEY are set in .env.

Debugging Tips

• AutoMapper Errors: Check if mappings are registered in automapper.php and services are autowired.

  php bin/console debug:automapper
  

• UTCDateTimeType Issues: Validate database column types (e.g., DATETIME(6) for MySQL).

  ALTER TABLE my_table MODIFY created_at DATETIME(6) NULL;
  

Extension Points

1. Custom Doctrine Types: Extend UTCDateTimeType for project-specific logic:

   class CustomUTCDateTimeType extends UTCDateTimeType {
       public function convertToDatabaseValue($value, AbstractPlatform $platform) {
           // Custom conversion logic
           return parent::convertToDatabaseValue($value, $platform);
       }
   }
   

2. API Proxy Extensions: Add custom proxy handlers in bro_world_core.yaml:

   bro_world_core:
       api_proxies:
           custom_service:
               handler: App\Service\CustomProxyHandler
   

3. Event Subscribers: Subscribe to Doctrine lifecycle events for UTCDateTimeType:

   use Doctrine\Common\EventSubscriber;
   use Doctrine\ORM\Events;
   
   class UTCDateTimeSubscriber implements EventSubscriber {
       public function getSubscribedEvents() {
           return [Events::prePersist, Events::preUpdate];
       }
   
       public function prePersist(LifecycleEventArgs $args) {
           $entity = $args->getObject();
           if (method_exists($entity, 'setCreatedAt')) {
               $entity->setCreatedAt(new \DateTime('now', new \DateTimeZone('UTC')));
           }
       }
   }