Php Date Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require assoconnect/php-date
   

   • No additional configuration is required for basic usage.

2. First Use Case: Formatting Dates

   use Assoconnect\Date\Date;
   
   $date = new Date('2023-12-25');
   echo $date->format('Y-m-d H:i:s'); // Output: "2023-12-25 00:00:00"
   

3. Key Classes to Explore

   • Date: Core class for date manipulation (similar to Carbon but lightweight).
   • DateTime: Extends Date with timezone support.
   • DateInterval: Handles date arithmetic (e.g., adding/subtracting days).

Implementation Patterns

1. Date Creation & Parsing

• From Strings

  $date = new Date('2023-12-25 14:30:00');
  $date = new Date('next Monday'); // Relative parsing
  

• From Unix Timestamps

  $date = new Date(strtotime('now'));
  

• From Arrays

  $date = new Date(['year' => 2023, 'month' => 12, 'day' => 25]);
  

2. Common Operations

• Arithmetic

  $date->addDays(5);          // Add 5 days
  $date->subtractMonths(2);   // Subtract 2 months
  $date->addInterval('P1Y2M'); // ISO-8601 interval
  

• Comparison

  if ($date1->isAfter($date2)) { ... }
  if ($date1->equals($date2)) { ... }
  

• Formatting

  $date->format('jS F Y'); // "25th December 2023"
  $date->toRfc822();       // "Mon, 25 Dec 2023 00:00:00 +0000"
  

3. Timezone Handling (DateTime Class)

$dateTime = new \Assoconnect\Date\DateTime('now', 'America/New_York');
$dateTime->setTimezone('Europe/London');

4. Integration with Laravel

• Request Validation

  use Illuminate\Support\Facades\Validator;
  
  $validator = Validator::make($request->all(), [
      'event_date' => 'required|date_format:Y-m-d|after:today',
  ]);
  

• Carbon Compatibility (Partial)

  $date = new Date('2023-12-25');
  $carbon = $date->toCarbon(); // If the package supports conversion
  

5. Query Builder Extensions

• Custom Where Clauses

  $users = User::whereDate('created_at', '>=', new Date('last month'))->get();
  

Gotchas and Tips

Pitfalls

1. No Carbon Compatibility by Default

   • Unlike Carbon, this package does not implement all Carbon methods. Check the docs for supported methods.
   • Workaround: Use toCarbon() if available or manually convert:

     $carbon = Carbon\Carbon::createFromFormat('Y-m-d', $date->format('Y-m-d'));
     

2. Relative Parsing Limitations

   • Strings like "next Monday" may not work as expected in all locales. Test edge cases:

     $date = new Date('next Monday +2 weeks'); // May fail silently
     

3. Timezone Ambiguity

   • Date (non-DateTime) assumes UTC. Always use DateTime for timezone-aware operations:

     $date = new Date('now'); // UTC
     $dateTime = new \Assoconnect\Date\DateTime('now', 'UTC'); // Explicit
     

4. Immutable Operations

   • Methods like addDays() return a new instance. Chain carefully:

     $newDate = $date->addDays(5)->subtractHours(2); // Correct
     $date->addDays(5)->subtractHours(2); // Original $date unchanged
     

Debugging Tips

• Check Input Parsing If a date string fails to parse, use:

  try {
      $date = new Date($invalidString);
  } catch (\InvalidArgumentException $e) {
      // Handle error
  }
  

• Log Formatted Output

  \Log::debug('Date value:', ['raw' => $date->getTimestamp(), 'formatted' => $date->format('Y-m-d H:i')]);
  

Extension Points

1. Custom Formatters Override the format() method or create a decorator:

   class CustomDate extends Date {
       public function customFormat() {
           return $this->format('l, F jS');
       }
   }
   

2. Add Helper Methods Extend the class for domain-specific logic:

   class EventDate extends Date {
       public function isWithinNextWeek() {
           return $this->isAfter('now') && $this->isBefore('+7 days');
       }
   }
   

3. Integration with Laravel Services Bind the package to the container in AppServiceProvider:

   $this->app->bind('date', function () {
       return new \Assoconnect\Date\Date();
   });
   

Performance Notes

• Avoid Over-Usage in Loops Creating new Date/DateTime objects in tight loops can be expensive. Reuse instances where possible:

  $baseDate = new Date('now');
  foreach ($items as $item) {
      $itemDate = clone $baseDate; // Cheaper than recreating
      // ...
  }
  

• Use getTimestamp() for Comparisons Faster than reformatting for comparisons:

  if ($date1->getTimestamp() > $date2->getTimestamp()) { ... }