PHPackages                             geoffreyrose/useful-dates - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. geoffreyrose/useful-dates

ActiveLibrary[Utility & Helpers](/categories/utility)

geoffreyrose/useful-dates
=========================

Useful Dates - PHP + Laravel Facade

v1.1.0(2mo ago)275↓53.3%1MITPHPPHP ^8.4CI passing

Since Dec 11Pushed 1mo agoCompare

[ Source](https://github.com/geoffreyrose/useful-dates)[ Packagist](https://packagist.org/packages/geoffreyrose/useful-dates)[ GitHub Sponsors](https://github.com/geoffreyrose)[ RSS](/packages/geoffreyrose-useful-dates/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (7)Versions (5)Used By (1)

[![Latest Stable Version](https://camo.githubusercontent.com/9cb18cff8d52d81a272c6b6a1ac166e500e18ba079c007a4229f7a250d513aa1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f67656f6666726579726f73652f75736566756c2d64617465733f7374796c653d666c61742d737175617265)](https://packagist.org/packages/geoffreyrose/useful-dates)[![Test Status](https://camo.githubusercontent.com/51ab650e9c054a555c80ee47bc85a068ec786f974abf1483cd5f263add9e2ec9/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f67656f6666726579726f73652f75736566756c2d64617465732f74657374732e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265266c6162656c3d7465737473)](https://github.com/geoffreyrose/useful-dates/actions?query=branch%3Amain)[![Code Coverage](https://camo.githubusercontent.com/983fde19eb856b2e253d521688908a54e3b34b8b91b76664e9eeabca8ef08b93/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f67682f67656f6666726579726f73652f75736566756c2d64617465732f6d61696e3f7374796c653d666c61742d737175617265)](https://app.codecov.io/gh/geoffreyrose/useful-dates/branch/main)[![License](https://camo.githubusercontent.com/3a253def8d8ba1e999f0f0ff1f7a5aae95ccca96e463349a3589ab78544b5669/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f67656f6666726579726f73652f75736566756c2d64617465733f7374796c653d666c61742d737175617265)](https://github.com/geoffreyrose/useful-dates/blob/main/LICENSE)

Useful Dates: A PHP Holiday Date Package
========================================

[](#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](https://github.com/geoffreyrose/us-holidays).

Features
--------

[](#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
------------

[](#requirements)

- PHP 8.4+
- [Carbon](http://carbon.nesbot.com/)

Installation
------------

[](#installation)

```
composer require geoffreyrose/useful-dates
```

Quick Start
-----------

[](#quick-start)

```
use UsefulDates\UsefulDates;
use Carbon\Carbon;

$usefulDates = new UsefulDates();
$usefulDates->setDate(Carbon::now());

// Add a simple date
$usefulDates->addDate(name: "Patrick Star's Birthday", date: Carbon::createFromFormat('Y-m-d', '1999-08-17'));

// Get upcoming dates
$dates = $usefulDates->getUsefulDatesInDays(30);
```

### Laravel Facade

[](#laravel-facade)

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

```
use UsefulDates\Facades\UsefulDates;

$usefulDates = UsefulDates::setDate(Carbon::now());
```

---

Table of Contents
-----------------

[](#table-of-contents)

- [Creating Custom Dates](#creating-custom-dates)
- [Methods](#methods)
    - [Core Methods](#core-methods)
    - [Range & Navigation Methods](#range--navigation-methods)
    - [Business Day Methods](#business-day-methods)
- [UsefulDate Properties](#usefuldate-properties)
- [Extensions](#extensions)
- [Filtering](#filtering)
- [Development](#development)

---

Creating Custom Dates
---------------------

[](#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

[](#step-1-create-a-date-class)

Create a new class that extends [`UsefulDates\Abstracts\UsefulDateAbstract`](https://github.com/geoffreyrose/useful-dates/blob/main/src/UsefulDates/Abstracts/UsefulDateAbstract.php):

```