Human Date Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Since this package is deprecated in favor of cocur/human-date, verify if the newer package meets your needs. If not, install via Composer:

   composer require braincrafted/human-date-bundle
   

   Register the bundle in config/bundles.php (Symfony):

   return [
       // ...
       Braincrafted\HumanDateBundle\BraincraftedHumanDateBundle::class => ['all' => true],
   ];
   

2. First Use Case Transform a \DateTime object into a human-readable string:

   use Braincrafted\HumanDateBundle\Transformer\HumanDateTransformer;
   
   $transformer = new HumanDateTransformer();
   $date = new \DateTime('2023-10-15');
   echo $transformer->transform($date); // Output: "October 15"
   

3. Twig Integration Enable the Twig extension in your templates:

   {{ episode.airDate|humanDate }}
   

   Requires the bundle to be registered and Twig configured.

Implementation Patterns

Core Workflows

1. Service Integration Register the transformer as a service in Symfony:

   # config/services.yaml
   services:
       App\Services\HumanDateService:
           arguments:
               $transformer: '@braincrafted.human_date.transformer'
   

   Use dependency injection in controllers:

   public function show(HumanDateTransformer $transformer) {
       $humanDate = $transformer->transform($this->getDate());
       return response()->json(['date' => $humanDate]);
   }
   

2. Custom Date Formatting Extend the transformer for project-specific rules:

   class CustomHumanDateTransformer extends HumanDateTransformer {
       public function transform(\DateTime $date) {
           $result = parent::transform($date);
           return str_replace('Today', 'Current Day', $result);
       }
   }
   

   Register the custom service in services.yaml:

   services:
       App\Services\CustomHumanDateTransformer:
           class: App\Services\CustomHumanDateTransformer
           tags: ['human_date.transformer']
   

3. API Responses Use the transformer in JSON APIs for consistent date formatting:

   return response()->json([
       'created_at' => $transformer->transform($post->createdAt),
       'updated_at' => $transformer->transform($post->updatedAt),
   ]);
   

4. Twig Filters Extend Twig’s humanDate filter for dynamic behavior:

   {% set customDate = episode.airDate|humanDate('custom_format') %}
   

   Requires custom Twig extension logic (see Twig Extensions).

Gotchas and Tips

Pitfalls

1. Deprecation Warning This bundle is deprecated in favor of cocur/human-date. Evaluate migration if long-term maintenance is a priority.

   • Migration Tip: Replace braincrafted/human-date-bundle with cocur/human-date and update usage:

     use Cocur\HumanDate\HumanDate;
     
     $humanDate = new HumanDate();
     echo $humanDate->format($date); // Output: "October 15"
     

2. Time Zone Sensitivity The transformer respects the system’s default time zone. Explicitly set time zones for consistency:

   $date = new \DateTime('now', new \DateTimeZone('America/New_York'));
   

3. Caching Static Results Cache transformed dates in performance-critical applications (e.g., dashboard widgets):

   $cacheKey = 'human_date_' . $date->getTimestamp();
   $humanDate = Cache::remember($cacheKey, 3600, function() use ($transformer, $date) {
       return $transformer->transform($date);
   });
   

4. Locale Limitations The bundle defaults to English. For multilingual apps, integrate with Symfony’s translation system or use cocur/human-date’s locale support:

   $humanDate = new HumanDate('en_US');
   

Debugging Tips

1. Edge Cases Test with dates far in the past/future to ensure correct formatting:

   $transformer->transform(new \DateTime('-50 years')); // "1973"
   $transformer->transform(new \DateTime('+100 years')); // "2123"
   

2. Twig Debugging If the Twig filter fails, verify:

   • The bundle is enabled in config/bundles.php.
   • The Twig environment is properly configured (check kernel.twig or framework.twig).

3. Custom Logic Validation When extending the transformer, validate edge cases:

   public function transform(\DateTime $date) {
       $result = parent::transform($date);
       if (strpos($result, 'Invalid') !== false) {
           throw new \RuntimeException('Date transformation failed');
       }
       return $result;
   }
   

Extension Points

1. Custom Rules Override the getRules() method in a subclass to add project-specific logic:

   protected function getRules() {
       return array_merge(parent::getRules(), [
           'custom_rule' => function($date) {
               return $date->format('Y-m-d') === '2023-12-25' ? 'Christmas' : null;
           },
       ]);
   }
   

2. Integration with Carbon If using Carbon, convert it to \DateTime first:

   use Carbon\Carbon;
   
   $date = Carbon::now();
   $transformer->transform($date->toDateTime());
   

3. Symfony Form Types Use the transformer in form types for user-friendly date displays:

   public function configureOptions(OptionsResolver $resolver) {
       $resolver->setDefaults([
           'human_date' => function($date) {
               return (new HumanDateTransformer())->transform($date);
           },
       ]);
   }