Date Format Converter Laravel Package

## Getting Started

### **Minimal Setup**
1. **Installation**
   ```bash
   composer require danharrin/date-format-converter

No configuration is required—just autoload the package.

2. First Use Case: Convert a Date String

   use DanHarrin\DateFormatConverter\Converter;
   
   $converter = new Converter();
   $converted = $converter->convert('2024-06-13', 'Y-m-d', 'd/m/Y');
   // Output: "13/06/2024"
   

   New Feature (v0.3.1): Ordinal Suffixes Convert dates with ordinal suffixes (e.g., "1st", "2nd", "3rd"):

   $converted = $converter->convert('2024-06-13', 'Y-m-d', 'jS'); // "13th"
   

3. Where to Look First

   • Converter class: Core functionality for format conversions.
   • Converter::convert(): Primary method for token-based conversions.
   • Converter::getFormat(): Extract tokens from a format string (e.g., 'Y-m-d' → ['Y', 'm', 'd']).
   • Converter::getDate(): Parse a date string into a DateTime object.
   • New Token: jS (and related): Added support for ordinal suffixes (e.g., jS, dS).

Implementation Patterns

Common Workflows

1. Dynamic Format Handling Useful for user-submitted formats (e.g., CMS or API inputs):

   $userFormat = request('date_format'); // e.g., "MM/DD/YYYY"
   $converter->convert($dateString, 'Y-m-d', $userFormat);
   

2. Batch Processing Convert arrays of dates efficiently:

   $dates = ['2024-01-01', '2024-02-01'];
   $formatted = array_map(
       fn($date) => $converter->convert($date, 'Y-m-d', 'jS Y'), // "1st 2024"
       $dates
   );
   

3. Integration with Laravel

   • Form Requests: Validate and sanitize date formats:

     public function rules()
     {
         return ['date' => 'required|date_format:Y-m-d'];
     }
     

   • Carbon Compatibility: Convert to/from Carbon:

     $carbon = Carbon::parse('2024-06-13');
     $converted = $converter->convert($carbon->format('Y-m-d'), 'Y-m-d', 'jS M Y'); // "13th June 2024"
     

4. Localization and Ordinal Suffixes Handle locale-specific formats and ordinals (e.g., German jS. m. Y):

   $converter->convert('2024-06-13', 'Y-m-d', 'jS. m. Y'); // "13. June 2024" (locale-dependent)
   

Advanced Patterns

1. Custom Token Support Extend the converter for non-standard tokens (e.g., Q for quarter) or leverage new ordinal tokens:

   $converter->addToken('week', fn(DateTime $date) => $date->format('W'));
   $converter->convert('2024-06-13', 'Y-m-d', 'jS of Week w'); // "13th of Week 24"
   

2. Fallback Formats Handle ambiguous inputs gracefully:

   try {
       $converted = $converter->convert('06/13/2024', 'm/d/Y', 'jS F Y');
   } catch (InvalidArgumentException $e) {
       // Fallback to default parsing
   }
   

3. Testing Mock the Converter in unit tests, including ordinal suffixes:

   $converter = $this->createMock(Converter::class);
   $converter->method('convert')
       ->with('2024-06-13', 'Y-m-d', 'jS')
       ->willReturn('13th');
   

Gotchas and Tips

Pitfalls

1. Token Mismatches

   • Issue: convert('2024-06-13', 'Y-m-d', 'j-m-Y') may fail if the input doesn’t match the source format.
   • Fix: Always validate input formats or use getDate() first:

     $date = $converter->getDate('2024-06-13', 'Y-m-d');
     $converted = $date->format('jS'); // "13th"
     

2. Timezone Sensitivity

   • Issue: DateTime objects respect the system timezone. Use setTimezone() if needed:

     $date = $converter->getDate('2024-06-13', 'Y-m-d');
     $date->setTimezone(new DateTimeZone('UTC'));
     $converted = $date->format('jS'); // "13th" (UTC)
     

3. Locale-Specific Parsing

   • Issue: Ordinal suffixes (e.g., jS) may vary by locale (e.g., "1st" vs. "1.").
   • Fix: Explicitly set the locale for DateTime or use setlocale():

     setlocale(LC_TIME, 'en_US.UTF-8');
     $converter->convert('2024-06-13', 'Y-m-d', 'jS'); // "13th" (English)
     

4. Edge Cases in Tokens

   • Issue: Custom tokens or ordinal suffixes may not handle edge cases (e.g., invalid dates).
   • Fix: Wrap logic in try-catch:

     $converter->addToken('weekday', fn(DateTime $date) => {
         try {
             return $date->format('l'); // e.g., "Monday"
         } catch (Exception $e) {
             return 'Invalid Date';
         }
     });
     

Debugging Tips

1. Inspect Tokens Use getFormat() to debug token extraction, including ordinals:

   print_r($converter->getFormat('jS M Y')); // ['jS', 'M', 'Y']
   

2. Log Conversions Add logging for troubleshooting ordinals:

   $converter->convert('2024-06-13', 'Y-m-d', 'jS', true); // Enable debug mode
   

3. Fallback to Carbon For complex cases, leverage Carbon’s parsing and formatting:

   $date = Carbon::createFromFormat('Y-m-d', '2024-06-13');
   $converted = $date->format('jS F Y'); // "13th June 2024"
   

Extension Points

1. Custom Token Registry Override the default tokens, including ordinals, by extending the Converter class:

   class CustomConverter extends Converter {
       public function __construct() {
           $this->addToken('customOrdinal', fn(DateTime $date) => 'CUSTOM ' . $date->format('jS'));
       }
   }
   

2. Integration with Laravel Helpers Create a global helper for ordinal conversions:

   if (!function_exists('convert_date')) {
       function convert_date(string $date, string $from, string $to): string {
           return app(Converter::class)->convert($date, $from, $to);
       }
   }
   

   Usage:

   convert_date('2024-06-13', 'Y-m-d', 'jS'); // "13th"
   

3. Service Provider Binding Bind the converter to Laravel’s container for dependency injection:

   // app/Providers/AppServiceProvider.php
   public function register() {
       $this->app->bind(Converter::class, fn() => new Converter());
   }
   

   Usage in controllers:

   public function __construct(private Converter $converter) {}
   

4. Ordinal-Specific Extensions Extend the package to support additional ordinal formats (e.g., dS for day-only):

   $converter->convert('2024-06-13', 'Y-m-d', 'dS'); // "13th"
   

   Or create a wrapper for common ordinal use cases:

   function