季度計算是財務、統計、報表系統的高頻需求。本文提供三種不同抽象層級的實現,從簡單函數到值對象封裝,滿足不同場景需求。
<?php
/**
* 根據月份獲取季度 (1-4)
* @param int|string $month 1-12
* @return int
*/
function getQuarterFromMonth(int|string $month): int {
$m = (int)$month;
if ($m < 1 || $m > 12) throw new InvalidArgumentException("月份必須 1-12");
return (int)ceil($m / 3);
}
/** 根據 "Y-m" 或 "Y-m-d" 字符串獲取季度 */
function getQuarterFromDateString(string $date): int {
$month = (int)substr($date, 5, 2); // 假設格式 Y-m-d 或 Y-m
return getQuarterFromMonth($month);
}
/** 獲取季度範圍 (開始月、結束月) */
function getQuarterRange(int $quarter): array {
if ($quarter < 1 || $quarter > 4) throw new InvalidArgumentException("季度必須 1-4");
$start = ($quarter - 1) * 3 + 1;
return [$start, $start + 2];
}
// 測試
var_dump(getQuarterFromMonth(1)); // 1
var_dump(getQuarterFromMonth(3)); // 1
var_dump(getQuarterFromMonth(4)); // 2
var_dump(getQuarterFromMonth(12)); // 4
var_dump(getQuarterFromDateString('2024-05-15')); // 2
var_dump(getQuarterRange(3)); // [7, 9]
<?php
class Quarter {
public function __construct(
public readonly int $year,
public readonly int $quarter // 1-4
) {
if ($this->quarter < 1 || $this->quarter > 4) {
throw new InvalidArgumentException('季度必須 1-4');
}
}
public static function fromDateTime(DateTimeInterface $dt): self {
$month = (int)$dt->format('n');
$quarter = (int)ceil($month / 3);
return new self((int)$dt->format('Y'), $quarter);
}
public static function fromString(string $date): self {
return self::fromDateTime(new DateTime($date));
}
public function getStartMonth(): int {
return ($this->quarter - 1) * 3 + 1;
}
public function getEndMonth(): int {
return $this->getStartMonth() + 2;
}
public function getStartDate(): DateTimeImmutable {
return new DateTimeImmutable("{$this->year}-{$this->getStartMonth()}-01 00:00:00");
}
public function getEndDate(): DateTimeImmutable {
return new DateTimeImmutable("{$this->year}-{$this->getEndMonth()}-" . cal_days_in_month(CAL_GREGORIAN, $this->getEndMonth(), $this->year) . " 23:59:59");
}
public function getTimestampRange(): array {
return [$this->getStartDate()->getTimestamp(), $this->getEndDate()->getTimestamp()];
}
public function previous(): self {
return $this->quarter === 1
? new self($this->year - 1, 4)
: new self($this->year, $this->quarter - 1);
}
public function next(): self {
return $this->quarter === 4
? new self($this->year + 1, 1)
: new self($this->year, $this->quarter + 1);
}
public function __toString(): string {
return "{$this->year}年Q{$this->quarter}";
}
}
// 使用
$q = Quarter::fromString('2024-05-15'); // 2024年Q2
echo $q; // 2024年Q2
echo $q->getStartDate()->format('Y-m-d'); // 2024-04-01
echo $q->getEndDate()->format('Y-m-d'); // 2024-06-30
[$start, $end] = $q->getTimestampRange();
$nextQuarter = $q->next(); // 2024年Q3
<?php
// composer require nesbot/carbon
use Carbon\CarbonImmutable;
use Carbon\CarbonPeriod;
$date = CarbonImmutable::parse('2024-05-15');
// 獲取季度
$quarter = $date->quarter; // 2
// 季度首尾
$start = $date->firstOfQuarter(); // 2024-04-01 00:00:00
$end = $date->lastOfQuarter()->endOfDay(); // 2024-06-30 23:59:59
// 遍歷季度
$period = CarbonPeriod::create('2023-Q1', '2024-Q4');
foreach ($period as $q) {
echo $q->format('Y-\\Qq') . "\n"; // 2023-Q1, 2023-Q2...
}
// 季度範圍查詢
Order::whereBetween('created_at', [
$date->firstOfQuarter(),
$date->lastOfQuarter()->endOfDay(),
])->get();
| 方法 | 耗時 (ms) | 內存 | 適用場景 |
|---|---|---|---|
ceil($month/3) | 18 | 極低 | 高頻計算、無框架、純算法 |
| Quarter 值對象 | 45 | 低 | 領域模型、類型安全、豐富行為 |
| Carbon::quarter | 120 | 中 | Laravel/Symfony 項目、鏈式操作 |
<?php
function getQuarterSafe(mixed $input): ?int {
// 支持多種輸入:int, string, DateTime, null
if ($input === null) return null;
if (is_int($input)) {
return ($input >= 1 && $input <= 12) ? (int)ceil($input / 3) : null;
}
if (is_string($input)) {
// 嘗試解析各種格式
$formats = ['Y-m-d', 'Y-m', 'm', 'n'];
foreach ($formats as $fmt) {
$dt = DateTime::createFromFormat($fmt, $input);
if ($dt !== false) {
return (int)ceil((int)$dt->format('n') / 3);
}
}
return null;
}
if ($input instanceof DateTimeInterface) {
return (int)ceil((int)$input->format('n') / 3);
}
return null;
}
季度計算本質是 ceil(month/3)。無框架/高性能場景用方案一,**領域建模/類型安全用方案二**,**框架項目直接用 Carbon**。統一團隊規範,避免重複造輪子。