ISO 3166 / PHP

Look up the seasonby country code

Hemisphere, flag emoji and BCP 47 names in one lookup, with six framework adapters.

season mascot Seasony, the season project pet

One function that knows both hemispheres

season resolves the current season from an ISO 3166-1 alpha-2 country code. The southern hemisphere table is built in, and trans-equatorial countries follow the hemisphere where most of their population lives.

The same entry point also returns Chinese season names, flag emoji, season emoji and BCP 47 localized names. Everything is an in-memory lookup with no IO and no state changes.

Hemisphere detection
BCP 47 locales
Flag and season emoji

6Framework integrations

8Core capabilities

ISO 3166Country code standard

Seasony

A round globe spirit: spring green in the upper left hemisphere, autumn orange in the lower right, a sprout on top and four seasonal emblems around it.

Same month, two seasons.

Eight capabilities, all pure functions

Country code and date in, season and text out.

Country code lookup

ISO 3166-1 alpha-2 two-letter codes, case-insensitive, with an exception on invalid input.

Two hemispheres

A built-in southern hemisphere table, with trans-equatorial countries decided by population majority.

Season emoji

Blossom, sun, leaf and snowflake graphics, returned for the country's current season.

Localized names

BCP 47 locale resolution supporting forms such as zh_CN, en_US and de_DE.

Flag emoji

Regional indicators generated from the two-letter code, for upper or lower case input.

Six framework integrations

Laravel, ThinkPHP, Hyperf, Yii2, Yii3 and webman are all supported.

How the versions grew

Every version maps to a real commit and release.

v2.1.02026-09-25

Native PHP and mascot API

Added the native PHP bootstrap and Mascot/Emoji APIs, and fixed trans-equatorial country detection.

v2.0.42026-08-29

Hemisphere data calibration

Removed KI and UM, which are mostly in the northern hemisphere, added TL and AS, and added regression tests.

v2.0.32026-08-27

CI and test coverage

Fixed PHPStan always-true assertion errors and added unit tests and reports for every module.

v2.0.22026-08-02

Hemisphere fix wrap-up

Completed the hemisphere data fix and documented known issues and release notes.

Changelog

Recent releases; full list on GitHub Releases.

Latest v2.1.0 All versions

v2.1.02026-09-25

Added native PHP support and mascot APIs, and fixed hemisphere detection for trans-equatorial countries.

v2.0.42026-08-29

Calibrated the southern hemisphere table: removed KI/UM, added TL/AS and regression tests.

v2.0.32026-08-27

Fixed CI static analysis errors and added unit tests and test reports.

v2.0.22026-08-02

Wrapped up the hemisphere data fix and documented known issues and release notes.

v2.0.12026-07-27

Fixed Guyana (GY) being incorrectly listed as a southern hemisphere country.

v2.0.02026-05-17

Released version 2.0 and documented known issues and release notes.

Architecture and design

Click an image to enlarge.

Install and use

Install it, then look up a season by country code.

PHP >= 8.0 / mbstringFull README

Install

composer require erikwang2013/season

Minimal example

use Erikwang2013\Season\CountrySeason;

$season = CountrySeason::getSeason('CN');
$zh = CountrySeason::getSeasonNameZh('AU');
$flag = CountrySeason::getCountryFlagEmoji('JP');
$name = CountrySeason::getSeasonNameLocalized('DE', 'de_DE');

Twelve faces of Seasony

Hover and the mood changes.