Gotime Laravel Package

Product Decisions This Supports

• Standardized Time Handling in Polyglot Systems: Enables consistent duration parsing/serialization between Go and PHP services, reducing serialization overhead and API contract complexity (e.g., 5s → 5000000000 nanos). Critical for microservices exchanging time intervals (e.g., job delays, rate limits).
• Precision for Financial/Audit Logs: Replaces imprecise DateInterval with nanosecond-backed durations, ensuring accurate logging of transaction latencies (e.g., "payment processed in 123ms").
• Developer Onboarding for Go Teams: Accelerates ramp-up for engineers transitioning from Go by leveraging familiar APIs (e.g., Time::Now().Add(Duration::Parse('1h'))), reducing context-switching costs.
• Roadmap for Legacy Code: Justifies phasing out ad-hoc DateInterval usage in favor of gotime::Duration for new features (e.g., scheduling, time-based validations).
• Build vs. Buy Decision: Avoids reinventing time utilities; offers 80% Go parity with minimal maintenance (MIT license, active releases). Justifies investment over custom solutions for teams prioritizing velocity over innovation.

When to Consider This Package

• Adopt if:

  • Your team uses Go and PHP in tandem and needs to exchange time intervals without manual conversion logic.
  • You’re building precision-critical systems (e.g., trading platforms, audit trails) where DateInterval’s microsecond gaps are unacceptable.
  • Your developers are familiar with Go’s time package and want to reduce cognitive load when switching to PHP.
  • You’re starting a new project or feature and can avoid Carbon dependency bloat.
  • Your stack is PHP 8.1+ and you’re open to a lightweight, non-opinionated time library.

• Avoid if:

  • Your team heavily relies on Carbon for its ecosystem (e.g., CarbonInterval, CarbonPeriod, Laravel integrations). The dual-maintenance cost may outweigh benefits.
  • You need sub-millisecond precision beyond PHP’s DateTime limits (this package uses nanoseconds internally but delegates arithmetic to DateTime).
  • Your project targets PHP <8.1 (compatibility requirement).
  • You require timezone-aware duration parsing (e.g., "parse 5s in UTC but apply to a local timezone"). This package treats durations as timezone-agnostic.
  • Your use case is heavily event-based (e.g., cron jobs, recurring tasks). Consider spatie/schedule or Laravel’s built-in scheduler instead.

• Look Elsewhere if:

  • You need advanced calendar math (e.g., "add 1 business month"). Use spatie/calendar or Carbon’s modify().
  • Your workflows are performance-sensitive (e.g., high-frequency trading). This package adds a thin abstraction layer over DateTime, which may introduce overhead.
  • You prioritize Laravel-specific features (e.g., Eloquent timestamps, Carbon facades). This package is framework-agnostic.

How to Pitch It (Stakeholders)

For Executives: "This package lets us write time-sensitive logic in PHP as cleanly as Go—critical for our [X Initiative] where we’re integrating Go and PHP microservices. For example, instead of manually calculating (60 * 60 * 1000) for milliseconds, we’ll parse durations like 30m or 2.5h in a single line, reducing bugs in scheduling and payment workflows. It’s a low-risk upgrade (MIT license, minimal dependencies) that aligns with our goal to [reduce technical debt/improve developer velocity]. The nanosecond precision also ensures we meet compliance requirements for audit logs in [Y Regulation]."

For Engineers: *"Gotime solves three key pain points:

1. Duration Parsing: No more DateInterval::createFromDateString('5 seconds')—just Duration::Parse('5s').
2. Go-PHP Sync: If you’ve used Go’s time package, this feels familiar (e.g., Time::Now().Add(Duration::Parse('1h'))).
3. Precision: Nanosecond backing ensures we don’t lose accuracy in financial/audit logs.

Tradeoffs:

• It’s not a drop-in for Carbon, but the learning curve is under 5 minutes for teams already using Go.
• The Time class is in beta, so we’d avoid it for now and focus on Duration.
• We’d need to manually bridge it with Carbon for timezone-aware operations.

Proposal: Let’s pilot it in [Z Service] where we’re hitting time-parsing edge cases. If successful, we can phase it into new features and gradually replace DateInterval usages."*

For Product Managers: *"This package enables us to:

• Ship faster: Reduce time spent debugging time-related bugs in microservices.
• Scale cleaner: Standardize time handling across languages, making it easier to add new services.
• Meet compliance: Ensure audit logs capture precise timestamps for [Y Requirement].

Example: For our [Payment Processing] feature, we’d replace:

// Before (error-prone)
$delay = DateInterval::createFromDateString('1 minute');

with:

// After (explicit, precise)
$delay = Time::ParseDuration('1m')->DateInterval();

This reduces ambiguity and aligns with our Go backend’s time handling."*