คลาส Date - ยูทิลิตี้สำหรับจัดการวันที่และเวลา

คลาส Date เป็นยูทิลิตี้สำหรับการจัดการวันที่ เวลา การคำนวณอายุ การจัดรูปแบบวันที่ และการแปลงเป็นรูปแบบที่อ่านง่าย รองรับภาษาไทย (พ.ศ.) และหลายภาษา

Namespace

Kotchasan\Date

ภาพรวม

Date class ประกอบด้วยเมธอดสำหรับ:

• คำนวณความแตกต่างระหว่างวันที่ (อายุ, ระยะเวลา)
• จัดรูปแบบวันที่ตามภาษา (รองรับ พ.ศ./ค.ศ., ชื่อเดือน/วันภาษาไทย)
• แปลงวันที่เป็นรูปแบบ "time ago" (เมื่อ 5 นาทีที่แล้ว)
• แยกและตรวจสอบรูปแบบวันที่

API Reference

compare()

คำนวณความแตกต่างระหว่างสองวันที่ คืนค่าจำนวนวัน ปี เดือน และวัน

public static function compare($begin_date, $end_date): array

Parameters:

• $begin_date - วันที่เริ่มต้น (Unix timestamp หรือ Y-m-d format)
• $end_date - วันที่สิ้นสุด (Unix timestamp หรือ Y-m-d format)

Returns: ['days' => int, 'year' => int, 'month' => int, 'day' => int]

• days - จำนวนวันทั้งหมด (อาจเป็นลบได้ถ้า begin_date > end_date)
• year - จำนวนปี
• month - จำนวนเดือน (0-11)
• day - จำนวนวัน (0-30)

Example:

use Kotchasan\Date;

// คำนวณอายุ
$birthDate = '1990-05-15';
$age = Date::compare($birthDate, date('Y-m-d'));
echo "อายุ: {$age['year']} ปี {$age['month']} เดือน {$age['day']} วัน";
// "อายุ: 34 ปี 6 เดือน 17 วัน"

// ใช้ Unix timestamp
$start = strtotime('2024-01-01');
$end = time();
$duration = Date::compare($start, $end);
echo "ผ่านไป {$duration['days']} วัน";

// คำนวณอายุงาน
$hireDate = '2020-03-15';
$workDuration = Date::compare($hireDate, date('Y-m-d'));
echo "อายุงาน: {$workDuration['year']} ปี";

// ตรวจสอบอายุ
if ($age['year'] >= 18) {
    echo "บรรลุนิติภาวะ";
}

// คำนวณวันหมดอายุ
$expiryDate = '2025-12-31';
$remaining = Date::compare(date('Y-m-d'), $expiryDate);
if ($remaining['days'] > 0) {
    echo "เหลือ {$remaining['days']} วัน";
} else {
    echo "หมดอายุแล้ว";
}

age()

คืนค่าอายุเป็นข้อความแบบอ่านง่าย (ใช้ Language placeholders)

public static function age(string $date): string

Parameters:

• $date - วันที่เกิดหรือวันที่เริ่มต้น

Returns: สตริงรูปแบบ "X {LNG_year} Y {LNG_month} Z {LNG_days}"

Example:

use Kotchasan\Date;

// แสดงอายุ
$birthDate = '1990-05-15';
echo Date::age($birthDate);
// "34 {LNG_year} 6 {LNG_month} 17 {LNG_days}"
// (แปลงเป็นภาษาไทย: "34 ปี 6 เดือน 17 วัน")

// ใช้กับฐานข้อมูล
$users = $db->select('users', ['name', 'birth_date']);
foreach ($users as $user) {
    echo "{$user->name}: " . Date::age($user->birth_date);
}

// คำนวณอายุงาน
$member = $db->first("SELECT join_date FROM members WHERE id=?", [1]);
echo "สมาชิกมาแล้ว: " . Date::age($member->join_date);

timeDiff()

คำนวณความแตกต่างของเวลาเป็นวินาที

public static function timeDiff($firstTime, $lastTime): int

Parameters:

• $firstTime - เวลาแรก (string ที่ strtotime() เข้าใจได้)
• $lastTime - เวลาหลัง (string ที่ strtotime() เข้าใจได้)

Returns: จำนวนวินาที (อาจเป็นลบได้)

Example:

use Kotchasan\Date;

// คำนวณระยะเวลา
$start = '2024-12-01 10:00:00';
$end = '2024-12-01 10:05:30';
$seconds = Date::timeDiff($start, $end);
echo "ใช้เวลา: {$seconds} วินาที"; // 330

// แปลงเป็นนาที
$minutes = $seconds / 60;
echo "ใช้เวลา: " . number_format($minutes, 2) . " นาที"; // 5.50

// วัดเวลา session
$session = $db->first("SELECT login_time, logout_time FROM sessions WHERE id=1");
$duration = Date::timeDiff($session->login_time, $session->logout_time);
echo "ใช้งาน: " . gmdate("H:i:s", $duration);

// คำนวณเวลาคงเหลือ
$deadline = '2024-12-31 23:59:59';
$timeLeft = Date::timeDiff(date('Y-m-d H:i:s'), $deadline);
$days = floor($timeLeft / 86400);
$hours = floor(($timeLeft % 86400) / 3600);
echo "เหลือ {$days} วัน {$hours} ชั่วโมง";

dateName()

แปลงตัวเลข (0-6) เป็นชื่อวันในภาษาปัจจุบัน

public static function dateName(int $date, bool $short_date = true): string

Parameters:

• $date - ตัวเลข 0-6 (0=อาทิตย์, 1=จันทร์, ..., 6=เสาร์)
• $short_date - true = ชื่อย่อ (อ., จ.), false = ชื่อเต็ม (อาทิตย์, จันทร์)

Returns: ชื่อวันตามภาษาที่ตั้งค่า

Example:

use Kotchasan\Date;

// ชื่อวันแบบสั้น (default)
echo Date::dateName(0); // "อ." (อาทิตย์)
echo Date::dateName(1); // "จ." (จันทร์)
echo Date::dateName(6); // "ส." (เสาร์)

// ชื่อวันแบบเต็ม
echo Date::dateName(0, false); // "อาทิตย์"
echo Date::dateName(1, false); // "จันทร์"

// วันนี้
$today = date('w'); // 0-6
echo "วันนี้: " . Date::dateName($today, false);

// สร้างหัวตารางปฏิทิน
for ($i = 0; $i < 7; $i++) {
    echo Date::dateName($i) . " ";
}
// "อ. จ. อ. พ. พฤ. ศ. ส."

// ใช้กับนัดหมาย
$appointments = $db->select('appointments', ['appointment_date']);
foreach ($appointments as $apt) {
    $dayNum = date('w', strtotime($apt->appointment_date));
    echo "นัดวัน" . Date::dateName($dayNum, false);
}

format()

จัดรูปแบบวันที่ตามรูปแบบที่กำหนด (รองรับ custom placeholders)

public static function format($time = 0, ?string $format = null): string

Parameters:

• $time - Unix timestamp, สตริงวันที่, หรือ 0 (= เวลาปัจจุบัน)
• $format - รูปแบบ (ถ้าไม่ระบุ ใช้ DATE_FORMAT จาก Language)

Returns: วันที่ที่จัดรูปแบบแล้ว

Custom Format Placeholders:

• Y - ปี พ.ศ. (เพิ่ม YEAR_OFFSET จาก Language, เช่น +543)
• F - ชื่อเดือนเต็ม (มกราคม, ..., ธันวาคม)
• M - ชื่อเดือนย่อ (ม.ค., ..., ธ.ค.)
• L - ชื่อวันเต็ม (อาทิตย์, ..., เสาร์)
• l - ชื่อวันย่อ (อ., ..., ส.)
• อื่นๆ - ใช้ date() format ปกติ (d, m, H, i, s, ...)

Example:

use Kotchasan\Date;

// วันนี้ (ใช้รูปแบบจาก Language config)
echo Date::format(); // ตาม DATE_FORMAT

// Unix timestamp
$timestamp = strtotime('2024-12-01 15:30:00');
echo Date::format($timestamp, 'd/m/Y H:i');
// "01/12/2567 15:30" (ถ้า YEAR_OFFSET = 543)

// String วันที่
echo Date::format('2024-12-01', 'd F Y');
// "01 ธันวาคม 2567"

// รูปแบบภาษาไทยเต็ม
echo Date::format(time(), 'วันL ที่ d F พ.ศ. Y');
// "วันอาทิตย์ ที่ 03 กุมภาพันธ์ พ.ศ. 2569"

// แสดงเฉพาะเวลา
echo Date::format(time(), 'H:i:s'); // "20:10:00"

// ใช้กับข้อมูลจากฐานข้อมูล
$posts = $db->select('posts', ['title', 'created_at']);
foreach ($posts as $post) {
    $formatted = Date::format($post->created_at, 'd/m/Y H:i');
    echo "{$post->title} - {$formatted}";
}

// วันที่แบบย่อ
echo Date::format('2024-12-01', 'd M Y');
// "01 ธ.ค. 2567"

monthName()

แปลงตัวเลข (1-12) เป็นชื่อเดือนในภาษาปัจจุบัน

public static function monthName(int $month, bool $short_month = true): string

Parameters:

• $month - ตัวเลข 1-12 (1=มกราคม, ..., 12=ธันวาคม)
• $short_month - true = ชื่อย่อ (ม.ค., ธ.ค.), false = ชื่อเต็ม (มกราคม, ธันวาคม)

Returns: ชื่อเดือนตามภาษาที่ตั้งค่า

Example:

use Kotchasan\Date;

// ชื่อเดือนแบบสั้น (default)
echo Date::monthName(1); // "ม.ค."
echo Date::monthName(12); // "ธ.ค."

// ชื่อเดือนแบบเต็ม
echo Date::monthName(1, false); // "มกราคม"
echo Date::monthName(12, false); // "ธันวาคม"

// เดือนปัจจุบัน
$currentMonth = date('n'); // 1-12
echo "เดือนนี้: " . Date::monthName($currentMonth, false);

// สร้างรายการเดือน
for ($m = 1; $m <= 12; $m++) {
    echo $m . ". " . Date::monthName($m, false) . "\n";
}

// Dropdown เลือกเดือน
echo '<select name="month">';
for ($i = 1; $i <= 12; $i++) {
    $name = Date::monthName($i, false);
    echo "<option value='{$i}'>{$name}</option>";
}
echo '</select>';

// รายงานรายเดือน
$sales = $db->query("SELECT MONTH(sale_date) as m, SUM(amount) as total
                     FROM sales GROUP BY m");
foreach ($sales as $row) {
    $monthName = Date::monthName($row->m, false);
    echo "{$monthName}: " . number_format($row->total);
}

parse()

แยกสตริงวันที่เป็น array ของส่วนประกอบ

public static function parse(string $date): array|false

Parameters:

• $date - สตริงวันที่รูปแบบ YYYY-MM-DD หรือ YYYY-MM-DD HH:II:SS

Returns: Array ['y', 'm', 'd', 'h', 'i', 's'] หรือ false (ถ้ารูปแบบไม่ถูกต้อง)

Example:

use Kotchasan\Date;

// แยกวันที่
$parsed = Date::parse('2024-12-01');
print_r($parsed);
// ['y' => '2024', 'm' => '12', 'd' => '01']

// แยกวันที่และเวลา
$parsed = Date::parse('2024-12-01 15:30:45');
print_r($parsed);
// ['y' => '2024', 'm' => '12', 'd' => '01',
//  'h' => '15', 'i' => '30', 's' => '45']

// Validate วันที่จาก user input
$userDate = $_POST['date'] ?? '';
$parsed = Date::parse($userDate);

if ($parsed) {
    echo "ปี: {$parsed['y']}, เดือน: {$parsed['m']}, วัน: {$parsed['d']}";

    if (isset($parsed['h'])) {
        echo ", เวลา: {$parsed['h']}:{$parsed['i']}";
    }
} else {
    echo "รูปแบบวันที่ไม่ถูกต้อง";
}

// ตรวจสอบความถูกต้อง
function validateDate($dateStr) {
    $parsed = Date::parse($dateStr);
    if (!$parsed) return false;

    return checkdate($parsed['m'], $parsed['d'], $parsed['y']);
}

if (validateDate('2024-02-30')) {
    echo "วันที่ถูกต้อง";
} else {
    echo "วันที่ไม่ถูกต้อง"; // ← จะได้ผลนี้
}

// แปลงรูปแบบ
$parsed = Date::parse('2024-12-01');
if ($parsed) {
    $timestamp = mktime(0, 0, 0, $parsed['m'], $parsed['d'], $parsed['y']);
    echo date('d/m/Y', $timestamp); // "01/12/2024"
}

timeAgo()

แปลงวันที่เป็นข้อความ "เมื่อไหร่" (time ago format)

public static function timeAgo(string $date): string

Parameters:

• $date - วันที่ที่ต้องการแปลง

Returns: สตริงรูปแบบ "{N} {LNG_unit} {LNG_ago}" หรือ "{LNG_now}"

Time Units (เรียงตามลำดับ):

• ปี: {N} {LNG_year} {LNG_ago}
• เดือน: {N} {LNG_month} {LNG_ago}
• สัปดาห์: {N} {LNG_week} {LNG_ago} (> 7 วัน)
• วัน: {N} {LNG_days} {LNG_ago} (> 2 วัน)
• ชั่วโมง: {N} {LNG_hours} {LNG_ago}
• นาที: {N} {LNG_minutes} {LNG_ago}
• ตอนนี้: {LNG_now} (< 1 นาที)

Example:

use Kotchasan\Date;

// เมื่อ 5 นาทีที่แล้ว
echo Date::timeAgo('2024-12-01 10:00:00');
// "5 {LNG_minutes} {LNG_ago}" → "5 นาทีที่แล้ว"

// เมื่อ 2 ชั่วโมงที่แล้ว
echo Date::timeAgo('2024-12-01 08:00:00');
// "2 {LNG_hours} {LNG_ago}" → "2 ชั่วโมงที่แล้ว"

// เมื่อ 1 เดือนที่แล้ว
echo Date::timeAgo('2024-11-01');
// "1 {LNG_month} {LNG_ago}" → "1 เดือนที่แล้ว"

// โพสต์โซเชียล
$posts = $db->select('posts', ['content', 'created_at']);
foreach ($posts as $post) {
    echo "<div>";
    echo "<p>{$post->content}</p>";
    echo "<small>" . Date::timeAgo($post->created_at) . "</small>";
    echo "</div>";
}

// ความคิดเห็น
$comments = $db->select('comments', ['comment', 'created_at']);
foreach ($comments as $comment) {
    $timeAgo = Date::timeAgo($comment->created_at);
    echo "{$comment->comment} - {$timeAgo}";
}

// การแจ้งเตือน
$notifications = $db->select('notifications',
    ['message', 'created_at'],
    ['user_id' => $userId]
);
foreach ($notifications as $notif) {
    echo "<div class='notification'>";
    echo "{$notif->message} ({Date::timeAgo($notif->created_at)})";
    echo "</div>";
}

ตัวอย่างการใช้งานจริง

1. ระบบสมาชิก

use Kotchasan\Date;

class MemberSystem
{
    public function getMemberInfo($memberId)
    {
        global $db;
        $member = $db->first("SELECT * FROM members WHERE id=?", [$memberId]);

        $age = Date::compare($member->birth_date, date('Y-m-d'));
        $memberSince = Date::compare($member->join_date, date('Y-m-d'));

        return [
            'name' => $member->name,
            'age' => $age['year'] . ' ปี',
            'age_text' => Date::age($member->birth_date),
            'member_since' => Date::format($member->join_date, 'd F Y'),
            'membership_years' => $memberSince['year'],
            'is_adult' => $age['year'] >= 18,
            'last_login' => Date::timeAgo($member->last_login)
        ];
    }
}

2. รายงานการขาย

class SalesReport
{
    public function getDailySales($date)
    {
        global $db;
        $sales = $db->select('sales', '*', ['DATE(created_at)' => $date]);

        $dayNum = date('w', strtotime($date));

        return [
            'date' => Date::format($date, 'd F Y'),
            'day_name' => Date::dateName($dayNum, false),
            'total_sales' => count($sales),
            'sales' => array_map(function($sale) {
                return [
                    'amount' => number_format($sale->amount, 2),
                    'time' => Date::format($sale->created_at, 'H:i'),
                    'time_ago' => Date::timeAgo($sale->created_at)
                ];
            }, $sales)
        ];
    }
}

3. ระบบจองห้องประชุม

class BookingSystem
{
    public function checkAvailability($date)
    {
        $dayOfWeek = date('w', strtotime($date));

        // ตรวจสอบวันหยุด
        if ($dayOfWeek == 0 || $dayOfWeek == 6) {
            return [
                'available' => false,
                'reason' => 'วัน' . Date::dateName($dayOfWeek, false) . 'ปิดทำการ'
            ];
        }

        return [
            'available' => true,
            'date' => Date::format($date, 'วันL ที่ d F Y'),
            'day_name' => Date::dateName($dayOfWeek, false)
        ];
    }

    public function canCancelBooking($bookingDate)
    {
        $diff = Date::compare($bookingDate, date('Y-m-d'));
        return [
            'can_cancel' => $diff['days'] < 7,
            'days_until' => $diff['days'],
            'message' => "จองไว้" . Date::timeAgo($bookingDate)
        ];
    }
}

4. ระบบพนักงาน

class EmployeeSystem
{
    public function calculateRetirement($birthDate)
    {
        $retirementAge = 60;
        $currentAge = Date::compare($birthDate, date('Y-m-d'));
        $yearsToRetirement = $retirementAge - $currentAge['year'];

        if ($yearsToRetirement > 0) {
            return "เกษียณอีก {$yearsToRetirement} ปี";
        }

        return "เกษียณแล้ว";
    }

    public function getWorkDuration($hireDate)
    {
        $duration = Date::compare($hireDate, date('Y-m-d'));

        return [
            'years' => $duration['year'],
            'months' => $duration['month'],
            'days' => $duration['day'],
            'total_days' => $duration['days'],
            'text' => Date::age($hireDate),
            'is_senior' => $duration['year'] >= 5
        ];
    }
}

Best Practices

1. ใช้ compare() สำหรับคำนวณ

// ✅ Good - ใช้ compare() ได้ข้อมูลครบ
$diff = Date::compare($start, $end);
echo "{$diff['year']} ปี {$diff['month']} เดือน";

// ❌ Bad - คำนวณเอง ซับซ้อน
$y1 = date('Y', strtotime($start));
$y2 = date('Y', strtotime($end));
echo ($y2 - $y1) . " ปี"; // ไม่แม่นย�า

2. ใช้ format() สำหรับแสดงผล

// ✅ Good - ใช้ format() รองรับหลายภาษา
echo Date::format($date, 'd F Y'); // "01 ธันวาคม 2567"

// ❌ Bad - hardcode ภาษา
echo date('d', $timestamp) . " ธันวาคม " . (date('Y', $timestamp) + 543);

3. ใช้ timeAgo() สำหรับ social features

// ✅ Good - อ่านง่าย user-friendly
echo Date::timeAgo($post->created_at); // "5 นาทีที่แล้ว"

// ❌ Bad - แสดงวันที่เต็ม
echo $post->created_at; // "2024-12-01 10:00:00" (ยาก)

4. Validate ด้วย parse()

// ✅ Good - validate ก่อนใช้
$parsed = Date::parse($_POST['date']);
if ($parsed && checkdate($parsed['m'], $parsed['d'], $parsed['y'])) {
    // ปลอดภัย
}

// ❌ Bad - ใช้ตรงๆ
$date = strtotime($_POST['date']); // อันตราย!

ข้อควรระวัง

[!WARNING]
Language Dependency: เมธอด dateName(), monthName(), format() ต้องการ Language class ถูก configure ก่อน

[!NOTE]
YEAR_OFFSET: ปี พ.ศ. ใช้ YEAR_OFFSET = 543 จาก Language config

[!IMPORTANT]
parse() รองรับเฉพาะ: รูปแบบ YYYY-MM-DD และ YYYY-MM-DD HH:II:SS เท่านั้น

[!TIP]
timeDiff() vs compare(): ใช้ timeDiff() สำหรับวินาที, compare() สำหรับปี/เดือน/วัน

คลาสที่เกี่ยวข้อง

• Number - การจัดรูปแบบตัวเลข
• Text - การจัดการข้อความ
• Language - การจัดการภาษา

สรุป

คลาส Date มี 8 เมธอดหลัก:

1. compare() - คำนวณความแตกต่างวันที่ (คืนค่า days, year, month, day)
2. age() - แปลงเป็นข้อความอายุ (X ปี Y เดือน Z วัน)
3. timeDiff() - คำนวณเป็นวินาที
4. dateName() - ชื่อวัน (อาทิตย์-เสาร์)
5. format() - จัดรูปแบบวันที่ (รองรับ พ.ศ./ชื่อไทย)
6. monthName() - ชื่อเดือน (มกราคม-ธันวาคม)
7. parse() - แยกส่วนประกอบวันที่
8. timeAgo() - แปลงเป็น "เมื่อไหร่" (5 นาทีที่แล้ว)

เหมาะสำหรับ:

• ระบบสมาชิก (คำนวณอายุ)
• รายงาน (จัดรูปแบบวันที่)
• โซเชียลมีเดีย (time ago)
• ปฏิทิน (ชื่อวัน/เดือน)