README

English ｜简体中文

A BaZi (Four Pillars of Destiny) charting library for PHP, supporting solar-lunar calendar conversion between 1900-2100, precise 24 solar terms calculation, Four Pillars charting, Five Elements analysis, Ten Gods interpretation, and Luck Cycles calculation.

Live Demo: hejunjie.life/composer/fortune-analyzer

This project has been parsed by Zread. Click to learn more: Learn More

Features

Solar-lunar calendar conversion, covering 1900-2100
24 solar terms accurate to the second, powered by Jet Propulsion Laboratory data
Four Pillars charting (year, month, day, hour pillars) with Wu Hu Dun and Wu Shu Dun calculations
Five Elements statistics (with/without hidden stems) and element configuration detection, covering San Hui, San He, Liu He, and Wu Ju
Ten Gods distribution and interpretation, categorized by Yin Star, Bi Jie, Shi Shang, Guan Sha, and Cai Star
Luck Cycles calculation, supporting start age computation and multi-step cycle projection, with Five Elements and Ten Gods annotations per step
Well-commented code with Chinese annotations for every calculation step, suitable for learning and customization

Requirements

PHP >= 8.1

Installation

composer require hejunjie/fortune-analyzer

Quick Start

<?php

use Hejunjie\FortuneAnalyzer\FortuneAnalyzer;

$date = '1997-01-21 16:30:00';
$gender = 1; // 1=male, 0=female

// Chart the Four Pillars (BaZi)
$pillars = FortuneAnalyzer::analyzeFourPillars($date);
// ['丙子', '辛丑', '癸亥', '庚申']

// Five Elements statistics (with hidden stems)
$wuXing = FortuneAnalyzer::analyzeWuXingFull($pillars);
// ['金' => 5, '木' => 1, '水' => 7, '火' => 1, '土' => 3]

// Ten Gods interpretation
$shiShen = FortuneAnalyzer::interpretShiShen($pillars);
// Returns frequency (count of each Ten God), statistics (5 categories), analysis (interpretation text)

// Luck Cycles
$luckCycles = FortuneAnalyzer::getLuckCycles($date, $gender);
// Returns 8-step luck cycle, each step includes luckPillar (stem-branch), startAge, wuXing, shiShen

In the examples above, $pillars is the return value of analyzeFourPillars(). All methods that require Four Pillars input accept this array.

API Reference

All methods are static methods of FortuneAnalyzer.

Calendar Conversion

Method	Description
`convertSolarToLunar($date)`	Convert solar date to lunar date, returns a date string
`convertLunarToSolar($date)`	Convert lunar date to solar date, returns a date string
`getSolarTerms($year)`	Get all 24 solar terms for a given year (second-level precision)

Four Pillars

Method	Description
`analyzeFourPillars($date)`	Get the complete BaZi, returns `[year, month, day, hour]` pillars
`getYearPillar($date)`	Get year pillar (heavenly stem + earthly branch)
`getMonthPillar($date)`	Get month pillar (heavenly stem + earthly branch)
`getDayPillar($date)`	Get day pillar (heavenly stem + earthly branch)
`getHourPillar($date)`	Get hour pillar (heavenly stem + earthly branch)

Five Elements Analysis

Method	Description
`getWuXingBreakdown($pillars)`	Detailed Five Elements breakdown for each pillar's stem, branch, and hidden stems
`analyzeWuXingSimple($pillars)`	Five Elements occurrence count (excluding hidden stems)
`analyzeWuXingFull($pillars)`	Five Elements occurrence count (including hidden stems)
`detectWuXingJu($pillars)`	Five Elements configuration detection, returns main configuration, description, and extras

Ten Gods Analysis

Method	Description
`getShiShenDistribution($pillars)`	Ten God distribution for each stem and branch in the Four Pillars
`interpretShiShen($pillars)`	Ten God frequency statistics, category grouping, and brief interpretation

Luck Cycles

Method	Description
`calculateStartAge($birthDatetime, $gender)`	Calculate the starting age and date for the first luck cycle
`getLuckCycles($birthDatetime, $gender, $count = 8)`	Generate the list of luck cycles, with configurable step count (defaults to 8)

Directory Structure

src/
├── FortuneAnalyzer.php          # Main entry point, static method facade
├── Calculator/
│   ├── BaZiCalculator.php       # Four Pillars calculation (year/month/day/hour pillars, Ten God derivation)
│   └── WuXingCalculator.php     # Five Elements statistics and configuration detection
├── Analysis/
│   ├── ShiShenAnalyzer.php      # Ten Gods distribution and interpretation
│   └── DaYunAnalyzer.php        # Luck cycle start calculation and projection
├── Converter/
│   ├── BaZiConstants.php        # Heavenly stems, earthly branches, Five Elements, Ten Gods constant mappings
│   └── DateConverter.php        # Solar/lunar date conversion and solar terms lookup
└── Data/
    ├── LunarMap.php             # Lunar date mapping data
    ├── SolarMap.php             # Solar date mapping data
    └── SolarTermsMap.php        # Solar terms mapping data (1900-2100)

Notes

All time calculations use UTC+8 (China Standard Time / Beijing Time)
Solar terms data covers 1900-2100; years outside this range will return empty results
The year pillar boundary is Li Chun (Start of Spring), not January 1st; the month pillar boundary follows the twelve Jie Qi (solar nodes), not the 1st of each Gregorian month
Time after 23:00 is treated as the next day's Zi hour; the day and hour pillar calculations handle cross-day logic automatically
Luck cycle projection uses the Shu Nian system (360 days per year), with 3 days equivalent to 1 year of starting age
The $date parameter accepts a string (e.g., '1997-01-21 16:30:00') or a DateTimeInterface instance
The $gender parameter: 1 for male, 0 for female
Yang male and Yin female: luck cycles are projected forward; Yin male and Yang female: projected backward

hejunjie / fortune-analyzer

Maintainers

Package info

Statistics

Security