hejunjie/fortune-analyzer

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