erikwang2013/season

PHP library / extension that resolves the current season from an ISO 3166-1 alpha-2 country code. Use it as a plain Composer package, or integrate with Laravel 7–11, ThinkPHP 6 / 8, Hyperf 2 / 3, and webman. Besides English season keys (spring, etc.) and Chinese names, it provides flag emoji, locali

Maintainers

Package info

github.com/erikwang2013/season

pkg:composer/erikwang2013/season

Statistics

Installs: 17

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.0.2 2026-04-07 03:56 UTC

Requires

Suggests

MIT 321747fac2e6087d5d5d0b5590081ae223d4ba98

  • erik <erik.woop@erik.xyz>

phplaravelcountryISO 3166-1thinkphpseasonhyperfwebman

This package is auto-updated.

Last update: 2026-04-07 07:00:26 UTC

README

Language: English · 简体中文

PHP library / extension that resolves the current season from an ISO 3166-1 alpha-2 country code. Use it as a plain Composer package, or integrate with Laravel 7–11, ThinkPHP 6 / 8, Hyperf 2 / 3, and webman. Besides English season keys (spring, etc.) and Chinese names, it provides flag emoji, localized season names by BCP 47 locale, hemisphere detection, and optional date-based calculation.

  • Northern hemisphere: spring Mar–May, summer Jun–Aug, autumn Sep–Nov, winter Dec / Jan / Feb
  • Southern hemisphere: autumn Mar–May, winter Jun–Aug, spring Sep–Nov, summer Dec / Jan / Feb

Installation

composer require erikwang2013/season

webman plugin

After installing the dependency, from your webman project root (with webman/console installed):

php webman install erikwang2013/season

Or manually copy vendor/erikwang2013/season/src/config/plugin/erikwang2013/season to config/plugin/erikwang2013/season in your project.

Laravel 7–11

After composer require, unless you disable this package’s package discovery in composer.json, CountrySeason\Laravel\CountrySeasonServiceProvider is auto-registered and SeasonService is bound to the container (default country code comes from merged config).

Optional: publish default config:

php artisan vendor:publish --tag=country-season-config

This creates config/country_season.php; default_country_code maps to COUNTRY_SEASON_DEFAULT (default CN). Inject CountrySeason\SeasonService in controllers or services.

ThinkPHP 6 / 8

Composer’s think extension discovery registers CountrySeason\ThinkPHP\Service, binds SeasonService, and merges the package config/country_season.php into country_season. Resolve CountrySeason\SeasonService from the container or use dependency injection.

Hyperf 2 / 3

Hyperf ConfigProvider merges config: SeasonService is bound; default country code is read from country_season.default_country_code.

Optional: publish config:

php bin/hyperf.php vendor:publish erikwang2013/season

After config/autoload/country_season.php exists, adjust as needed; otherwise built-in default CN applies (override via COUNTRY_SEASON_DEFAULT or custom config).

Usage

1. Static API (any PHP project)

use CountrySeason\CountrySeason;

// English keys: spring | summer | autumn | winter
$season = CountrySeason::getSeason('CN');        // e.g. winter
$season = CountrySeason::getSeason('AU');        // Southern hemisphere, e.g. summer

// Chinese: 春 | 夏 | 秋 | 冬
$zh = CountrySeason::getSeasonNameZh('CN');

// Fixed date
$date = new \DateTimeImmutable('2026-06-15');
$season = CountrySeason::getSeason('US', $date);  // summer

// Hemisphere
$hemisphere = CountrySeason::getHemisphere('BR'); // south
$valid = CountrySeason::isValidCode('XX');        // true/false

Flag emoji (Unicode regional indicators)

$flag = CountrySeason::getCountryFlagEmoji('CN');  // 🇨🇳
$flag = CountrySeason::getCountryFlagEmoji('us');  // case-insensitive → 🇺🇸

Invalid or non–two-letter codes throw InvalidArgumentException (same as getSeason, etc.).

Localized season names (BCP 47)

getSeasonNameLocalized uses the country code for the season (including hemisphere) and the locale for the label:

// Second argument is locale: zh_CN, en_US, ja, de, fr_FR, etc. (- and _ both OK)
$name = CountrySeason::getSeasonNameLocalized('DE', 'de_DE');   // e.g. Frühling
$name = CountrySeason::getSeasonNameLocalized('US', 'en_US');   // fall (US English)
$name = CountrySeason::getSeasonNameLocalized('GB', 'en_GB');   // autumn (UK English)

// With a specific date
$date = new \DateTimeImmutable('2026-03-01');
CountrySeason::getSeasonNameLocalized('AU', 'en', $date);

List built-in locale tags (lowercase + underscore):

$locales = CountrySeason::getSupportedLocales();

Locale resolution: full tag first (e.g. zh_CN), then language only (e.g. zh), else fallback to en.

Built-ins cover common languages (EN/ZH/JA/KO, DE/FR/ES/IT/PT, RU/NL/PL/SV/UK, AR/HI/TH/VI/ID/TR, CS/DA/FI/NO, RO/EL/HE/HU, etc.); see getSupportedLocales() for the full set. For unlisted variants, try the language code (e.g. es) or map/extend externally.

2. Global helpers (when autoloaded)

country_season('JP');       // e.g. spring
country_season_zh('AU');    // Chinese name, e.g. 秋

country_season_flag('FR');  // 🇫🇷
country_season_locale('IT', 'it_IT');  // e.g. Primavera
country_season_locale('KR', 'ko', $date);  // optional date

3. Laravel / ThinkPHP / Hyperf — SeasonService

After integration, container SeasonService uses framework config (country_season.default_country_code, same as package config/country_season.php). getSeasonForDefault() uses that default country.

4. webman — SeasonService (after plugin install)

Register once (e.g. in config/bootstrap.php), then resolve from the container:

use CountrySeason\SeasonService;
use support\Container;

Container::singleton(SeasonService::class, function () {
    $code = config('plugin.erikwang2013.season.app.default_country_code', 'CN');

    return new SeasonService(\is_string($code) ? $code : 'CN');
});
use support\Container;
use CountrySeason\SeasonService;

/** @var SeasonService $seasonService */
$seasonService = Container::get(SeasonService::class);

$seasonService->getSeason('CN');
$seasonService->getSeasonNameZh('AU');
$seasonService->getCountryFlagEmoji('JP');
$seasonService->getSeasonNameLocalized('FR', 'fr_FR');
$seasonService->getSeasonForDefault();
$seasonService->getHemisphere('NZ');

5. Configuration (webman)

File: config/plugin/erikwang2013/season/app.php

return [
    'enable' => true,
    'default_country_code' => 'CN',  // or env('COUNTRY_SEASON_DEFAULT', 'CN')
];

Country codes

  • ISO 3166-1 alpha-2 two-letter codes (e.g. CN, US, JP, AU).
  • Southern countries (AU, AR, NZ, BR, etc.) are mapped; others are treated as northern hemisphere.

API summary

Method / function Description
CountrySeason::getSeason / country_season English season key
CountrySeason::getSeasonNameZh / country_season_zh Chinese season name
CountrySeason::getCountryFlagEmoji / country_season_flag Flag emoji
CountrySeason::getSeasonNameLocalized / country_season_locale Localized name
CountrySeason::getSupportedLocales Built-in locales
CountrySeason::getHemisphere north / south
SeasonService::getSeasonForDefault Uses configured default country

Exceptions and validation

  • Country code must be two letters A–Z (case-insensitive); otherwise InvalidArgumentException from getSeason, getCountryFlagEmoji, etc.
  • isValidCode() only checks format; it does not validate real ISO country codes.

Requirements

  • PHP >= 8.0
  • mbstring extension (flag emoji uses mb_chr)
  • Optional: workerman/webman-framework, illuminate/support, topthink/framework, hyperf/framework

License

MIT