DateHelper – Smart, Flexible Date Normalization for Laravel

A lightweight Laravel package that converts any human-written date string — including Arabic digits, Arabic month names, timestamps, and messy formats — into a clean MySQL-compatible date (Y-m-d).

This package solves a common real-world problem:

Users enter dates in many different formats.
Your backend needs one consistent format.

DateHelper intelligently detects, normalizes, and validates dates coming from forms, mobile apps, imports, or mixed Arabic/English inputs.

---

🌟 Features

• Converts almost any date format into Y-m-d
• Full support for Arabic digits (٠١٢٣٤٥٦٧٨٩)
• Full support for Persian digits (۰۱۲۳۴۵۶۷۸۹)
• Arabic month names support (مارس, أكتوبر, أغسطس …)
• Automatic timestamp handling (seconds & milliseconds)
• Cleans noise (ordinals, commas, NBSP, time parts)
• Safe fallback using Carbon natural-language parsing
• Year-range validation to avoid parsing Hijri years incorrectly
• Graceful error handling (null on failure)
• No warnings, no exceptions thrown

---

🚀 Installation

composer require fadyreda99/laravel-date-helper

Laravel automatically discovers the service provider.

---

🧠 Usage

1️⃣ Static Usage

use Fadyreda99\DateHelper\DateHelper;

$date = DateHelper::toMysqlDate('٠٣/٠٤/٢٠٢٤');
// "2024-04-03"

---

3️⃣ Dependency Injection

use Fadyreda99\DateHelper\DateHelper;

class MyController
{
    public function store(DateHelper $dates)
    {
        $clean = $dates->toMysqlDate('March 4, 2024');
        // "2024-03-04"
    }
}

---

🔍 Supported Formats

Numeric:

• Y-m-d
• Y/m/d
• Y.m.d
• Ymd
• d-m-Y
• d/m/Y
• d.m.Y
• dmY
• m-d-Y
• m/d/Y
• m.d.Y

Textual:

• F j, Y
• F d, Y
• M j, Y
• M d, Y
• j F Y
• d F Y
• j M Y
• d M Y

Mixed:

• d M Y
• M d Y
• d-M-Y
• d.M.Y

Natural Language Fallback:

• "today"
• "yesterday"
• "tomorrow"
• "next week"
• "next month"
• "last week"
• "last month"
• "in 2 days"
• "in 3 weeks"
• "-1 day"
• "+1 day"
• "+2 months"
• "last friday"
• "next tuesday"

---

🌍 Arabic & Persian Support

Arabic Digit Conversion

٠٣/٠٤/٢٠٢٤ → 03/04/2024

Arabic Month Names

• مارس → March
• أكتوبر → October
• اغسطس → August

Persian Digits

۲۰۲۴-۰۴-۰۳ → 2024-04-03

---

🕒 Timestamp Support

Supports:

• 10-digit Unix timestamps
• 13+ digit millisecond timestamps

Example:

DateHelper::toMysqlDate('1609459200000');
// "2021-01-01"

---

⚙️ Year Validation

Accepted year range:

1900 → (current year + 5)

Prevents treating Hijri-like dates such as:

1445-01-01

as Gregorian year 1445.

---

🚫 Error Handling

If the date cannot be parsed, the function returns:

null

• No exceptions
• No warnings
• Safe for forms, DTOs, models, imports

---

🤝 Contributing

Contributions are welcome!
If you find a missing format, edge case, or improvement — please open an issue or PR.

---

📄 License

This package is open-source under the MIT License.