Php Date Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require assoconnect/php-date-bundle
   

   Ensure your config/bundles.php includes:

   Assoconnect\PhpDateBundle\PhpDateBundle::class => ['all' => true],
   

2. First Use Case:

   • Doctrine Entity:

     use Assoconnect\PhpDate\AbsoluteDate;
     use Doctrine\DBAL\Types\Types;
     use Doctrine\ORM\Mapping as ORM;
     
     #[ORM\Entity]
     class Event
     {
         #[ORM\Column(type: AbsoluteDateType::NAME)]
         private AbsoluteDate $date;
     }
     

   • Twig Template:

     {{ event.date|date('Y-m-d') }}  {# Renders as "2024-02-14" #}
     

3. Key Files to Review:

   • config/packages/assoconnect_php_date.yaml (default config)
   • src/Assoconnect/PhpDateBundle/DependencyInjection/ (for advanced config)

Implementation Patterns

Core Workflows

1. Doctrine Integration

• Type Conversion:

  $absoluteDate = new AbsoluteDate('2024-02-14T12:00:00+02:00');
  $entityManager->persist($event); // Automatically converts to DB storage format
  

• QueryBuilder Support:

  $qb->andWhere('e.date > :minDate')
    ->setParameter('minDate', new AbsoluteDate('2024-01-01'));
  

2. Serialization

• Normalization:

  $normalizer = new AbsoluteDateNormalizer();
  $normalized = $normalizer->normalize($absoluteDate, null, [
      'format' => 'Y-m-d\TH:i:sP'
  ]);
  // Returns: "2024-02-14T12:00:00+02:00"
  

• Denormalization:

  $denormalizer = new AbsoluteDateNormalizer();
  $date = $denormalizer->denormalize('2024-02-14', null, [
      'format' => 'Y-m-d'
  ]);
  

3. Twig Extensions

• Filters:

  {{ event.date|date('d/m/Y') }}          {# "14/02/2024" #}
  {{ event.date|timezone('America/New_York')|date('H:i') }} {# Localized time #}
  

• Custom Extensions:

  // src/Twig/Extension/CustomDateExtension.php
  class CustomDateExtension extends \Twig\Extension\AbstractExtension
  {
      public function getFilters(): array
      {
          return [
              new \Twig\TwigFilter('is_future', [$this, 'isFutureDate']),
          ];
      }
  
      public function isFutureDate(AbsoluteDate $date): bool
      {
          return $date > new AbsoluteDate();
      }
  }
  

4. Testing with AbsoluteDateClock

• Mocking Time:

  use Assoconnect\PhpDateBundle\Clock\AbsoluteDateClock;
  
  $clock = new AbsoluteDateClock(new \DateTimeImmutable('2024-02-15'));
  $this->container->set('assoconnect_php_date.clock', $clock);
  
  // Now all AbsoluteDate instances will use 2024-02-15 as "now"
  

5. Translatable Dates

• Symfony Translatable Integration:

  use Assoconnect\PhpDateBundle\Translatable\AbsoluteDateTranslatable;
  
  #[ORM\Entity]
  class MultilingualEvent
  {
      #[ORM\Column(type: AbsoluteDateType::NAME)]
      #[AbsoluteDateTranslatable]
      private AbsoluteDate $date;
  }
  

Integration Tips

1. Database Schema:

   • The AbsoluteDateType stores dates as ISO-8601 strings (e.g., "2024-02-14T12:00:00+02:00"). Ensure your DB supports TEXT or VARCHAR columns.

2. Clock Service:

   • Override the default Clock service in config/services.yaml:

     services:
         assoconnect_php_date.clock:
             class: Assoconnect\PhpDateBundle\Clock\AbsoluteDateClock
             arguments:
                 $clock: '@clock' # Symfony's default Clock
     

3. Validation:

   • Combine with assoconnect/validator-bundle for custom validation:

     use Assoconnect\Validator\Constraints\AbsoluteDate;
     
     #[ORM\Entity]
     class Event
     {
         #[ORM\Column(type: AbsoluteDateType::NAME)]
         #[AbsoluteDate('future')]
         private AbsoluteDate $date;
     }
     

4. API Responses:

   • Use the AbsoluteDateNormalizer in API platforms:

     # config/packages/api_platform.yaml
     api_platform:
         formats:
             jsonld:
                 normalization_context:
                     groups: ['api']
                     date_format: 'Y-m-d\TH:i:sP'
     

Gotchas and Tips

Pitfalls

1. Time Zone Handling:

   • Issue: AbsoluteDate uses the system default timezone if none is specified.
   • Fix: Explicitly set the timezone in constructors or normalizers:

     $date = new AbsoluteDate('2024-02-14T12:00:00', 'Europe/Paris');
     

2. Doctrine Hydration:

   • Issue: If your DB stores dates as DATETIME instead of TEXT, Doctrine may fail to hydrate.
   • Fix: Configure the AbsoluteDateType in config/packages/doctrine.yaml:

     doctrine:
         dbal:
             types:
                 AbsoluteDate:
                     class: Assoconnect\PhpDate\Doctrine\AbsoluteDateType
                     comment: "Stores dates as ISO-8601 strings"
     

3. Twig Caching:

   • Issue: Twig filters may not update if the bundle is not recompiled.
   • Fix: Clear Twig cache after updates:

     php bin/console cache:clear --env=prod
     

4. PHP 8.4+ Changes:

   • Issue: Some older Symfony versions may conflict with PHP 8.4’s strict types.
   • Fix: Ensure you’re using Symfony ^7.0 and assoconnect/php-date:^2.11.

5. Null Values:

   • Issue: The normalizer throws exceptions for null by default (pre-2.0.1 behavior).
   • Fix: Configure the normalizer to handle null:

     $normalizer->setIgnoredAttributes(['null']);
     

Debugging Tips

1. Clock Debugging:

   • Dump the current clock in a controller:

     use Assoconnect\PhpDate\AbsoluteDate;
     
     public function debugClock(): void
     {
         $now = new AbsoluteDate();
         dump($now->format('Y-m-d H:i:sP')); // Check timezone/offset
     }
     

2. Doctrine Type Issues:

   • Verify the type is registered:

     php bin/console debug:doctrine
     

   • Look for AbsoluteDate under "Custom Types."

3. Twig Filter Not Found:

   • Ensure the AbsoluteDateExtension is loaded. Check var/cache/dev/Twig* for errors.

4. Denormalization Failures:

   • Validate input formats:

     $denormalizer->denormalize('invalid-date', null, ['format' => 'Y-m-d']);
     // Throws: \Assoconnect\PhpDate\Exception\InvalidDateException
     

Extension Points

1. Custom Doctrine Types:

   • Extend AbsoluteDateType for domain-specific logic:

     class CustomAbsoluteDateType extends AbsoluteDateType
     {
         public function convertToDatabaseValue($value, AbstractPlatform $platform)
         {
             if ($value instanceof AbsoluteDate) {
                 return $value->format('Y-m-d H:i:s.uP'); // Custom format
             }
             return parent::convertToDatabaseValue($value, $platform);
         }
     }
     

2. Clock Decorators:

   • Decorate the AbsoluteDateClock to add logic:

     use Symfony\Component\Clock\Clock;
     
     class LoggingClockDecorator implements Clock
     {
         public function __construct(private Clock $clock) {}
     
         public function now(): \DateTimeInterface