Recruiter\Clock 5.1.0

✨ New Features

• Native MongoDB support - New asMongoUTC() method directly returns MongoDB's native UTCDateTime objects
• Namespace reorganization - Core interfaces moved to Recruiter\Clock namespace for better organization

🛠️ Improvements

• Direct MongoDB integration - Added MongoUTCClock interface and PsrMongoUTCClock wrapper for seamless MongoDB BSON\UTCDateTime conversion
• Better namespace structure - Relocated core interfaces (Clock, UTCClock, MicrotimeClock, StopWatch) to dedicated namespaces

🔧 API Changes

New MongoDB Clock Access

All clock implementations now provide direct MongoDB UTCDateTime conversion:

use Recruiter\Clock\SystemClock;

$clock = new SystemClock();

// NEW: Direct MongoDB UTCDateTime conversion
$mongoUTC = $clock->asMongoUTC(); // Returns MongoUTCClock
$bsonDateTime = $mongoUTC->now(); // Returns MongoDB\BSON\UTCDateTime

// Existing specialized clocks still available
$utcClock = $clock->asUTC(); // Custom UTCDateTime for advanced operations
$microtimeClock = $clock->asMicrotime(); // Float timestamp operations

This addition complements the existing asUTC() method, providing native MongoDB types when needed while keeping the powerful custom UTCDateTime class for advanced operations.

📦 Dependencies

No dependency changes - continues to use symfony/clock: ^7.3

Full Changelog

v5.0.0...v5.1.0

Recruiter\Clock 5.0.0

🚀 Breaking Changes

• BREAKING: Replaced psr/clock dependency with Symfony Clock (symfony/clock: ^7.3)
• BREAKING: Removed deprecated current() method from Clock interface - use now() instead
• BREAKING: Major refactoring of clock implementations to integrate with Symfony Clock framework
• BREAKING: Replaced integer constants with type-safe enums:
  • UTCDateTimeRange::LESS_THAN → ComparisonOperator::LessThan
  • UTCDateTimeRange::LESS_THAN_EQUALS → ComparisonOperator::LessThanOrEquals
  • UTCDateTimeRange::ASCENDING → Direction::Ascending
  • UTCDateTimeRange::DESCENDING → Direction::Descending

✨ New Features

• Symfony Clock Integration - All clock implementations now support Symfony Clock methods:
  • sleep(float|int $seconds) - Sleep functionality with time advancement for test clocks
  • withTimeZone(\DateTimeZone|string $timezone) - Timezone-aware clock creation
• Enhanced PSR Clock Support - New PsrMicrotimeClock adapter for existing PSR Clock implementations
• Docker Development Improvements:
  • XDebug support with dedicated dev Docker target
  • Test coverage reporting with make test-coverage command
  • Enhanced development workflow with better container setup

🛠️ Improvements

• Enhanced Type Safety with new enum-based APIs replacing magic constants
• Comprehensive Test Suite - Added extensive test coverage for all clock implementations
• Streamlined Development Workflow:
  • Simplified Docker configuration with multi-stage builds
  • Better Makefile with coverage support
  • Improved CI/CD with dependency caching
• Code Modernization:
  • Simplified constructor logic in ProgressiveClock
  • Enhanced FixedClock to prevent mutation from external DateTime objects
  • Better separation of concerns with new trait SymfonySupport

📦 Dependencies

• Replaced psr/clock: ^1.0 with symfony/clock: ^7.3
• Enhanced development dependencies for better testing and code quality

🔧 API Changes

Core Clock Interface

All clock implementations now extend Symfony's ClockInterface and provide unified access to specialized clock types:

use Recruiter\Clock\SystemClock;

$clock = new SystemClock();

// Primary interface - Symfony Clock compliant
$dateTimeImmutable = $clock->now(); // Returns DateTimeImmutable

// Access specialized clock implementations
$utcClock = $clock->asUTC(); // Returns UTCClock for MongoDB integration
$microtimeClock = $clock->asMicrotime(); // Returns MicrotimeClock for float timestamps
$stopWatch = $clock->stopWatch(); // Returns StopWatch for timing operations

// NEW: Symfony Clock methods
$clock->sleep(1.5); // Sleep for 1.5 seconds (advances test clocks)
$utcClock = $clock->withTimeZone('UTC'); // Create timezone-aware variant

Available Clock Implementations

• SystemClock - Production clock using system time (wraps Symfony NativeClock)
• ManualClock - Test clock with manual time control (wraps Symfony MockClock)
• SettableClock - Switchable clock that can override any base clock with fixed time
• ProgressiveClock - Auto-advancing clock that increments on each call
• DelayedClock - Clock with configurable delay offset

Automatic Clock Wrapping

All clock implementations automatically provide access to specialized interfaces through the AbstractClock base class:

• asUTC() → PsrUTCClock - Wraps any clock for custom UTCDateTime operations (battle-tested for MongoDB-heavy apps)
• asMicrotime() → PsrMicrotimeClock - Wraps any clock for float timestamp operations
• stopWatch() → ClockStopWatch - Wraps any clock for elapsed time measurements

This ensures consistent access to specialized datetime handling, microtime operations, and timing functionality across all clock implementations.

Enum Migration Example:

// Before v5.0.0
if ($range->direction() === UTCDateTimeRange::ASCENDING) { ... }
if ($range->toOperator() === UTCDateTimeRange::LESS_THAN) { ... }

// v5.0.0+
if ($range->direction() === Direction::Ascending) { ... }
if ($range->toOperator() === ComparisonOperator::LessThan) { ... }

🔄 Migration Guide

1. Update dependencies - Replace psr/clock with symfony/clock: ^7.3
2. Replace deprecated current() calls - Update all $clock->current() to $clock->now()
3. Update enum usage - Replace integer constants with new enum values:
   • Import use Recruiter\DateTime\{ComparisonOperator, Direction};
   • Update comparisons to use enum values instead of class constants
4. Optional: Leverage new Symfony Clock features like sleep() and withTimeZone()

⚠️ Breaking Change: The deprecated current() method has been removed. All code must use now() instead.

Full Changelog

v4.2.0...v5.0.0

Recruiter\Clock v4.2.0

✨ New Features

• Deprecation warning - Added @deprecated annotation to Clock::current() method, recommending PSR-20's now() method
• Improved GitHub Actions - Enhanced CI workflow with better Docker setup and dependency caching

🛠️ Improvements

• Simplified Docker setup - Consolidated Docker configuration with single-stage build
• Streamlined Makefile - Removed PHPStan and Rector commands, focusing on core development workflow
• Code modernization - Updated type hints and removed unnecessary complexity across the codebase
• Better CI performance - Added Composer cache and optimized build process
• Fixed UTCDateTime::toWeek() - Now correctly returns ISO week format (o-\WW) following the ISO 8601 standard

🔧 API Changes

The Clock::current() method is now deprecated in favor of the PSR-20 standard now() method:

use Recruiter\Clock\SystemClock;

$clock = new SystemClock();

// Deprecated (still works but not recommended)
$dateTime = $clock->current(); // Returns DateTime

// Recommended (PSR-20 standard)
$dateTimeImmutable = $clock->now(); // Returns DateTimeImmutable

This change encourages migration to the PSR-20 standard while maintaining full backward compatibility.

🔄 Migration Notes

• Update usages of current() to now() when possible
• No breaking changes - existing code continues to work
• The PSR-20 now() method returns DateTimeImmutable instead of DateTime

Full Changelog

v4.1.0...v4.2.0

Recruiter\Clock 4.1.0

✨ New Features

• PSR-20 Clock compatibility - All clock implementations now support the PSR-20 ClockInterface
• GitHub Actions CI - Added automated testing workflow with PHPUnit
• Code formatting - Added PHP-CS-Fixer configuration and make fix-cs command

🛠️ Improvements

• Enhanced type safety with declare(strict_types=1) across all files
• Improved code formatting and consistency
• Added PSR Clock dependency (psr/clock: ^1.0)
• Better development workflow with automated code formatting

📦 Dependencies

• Added psr/clock: ^1.0 for PSR-20 compatibility
• Added friendsofphp/php-cs-fixer: ^3.85 for code formatting

🔧 API Changes

All existing clock classes now implement both the original Recruiter\Clock interface and PSR-20's ClockInterface, providing a now() method that returns DateTimeImmutable:

use Recruiter\Clock\SystemClock;

$clock = new SystemClock();

// Original interface (unchanged)
$dateTime = $clock->current(); // Returns DateTime

// PSR-20 interface (new)
$dateTimeImmutable = $clock->now(); // Returns DateTimeImmutable

This is fully backward compatible - existing code continues to work unchanged while gaining PSR-20 compatibility.

Full Changelog

v4.0.0...v4.1.0

Recruiter\Clock 4.0.0

🚀 Breaking Changes

• BREAKING: Minimum PHP version upgraded from 7.1 to 8.4
• BREAKING: MongoDB extension requirement upgraded from >=1.1 to >=1.15
• BREAKING: Dropped support for legacy ext-mongo (including alcaeus/mongo-php-adapter)

✨ New Features

• Added strict typing throughout the codebase
• Enhanced microsecond precision handling in UTCDateTime
• Docker support with development environment
• Makefile with common development tasks

🛠️ Improvements

• Upgraded to PHPUnit 12.3
• Added Rector for code modernization
• Migrated to PSR-4 autoloading
• Enhanced type safety with return type declarations
• Converted classes to use readonly properties where applicable

🔄 Migration Guide

1. Update PHP to 8.4+
2. Ensure MongoDB extension >=1.15 (no more ext-mongo support)
3. Update dependencies - remove any alcaeus/mongo-php-adapter references

The API remains largely unchanged - existing code should work with minimal modifications after updating PHP and MongoDB extension versions.