Gotime Laravel Package

Getting Started

Minimal Steps

1. Installation (updated for v1.0.1):

   composer require dcarbone/gotime:^1.0
   

   Requires PHP 8.1+ (compatible with Laravel 9+). Breaking: Removed dcarbone/gotime namespace alias; use DCarbone\Go\Time directly.

2. First Use Case (updated API):

   use DCarbone\Go\Time\Duration;
   
   // Parse a duration string (e.g., from API input)
   $duration = Duration::parse('1h30m');
   
   // Add to a DateTime (via DateInterval bridge)
   $dateTime = new \DateTime();
   $dateTime->add($duration->toDateInterval());
   
   // Output: "1h30m" (string cast)
   echo $duration->format(); // New method in v1.0.1
   

3. Key Entry Points (updated):

   • Duration::parse('5s') → Parse strings like "5s", "2h45m" (replaces Time::ParseDuration).
   • new Duration(5, 'second') → Construct from numeric values + unit (replaces Time\Duration constructor).
   • $duration->toDateInterval() → Convert to PHP’s DateInterval (replaces DateInterval()).
   • $duration->format() → New! Human-readable string output (e.g., "1h30m").

Implementation Patterns

Core Workflows

1. Duration Handling (updated)

• Parsing (new static method):

  $duration = Duration::parse('1.5h'); // 5400 seconds (1h30m)
  

• Arithmetic (new fluent methods):

  $total = Duration::parse('1h')->add(Duration::parse('30m'));
  

• Serialization (updated):

  $json = json_encode($duration->nanoseconds()); // 5400000000000
  $string = $duration->format(); // "1h30m" (new!)
  

2. Time Operations (new Time class)

• Current Time:

  use DCarbone\Go\Time\Time;
  $now = Time::now(); // Returns Time instance (replaces `Time::Now()`)
  

• Adding/Subtracting:

  $future = $now->add(Duration::parse('2h'));
  $past = $now->subtract(Duration::parse('30m'));
  

• Comparisons:

  $diff = $now->until($future); // Returns Duration
  

3. DateTime Integration (updated)

• Bridge to PHP’s DateTime:

  $dateTime = new \DateTime();
  $dateTime->add($duration->toDateInterval()); // Modifies in-place
  

• Fluent Chaining (new Time class):

  $result = Time::now()
      ->add(Duration::parse('1h'))
      ->subtract(Duration::parse('15m'));
  

4. API Contracts (updated)

• Request/Response:

  // Incoming request (e.g., "timeout": "5s")
  $timeout = Duration::parse(request('timeout'));
  
  // Outgoing response (e.g., "duration_nanos": 5000000000)
  return ['duration_nanos' => $timeout->nanoseconds()];
  

Laravel-Specific Patterns

1. Service Providers (updated)

Register facade for global access (optional):

// app/Providers/AppServiceProvider.php
use DCarbone\Go\Time\Facades\Duration;
use DCarbone\Go\Time\Facades\Time;

public function boot()
{
    if (! class_exists(Duration::class)) {
        \Facade\Ignition::warning('gotime facade not found. Install via composer.');
    }
}

2. Model Accessors/Mutators (updated)

Handle Duration fields in Eloquent:

// app/Models/Job.php
protected $casts = [
    'duration' => \DCarbone\Go\Time\Duration::class,
];

// Parse from DB (e.g., "1h")
public function getDurationAttribute($value) {
    return Duration::parse($value);
}

// Serialize to DB (e.g., "1h")
public function setDurationAttribute($value) {
    $this->attributes['duration'] = $value instanceof Duration
        ? $value->format()
        : $value;
}

3. Artisan Commands (updated)

Use gotime for scheduled tasks:

// app/Console/Commands/ProcessQueue.php
public function handle()
{
    $timeout = Duration::parse('10s');
    $this->processJobsUntil($timeout);
}

4. Middleware (updated)

Enforce time-based constraints:

// app/Http/Middleware/RateLimit.php
public function handle($request, Closure $next)
{
    $window = Duration::parse('1m');
    // ... rate limiting logic using $window
}

5. Testing (updated)

Assert durations in tests:

use DCarbone\Go\Time\Duration;

public function testDurationParsing()
{
    $duration = Duration::parse('1h30m');
    $this->assertEquals('1h30m', $duration->format());
    $this->assertEquals(5400, $duration->seconds());
}

6. New: Timezone Support

Explicitly set timezone on Time operations:

$time = Time::now()->inTimezone('UTC');
$future = $time->add(Duration::parse('1h'));

Gotchas and Tips

Pitfalls

1. Breaking Changes in v1.0.1

• Issue: Time::ParseDuration() and Time\Duration are removed. Use Duration::parse() and DCarbone\Go\Time\Duration instead.
• Fix: Update all imports and static calls:

  - use DCarbone\Go\Time;
  + use DCarbone\Go\Time\Duration;
  - $duration = Time::ParseDuration('1h');
  + $duration = Duration::parse('1h');
  

2. Floating-Point Precision (unchanged but critical)

• Issue: Duration::parse('0.05s') may return 0s due to internal conversion.
• Fix: Use whole numbers or milliseconds:

  $duration = Duration::parse('50ms'); // Safe
  

3. Timezone Ambiguity (updated)

• Issue: Time is timezone-aware but defaults to system timezone. Operations like add() use the Time instance’s timezone.
• Fix: Explicitly set timezone:

  $time = Time::now()->inTimezone('America/New_York');
  

4. JSON Serialization Quirks (updated)

• Issue: json_encode() requires explicit conversion to nanoseconds or use format() for strings.
• Fix:

  $json = json_encode($duration->nanoseconds()); // Integer
  $string = $duration->format(); // Human-readable
  

5. DateInterval Limitations (unchanged)

• Issue: Underlying DateInterval may not handle all edge cases (e.g., 24h + 1s).
• Fix: Validate durations:

  if ($duration->hours() > 24) {
      throw new \InvalidArgumentException('Duration too large');
  }
  

6. Deprecated Methods

• Issue: Time::Now(), Time\Duration, and DateInterval() are deprecated. Use Time::now(), Duration::parse(), and toDateInterval().
• Fix: Update codebase to use new methods (see changelog).

7. New: Immutable Duration

• Issue: Duration objects are now immutable. Methods like add() return a new Duration instead of modifying in-place.
• Fix: Chain methods or reassign:

  $newDuration = $duration->add(Duration::parse('1h')); // Returns new Duration
  

Debugging Tips