Clock Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require alexeyshockov/clock
   

   Add the service provider to config/app.php (if not auto-discovered):

   'providers' => [
       // ...
       Alexeyshockov\Clock\ClockServiceProvider::class,
   ],
   

2. Basic Usage: Inject the Clock facade or service into your controller/service:

   use Alexeyshockov\Clock\Facades\Clock;
   
   // Get current time
   $now = Clock::now();
   
   // Format time
   $formatted = Clock::now()->format('Y-m-d H:i:s');
   

3. First Use Case: Replace Carbon or DateTime instantiations with Clock::now() for consistency. Example:

   // Before
   $dueDate = Carbon::now()->addDays(7);
   
   // After
   $dueDate = Clock::now()->addDays(7);
   

Implementation Patterns

Core Workflows

1. Time Zone Handling: Use Clock::setTimezone('America/New_York') globally or per-operation:

   $nyTime = Clock::now('America/New_York');
   

2. Mocking Time for Testing: Override time in tests:

   Clock::shouldReceive('now')->andReturn(Carbon::create(2023, 1, 1));
   

3. Date Arithmetic: Chain methods like addHours(), subtractMinutes(), or startOfDay():

   $nextWeek = Clock::now()->startOfWeek()->addWeek();
   

4. Integration with Eloquent: Use Clock::now() in model timestamps or queries:

   $user = User::create([
       'name' => 'John',
       'created_at' => Clock::now(),
   ]);
   

5. Custom Time Providers: Extend functionality by creating a custom time provider:

   Clock::extend('custom', function () {
       return new CustomTimeProvider();
   });
   

Gotchas and Tips

Pitfalls

1. Archived Package:

   • The package is archived; evaluate if its functionality is critical or if alternatives (e.g., nesbot/carbon) are viable.
   • Monitor for breaking changes if used long-term.

2. Time Zone Conflicts:

   • Ensure time zones are explicitly set to avoid unexpected behavior in multi-region apps.
   • Use Clock::getTimezone() to debug current timezone.

3. Carbon Dependency:

   • Under the hood, Clock uses Carbon. Be mindful of Carbon-specific quirks (e.g., createFromFormat edge cases).

4. Service Provider Auto-Discovery:

   • If not auto-discovered, manually register the provider in config/app.php to avoid Clock not being available.

Debugging Tips

1. Log Current Time:

   \Log::debug('Current time:', ['time' => Clock::now()->toDateTimeString()]);
   

2. Check Time Providers: List all registered providers to debug overrides:

   dd(Clock::providers());
   

3. Verify Time Manipulation: Use toDateTimeString() for debugging formatted output:

   $time = Clock::now()->addHours(5);
   dd($time->toDateTimeString());
   

Extension Points

1. Custom Time Logic: Override Clock::now() for app-specific logic (e.g., business hours):

   Clock::macro('businessHours', function () {
       $time = Clock::now();
       return $time->hour >= 9 && $time->hour < 17 ? $time : null;
   });
   

2. Event-Based Time Adjustments: Use Laravel events to dynamically adjust time (e.g., daylight saving):

   event(new AdjustTimeEvent());
   // In listener:
   Clock::setTimezone(request()->ip() ? 'UTC' : 'Europe/London');
   

3. Fallback Providers: Implement a fallback provider for offline scenarios:

   Clock::extend('offline', function () {
       return new StaticTimeProvider(Carbon::now());
   });
   Clock::setProvider('offline');