Effectra\Clock

Effectra\Clock is a lightweight PHP utility class that implements Psr\Clock\ClockInterface. It provides common date and time helpers for applications, including formatting, date arithmetic, calendar checks, timezone management, and basic Hijri calendar support.

Features

• Implements the Psr\Clock\ClockInterface interface
• Returns the current time as a DateTimeImmutable instance
• Returns the current Unix timestamp as an integer
• Formats current date and time in custom PHP date formats
• Supports date arithmetic with add() and sub()
• Calculates date differences with diff()
• Provides Gregorian/Hijri conversion helpers
• Exposes timezone and day-boundary utilities

Usage

use Effectra\Clock\Clock;

$clock = new Clock();

$currentDateTime = $clock->now();
$currentTimestamp = $clock->timestamp();
$formatted = $clock->format('Y-m-d H:i:s');

Public methods

now(): \DateTimeImmutable

Returns the current date and time as a DateTimeImmutable object.

timestamp(): int

Returns the current Unix timestamp as an integer.

format(string $format = 'Y-m-d H:i:s'): string

Formats the current date and time using the provided PHP date format string.

date(string $format = 'Y-m-d'): string

Returns the current date only, formatted with the supplied format.

time(string $format = 'H:i:s'): string

Returns the current time only, formatted with the supplied format.

dayOfWeek(bool $short = false): string

Returns the current day of the week. If $short is true, it returns the short form such as Mon; otherwise it returns the full name such as Monday.

month(bool $short = false): string

Returns the current month name. If $short is true, it returns the abbreviated month name.

year(): int

Returns the current year as an integer.

isLeapYear(): bool

Checks whether the current year is a leap year.

daysInMonth(): int

Returns the number of days in the current month.

toTimestamp(string $dateTime): int

Converts a date string into a Unix timestamp.

add(string $interval, int $value = 1): \DateTimeImmutable

Adds a time interval to the current time. Example: add('days', 2).

sub(string $interval, int $value = 1): \DateTimeImmutable

Subtracts a time interval from the current time.

diff(string $date1, string $date2, string $format = '%a days'): string

Calculates the difference between two dates and formats it using the supplied DateInterval format string.

toHijri(?int $year = null, ?int $month = null, ?int $day = null, bool $arabicNames = true): array

Converts a Gregorian date to Hijri date data. If no year, month, or day is provided, it uses the current date. The result includes the Hijri year, month, day, month name, day of year, leap-year flag, and formatted strings.

hijriNow(bool $arabicNames = true): array

Returns the current Hijri date information using the same structure as toHijri().

hijriFormat(string $format = 'd F Y', bool $arabicNames = true): string

Formats the current Hijri date using a simplified token format such as d, j, F, M, m, n, Y, and y.

timezoneInfo(): array

Returns information about the current timezone, including the timezone name, offset in seconds, offset in hours, and whether daylight saving time is active.

setTimezone(string $timezone): bool

Sets the default timezone and returns whether the operation succeeded.

microtime(): float

Returns the current timestamp with microseconds precision.

formatTimestamp(?int $timestamp = null, string $format = 'Y-m-d H:i:s'): string

Formats a Unix timestamp into a readable string. If no timestamp is provided, the current timestamp is used.

isWeekend(?string $date = null): bool

Checks whether the provided date is a weekend. If no date is given, it uses the current date.

dayBoundaries(?string $date = null): array

Returns the start and end of the day for a given date, along with their Unix timestamps.

Example

use Effectra\Clock\Clock;

$clock = new Clock();

echo $clock->now()->format('Y-m-d H:i:s');
echo $clock->timestamp();
echo $clock->hijriFormat('d F Y');

Contributing

Contributions are welcome. If you find a bug or want to suggest an improvement, feel free to open an issue or submit a pull request.

License

This package is open-source and available under the MIT License. "# clock"