README

A lightweight PHP utility class that returns the season from a given date. Supports meteorological and astronomical season calculations, northern and southern hemispheres, and custom season names for translations.

Installation

composer require jaybizzle/php-seasons

Quick Start

use Jaybizzle\Seasons;

// Get the current season
$season = new Seasons;
$season->season(); // e.g. "Spring"

// Get season for a specific date
$season->season('1st June'); // "Summer"

// Static convenience methods
Seasons::now();          // e.g. "Spring"
Seasons::for('1st June'); // "Summer"

Season Calculation Methods

By default, seasons are calculated using meteorological boundaries based on whole calendar months:

Astronomical Seasons

You can switch to astronomical season boundaries, which use approximate equinox and solstice dates:

$season = new Seasons;

$season->season('March 19');                // "Winter" (meteorological: March = Spring)
$season->astronomical()->season('March 19'); // "Winter" (astronomical: before equinox)
$season->astronomical()->season('March 21'); // "Spring" (astronomical: after equinox)

The astronomical calculation adjusts automatically for leap years.

Southern Hemisphere

Seasons in the southern hemisphere are reversed. Use the southern() method to get the correct season:

$season = new Seasons;

$season->season('July');              // "Summer"
$season->southern()->season('July');  // "Winter"

This works with astronomical mode too:

$season->astronomical()->southern()->season('March 25'); // "Autumn"

Immutable Fluent API

The astronomical() and southern() methods return a new instance, leaving the original unchanged. This means you can safely reuse the same base instance:

$season = new Seasons;

$northern = $season->season('July');              // "Summer"
$southern = $season->southern()->season('July');   // "Winter"
$original = $season->season('July');               // Still "Summer"

Month Ranges

Get the month numbers that belong to a given season:

$season = new Seasons;

$season->monthRange('Winter'); // [12, 1, 2]
$season->monthRange('Summer'); // [6, 7, 8]

// Southern hemisphere month ranges
$season->southern()->monthRange('Summer'); // [12, 1, 2]

Translations

Pass an array of four season names to the constructor in the order: winter, spring, summer, autumn. All output will use your custom names:

// French
$season = new Seasons(['Hiver', 'Printemps', 'Été', 'Automne']);
$season->season('June');        // "Été"
$season->season('January');     // "Hiver"
$season->monthRange('Été');     // [6, 7, 8]

// German
$season = new Seasons(['Winter', 'Frühling', 'Sommer', 'Herbst']);
$season->season('October');     // "Herbst"

// Japanese
$season = new Seasons(['冬', '春', '夏', '秋']);
$season->season('April');       // "春"

Translations work with all features including southern(), astronomical(), and monthRange():

$french = new Seasons(['Hiver', 'Printemps', 'Été', 'Automne']);
$french->southern()->season('June');                // "Hiver"
$french->astronomical()->season('March 21');        // "Printemps"

The static methods also accept translations:

Seasons::for('June', ['Hiver', 'Printemps', 'Été', 'Automne']); // "Été"
Seasons::now(['Hiver', 'Printemps', 'Été', 'Automne']);          // e.g. "Printemps"

Date Formats

Any date string parsable by PHP's strtotime() is accepted:

$season = new Seasons;

$season->season('June');               // "Summer"
$season->season('1st October 2016');   // "Autumn"
$season->season('2024-12-25');         // "Winter"
$season->season('next Friday');        // depends on current date

An Exception is thrown if the date string cannot be parsed.

API Reference

Constants

Seasons::SEASON_WINTER // "Winter"
Seasons::SEASON_SPRING // "Spring"
Seasons::SEASON_SUMMER // "Summer"
Seasons::SEASON_AUTUMN // "Autumn"

License

MIT