Download the PHP package geoffreyrose/useful-dates without Composer

Useful Dates: A PHP Holiday Date Package

A simple and elegant PHP library for working with commonly used or desired dates in your applications. UsefulDates helps you quickly identify and retrieve important dates like holidays, birthdays, paydays, and other significant calendar events.

This is an evolution of geoffreyrose/us-holidays.

Features

• Flexible Date Definitions - Add your own dates with simple or complex logic
• Extensions Support - Create reusable date collections for country-specific holidays, birthdays, or any custom dates
• Business Day Helpers - Built-in methods for working with business days
• Filtering - Filter dates by custom properties with various operators
• Laravel Integration - Works seamlessly with Laravel via auto-discovered Facade

On its own, UsefulDates comes with no predefined dates. It provides a clean base that you can extend with your own dates and methods.

Requirements

• PHP 8.4+
• Carbon

Installation

Quick Start

Laravel Facade

Laravel uses Package Auto-Discovery, so no manual registration is needed:

Table of Contents

• Creating Custom Dates
• Methods
  • Core Methods
  • Range & Navigation Methods
  • Business Day Methods
• UsefulDate Properties
• Extensions
• Filtering
• Development

Creating Custom Dates

You can create custom date definitions by extending UsefulDateAbstract. Each custom date class must implement the date() method which returns the date for the current context year.

Important: The date() method should always return dates in UTC time.

Step 1: Create a Date Class

Create a new class that extends UsefulDates\Abstracts\UsefulDateAbstract:

Tip: Carbon::createFromFormat() is faster than Carbon::create() in my benchmarks.

Step 2: Register Your Date

Use the add() method to register your custom date class:

Methods

Core Methods

setDate(Carbon|DateTime|string $date): self

Set the working date/time context (normalized to UTC). Accepts Carbon, DateTime, or a string parsable by Carbon.

add(string $dateClass): self

Register a UsefulDate by class name. The class must extend UsefulDateAbstract.

addDate(string $name, Carbon $date, ...): self

Add a simple UsefulDate without creating a class. Creates an internal definition that repeats according to the provided options.

Parameters:

• $name - Human-friendly name for the date
• $date - Prototype date (month/day are used for each occurrence)
• $isRepeated - Whether the date repeats (default: true)
• $repeatFrequency - RepeatFrequency::YEARLY, MONTHLY, NONE, or CUSTOM (default: YEARLY)
• $startYear - First year the date is considered (default: year from $date)

addExtension(string $extensionClass, mixed $options = null): self

Register an extension (must extend UsefulDatesExtensionAbstract). Adds its useful dates and any custom methods exposed by the extension.

isUsefulDate(?Carbon $date = null): bool

Returns true if any registered UsefulDate matches the given date (defaults to the current context date).

getUsefulDate(?Carbon $date = null, ?array $filters = null): array

Returns a list of matching UsefulDate objects for the given date (defaults to the current context date).

See the Filtering section for filter options.

Range & Navigation Methods

getUsefulDatesInDays(int $days, ?Carbon $startDate = null, ?array $filters = null): array

Get all matching UsefulDates occurring from $startDate (default: current context) through $startDate + $days.

getUsefulDatesInYears(int $years, ?array $filters = null): array

Get all useful dates within the next N years from the current context date.

getNextUsefulDates(int $number = 1, ?array $filters = null): array

Get the next N useful dates after the current context date.

getPreviousUsefulDates(int $number = 1, ?array $filters = null): array

Get the previous N useful dates before the current context date.

getUsefulDatesByYear(?int $year = null, ?array $filters = null): array

Get all useful dates within a given calendar year (defaults to current context year).

Business Day Methods

Default business days are Monday–Friday ([1, 2, 3, 4, 5]). Days use Carbon's constants where 0 = Sunday through 6 = Saturday.

isStandardBusinessDays(): bool

Returns true if the configured business days are Monday–Friday.

setBusinessDays(array $days): self

Define which days of week are business days (0=Sun..6=Sat). Throws InvalidDayException for invalid values.

getBusinessDays(): array

Get the configured business days array.

isBusinessDay(?Carbon $date = null): bool

Check if the given date (or current context date) is a business day.

nextBusinessDay(): ?Carbon

Get the next business day after the current context date.

prevBusinessDay(): ?Carbon

Get the previous business day before the current context date.

todayOrPreviousBusinessDay(): Carbon

Returns today if it is a business day, otherwise the previous business day.

todayOrNextBusinessDay(): Carbon

Returns today if it is a business day, otherwise the next business day.

UsefulDate Properties

When creating custom date classes by extending UsefulDateAbstract, you have access to these properties:

You may also add any additonal properties to your custom dates as needed

Instance Methods

These methods are available on each UsefulDate instance:

usefulDate(): ?Carbon

Returns the date if it should be considered for the current context (applies repeat frequency and start/end rules), otherwise null.

daysAway(): int

Returns the number of days from the current context to this date. Positive = future, negative = past, 0 = today.

Complete Example

Extensions

Extensions allow you to bundle groups of UsefulDates together, optionally with custom methods.

Available Extensions

Using an Extension

Creating an Extension

Create a class that extends UsefulDatesExtensionAbstract:

Using the extension with custom methods:

IDE Support

For better IDE autocompletion with extension methods, create a wrapper class:

Note: The @mixin annotation is what helps IDEs understand the extension methods.

Filtering

Filter useful dates by custom properties using the $filters parameter available on most retrieval methods.

Filter Structure

Each filter is an array with three keys:

Example

Multiple filters are combined with AND logic (all conditions must match).

Development

Linting

Static Analysis

Testing

License

MIT License. See LICENSE for details.