README

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"

effectra / clock

Maintainers

Package info

Statistics

Security