Clock Bundle Laravel Package

Product Decisions This Supports

• Consistent Time Handling in Tests: Enables deterministic unit/integration tests for time-sensitive logic (e.g., rate limiting, token expiration, scheduled tasks) by decoupling from system clock.
• Request-Scoped Time Isolation: Simplifies debugging and reproducibility by ensuring "now" remains static per request, eliminating flakiness in time-dependent workflows.
• Code Clarity: Replaces verbose manual time calculations (e.g., Unix timestamps) with expressive helper methods (e.g., hasElapsed(), isExpired()), improving maintainability.
• Legacy System Modernization: Justifies incremental adoption of time-aware features in older PHP/Symfony apps without full refactoring.
• Build vs. Buy: Favors buy for small teams lacking time to build a custom solution; build only if needing advanced features (e.g., time zones, custom clock providers).

When to Consider This Package

• Avoid if:
  • Your app requires time zones or custom clock providers (e.g., frozen time for replay testing).
  • You’re using PHP 8.1+ and prefer modern alternatives like DateTimeImmutable or libraries like spatie/temporal.
  • The team lacks PHP/Symfony expertise to evaluate unmaintained code.
  • You need active maintenance (e.g., security patches, bug fixes).
• Consider if:
  • You’re maintaining a Symfony 4/5 app with time-sensitive logic (e.g., auth, payments).
  • Tests fail intermittently due to system clock drift.
  • You want to reduce test flakiness without mocking DateTime everywhere.
  • The team prioritizes simplicity over cutting-edge features.

How to Pitch It (Stakeholders)

For Executives: "This package lets us write reliable, testable time-dependent logic (e.g., login retries, token validation) without flaky tests or complex mocking. It’s a low-risk, high-reward fix for a common pain point in PHP apps—especially for legacy systems. Since it’s unmaintained, we’d need to vet it, but the trade-off is minimal dev time vs. long-term stability gains."

For Engineering: *"The bundle provides a request-scoped clock that:

• Freezes time per request for consistent tests.
• Replaces manual timestamp math with clean helpers (e.g., hasElapsed()).
• Works out-of-the-box with Symfony’s DI. Downside: Unmaintained, but we can fork it or use it as a reference. Alternatives like spatie/temporal are more modern but overkill for basic needs. Recommend a trial in 1–2 critical modules first."*