PHPackages                             jobmetric/multi-calendar - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. jobmetric/multi-calendar

ActiveLibrary[Utility & Helpers](/categories/utility)

jobmetric/multi-calendar
========================

Multi-Calendar is a PHP library for converting dates between Gregorian, Jalali, Hijri, Hebrew, Buddhist, Coptic, Ethiopian, and Chinese calendars, with simple API and support for array or formatted string outputs.

1.6.0(6mo ago)3142[2 issues](https://github.com/jobmetric/multi-calendar/issues)1MITPHPPHP >=8.2CI passing

Since Aug 14Pushed 5mo agoCompare

[ Source](https://github.com/jobmetric/multi-calendar)[ Packagist](https://packagist.org/packages/jobmetric/multi-calendar)[ Docs](https://doc.jobmetric.net/package/multi-calendar)[ RSS](/packages/jobmetric-multi-calendar/feed)WikiDiscussions master Synced 3w ago

READMEChangelog (1)Dependencies (1)Versions (9)Used By (1)

[![Contributors](https://camo.githubusercontent.com/6399ef8f9db5e435f9fa4b0edef42a3b24e0b734545672969a5b27d596fefd6d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6e7472696275746f72732f6a6f626d65747269632f6d756c74692d63616c656e6461722e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/jobmetric/multi-calendar/graphs/contributors)[![Forks](https://camo.githubusercontent.com/436dc206abc55861e8a8160e0f435e40a8dec35c0c845b8c04d12a80004f1291/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f6a6f626d65747269632f6d756c74692d63616c656e6461722e7376673f7374796c653d666f722d7468652d6261646765266c6162656c3d466f726b)](https://github.com/jobmetric/multi-calendar/network/members)[![Stargazers](https://camo.githubusercontent.com/a6cb06160d58c1a3388d0993629b2d12d4753d2dc3a2c518a41764c804f5c63e/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f6a6f626d65747269632f6d756c74692d63616c656e6461722e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/jobmetric/multi-calendar/stargazers)[![MIT License](https://camo.githubusercontent.com/223b3d56378a01dc36e714a750a5174b29352ea857dd784397e2a46158ff5432/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6a6f626d65747269632f6d756c74692d63616c656e6461722e7376673f7374796c653d666f722d7468652d6261646765)](https://github.com/jobmetric/multi-calendar/blob/master/LICENCE.md)[![LinkedIn](https://camo.githubusercontent.com/eb590f47a3fca74584d18db8dd3e985ae3d786f50cd41b7530c3af3885da233c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f2d4c696e6b6564496e2d626c75652e7376673f7374796c653d666f722d7468652d6261646765266c6f676f3d6c696e6b6564696e26636f6c6f72423d353535)](https://linkedin.com/in/majidmohammadian)

Multi Calendar for PHP
======================

[](#multi-calendar-for-php)

Multi-Calendar is a PHP library for converting dates between multiple calendar systems, including Gregorian, Jalali (Persian), Hijri (Islamic), Hebrew, Buddhist, Coptic, Ethiopian, and Chinese. It provides an easy-to-use API with support for both array and formatted string outputs, making date conversions reliable and consistent across different calendar types.

Install via composer
--------------------

[](#install-via-composer)

Run the following command to pull in the latest version:

```
composer require jobmetric/multi-calendar
```

Documentation
-------------

[](#documentation)

### Basic Usage

[](#basic-usage)

```
use JobMetric\MultiCalendar\Converters\JalaliConverter;
use JobMetric\MultiCalendar\Converters\HijriConverter;

// Jalali (Persian) Example
$jalali = new JalaliConverter();
$result = $jalali->fromGregorian(2025, 8, 13); // [1404, 5, 22]
echo implode('/', $result); // "1404/05/22"

$gregorian = $jalali->toGregorian(1404, 5, 22); // [2025, 8, 13]
echo implode('-', $gregorian); // "2025-08-13"

// Hijri Example
$hijri = new HijriConverter();
echo $hijri->fromGregorian(2025, 8, 13, '/'); // e.g. "1447/02/20"
```

### Supported Calendars

[](#supported-calendars)

This library supports the following calendar systems, each with its own converter class. You can instantiate these classes and use their methods to convert dates between the Gregorian calendar and the respective calendar system.

Calendar KeyClass NameDescription`gregorian`GregorianConverter *(default)*The standard calendar used worldwide.`jalali` (Persian)JalaliConverterThe Iranian calendar, also known as the Solar Hijri calendar.`hijri` (Islamic)HijriConverterThe lunar calendar used in the Islamic world.`hebrew`HebrewConverterThe calendar used in Jewish culture.`buddhist`BuddhistConverterThe calendar used in many Buddhist countries.`coptic`CopticConverterThe calendar used in the Coptic Orthodox Church.`ethiopian`EthiopianConverterThe calendar used in Ethiopia.`chinese`ChineseConverterThe traditional Chinese calendar.### Using the Factory

[](#using-the-factory)

You can also use the `CalendarConverterFactory` to create converters dynamically based on the calendar key:

```
use JobMetric\MultiCalendar\Factory\CalendarConverterFactory;

// Create a converter dynamically
$conv = CalendarConverterFactory::make('jalali');

// Convert Gregorian to Jalali
echo $conv->fromGregorian(2025, 8, 13, '/'); // "1404/05/22"
```

### Number Transliteration

[](#number-transliteration)

You can convert numbers between English, Persian, and Arabic numeral systems:

```
use JobMetric\MultiCalendar\Helpers\NumberTransliterator;

echo NumberTransliterator::trNum('2025/08/13', 'fa'); // "۲۰۲۵/۰۸/۱۳"
echo NumberTransliterator::trNum('۱۴۰۴/۰۵/۲۲', 'en'); // "1404/05/22"
```

### Output Format

[](#output-format)

**Array output**: default when `$mod` (separator) is empty Example: `[2025, 8, 13]`

**String output**: set `$mod` to a separator (`/`, `-`, `.`) Example: `"2025/08/13"`

### Example Conversion Table for 2025-08-13 (Gregorian)

[](#example-conversion-table-for-2025-08-13-gregorian)

CalendarDateGregorian2025-08-13Jalali1404-05-22Hijri1447-02-20Hebrew5785-12-19Buddhist2568-08-13Coptic1741-12-07Ethiopian2017-12-07Chinese2025-07-11> **Note**: Values for non-Gregorian calendars are calculated using the `intl` extension. Actual results may vary slightly based on leap year and leap month handling.

Command Line Tool
-----------------

[](#command-line-tool)

The package includes a command-line tool (`date-converter.sh`) that allows you to convert dates between different calendar systems directly from your terminal without writing PHP code.

### Usage

[](#usage)

You can use the command-line tool in two ways:

**Direct execution:**

```
date-converter.sh [date] [options]
```

**Using Composer alias:**

```
composer date-convert -- [date] [options]
```

> **Note**: When using the Composer alias, use `--` to separate Composer arguments from the script arguments.

### Arguments

[](#arguments)

ArgumentDescription`date`Optional. If not provided, current date (now) will be used.### Options

[](#options)

OptionShortDescriptionDefault`--date-format``-df`Input calendar type (supported calendar systems)`gregorian``--to``-t`Output calendar type (supported calendar systems)`gregorian``--format-input``-fi`Input date string format (supported date formats), auto-detected if not providedAuto-detect`--format-output``-fo`Output date format (supported date formats)`Y-m-d``--timezone``-tz`Convert time to specified timezone (e.g., Asia/Tehran, UTC, Europe/London)None`--from-timezone``-ftz`Source timezone for time conversion (e.g., UTC, Europe/London)Auto-detect`--to-timezone``-ttz`Target timezone for time conversion (e.g., Asia/Tehran, UTC)None`--help``-h`Show this help message-### Supported Calendar Systems

[](#supported-calendar-systems)

- `gregorian`
- `jalali` or `persian`
- `hijri` or `islamic`
- `hebrew`
- `buddhist`
- `coptic`
- `ethiopian` or `ethiopic`
- `chinese`

### Supported Date Formats

[](#supported-date-formats)

- `Y-m-d`
- `d/m/Y`
- `F d Y`
- `Y/m/d H:i:s` (with time)

### Timezone Conversion

[](#timezone-conversion)

The command-line tool supports timezone conversion in two ways:

1. **Simple timezone conversion** (using `--timezone` for backward compatibility):

    - Converts the input time to the specified timezone
    - Automatically detects the source timezone from the input date or uses default based on calendar type
2. **Explicit timezone conversion** (using `--from-timezone` and `--to-timezone`):

    - Allows you to explicitly specify both source and target timezones
    - More precise control over timezone conversion
    - Automatically adds time to output format if timezone conversion is performed

**Important Notes:**

- When timezone conversion is performed and the input contains time, the output format will automatically include time (`H:i:s`) if not already specified
- If no time is present in the input, timezone conversion will not add time to the output
- Supported timezone formats: All PHP supported timezone identifiers (e.g., `UTC`, `Asia/Tehran`, `Europe/London`, `America/New_York`, `Asia/Kabul`, `America/Sao_Paulo`)

**Timezone Conversion Examples:**

```
# Convert from UTC to Asia/Tehran
# Input: 2025-12-20 12:00:00 (UTC)
# Output: 2025/12/20 15:30:00 (Asia/Tehran, UTC+3:30)
date-converter.sh "2025-12-20 12:00:00" --from-timezone UTC --to-timezone Asia/Tehran

# Convert from Europe/London to Asia/Kabul
# Input: 2025-12-20 12:00:00 (London, UTC+0 in winter)
# Output: 2025/12/20 16:30:00 (Kabul, UTC+4:30)
date-converter.sh "2025-12-20 12:00:00" --from-timezone Europe/London --to-timezone Asia/Kabul

# Convert from America/Sao_Paulo to Asia/Tehran
# Input: 2025-12-20 12:00:00 (Brazil, UTC-3)
# Output: 2025/12/20 18:30:00 (Tehran, UTC+3:30)
date-converter.sh "2025-12-20 12:00:00" --from-timezone America/Sao_Paulo --to-timezone Asia/Tehran

# Convert calendar and timezone together (Gregorian to Jalali with timezone conversion)
# Input: 2025-12-20 12:00:00 (UTC)
# Output: 1404/09/29 15:30:00 (Jalali calendar, Asia/Tehran timezone)
date-converter.sh "2025-12-20 12:00:00" --to jalali --from-timezone UTC --to-timezone Asia/Tehran

# Convert calendar and timezone (Jalali to Gregorian with timezone conversion)
# Input: 1404-09-29 15:30:00 (Jalali, Asia/Tehran)
# Output: 2025/12/20 12:00:00 (Gregorian, UTC)
date-converter.sh "1404-09-29 15:30:00" --date-format jalali --to gregorian --from-timezone Asia/Tehran --to-timezone UTC
```

### Examples

[](#examples)

**Direct execution:**

```
# Convert Gregorian to Jalali
date-converter.sh "2025-12-20" --to jalali --format-output Y/m/d

# Convert Jalali to Gregorian
date-converter.sh "1403-10-01" --date-format jalali --to gregorian

# Convert with custom input format
date-converter.sh "20/12/2025" --format-input "d/m/Y" --to jalali

# Convert with timezone (backward compatibility)
date-converter.sh "2025-12-20 12:00:00" --timezone Asia/Tehran

# Convert timezone from one timezone to another
date-converter.sh "2025-12-20 12:00:00" --from-timezone UTC --to-timezone Asia/Tehran --format-output "Y/m/d H:i:s"

# Convert timezone from London to Afghanistan
date-converter.sh "2025-12-20 12:00:00" --from-timezone Europe/London --to-timezone Asia/Kabul --format-output "Y/m/d H:i:s"

# Convert timezone from Brazil to Tehran
date-converter.sh "2025-12-20 12:00:00" --from-timezone America/Sao_Paulo --to-timezone Asia/Tehran --format-output "Y/m/d H:i:s"

# Convert calendar and timezone together (Gregorian to Jalali with timezone conversion)
date-converter.sh "2025-12-20 12:00:00" --to jalali --from-timezone UTC --to-timezone Asia/Tehran --format-output "Y/m/d H:i:s"

# Convert calendar and timezone (Jalali to Gregorian with timezone conversion)
date-converter.sh "1404-09-29 15:30:00" --date-format jalali --to gregorian --from-timezone Asia/Tehran --to-timezone UTC --format-output "Y/m/d H:i:s"
```

**Using Composer alias:**

```
# Convert Gregorian to Jalali
composer date-convert -- "2025-12-20" --to jalali --format-output Y/m/d

# Convert Jalali to Gregorian
composer date-convert -- "1403-10-01" --date-format jalali --to gregorian

# Convert with custom input format
composer date-convert -- "20/12/2025" --format-input "d/m/Y" --to jalali

# Convert timezone (backward compatibility)
composer date-convert -- "2025-12-20 12:00:00" --timezone Asia/Tehran

# Convert timezone from UTC to Asia/Tehran
composer date-convert -- "2025-12-20 12:00:00" --from-timezone UTC --to-timezone Asia/Tehran --format-output "Y/m/d H:i:s"

# Convert timezone from London to Afghanistan
composer date-convert -- "2025-12-20 12:00:00" --from-timezone Europe/London --to-timezone Asia/Kabul --format-output "Y/m/d H:i:s"

# Convert timezone from Brazil to Tehran
composer date-convert -- "2025-12-20 12:00:00" --from-timezone America/Sao_Paulo --to-timezone Asia/Tehran --format-output "Y/m/d H:i:s"

# Convert calendar and timezone together
composer date-convert -- "2025-12-20 12:00:00" --to jalali --from-timezone UTC --to-timezone Asia/Tehran --format-output "Y/m/d H:i:s"
```

License
-------

[](#license)

The MIT License (MIT). Please see [License File](https://github.com/jobmetric/multi-calendar/blob/master/LICENCE.md) for more information.

Contributing
------------

[](#contributing)

Thank you for considering contributing to the Laravel Multi Calendar! The contribution guide can be found in the [CONTRIBUTING.md](https://github.com/jobmetric/multi-calendar/blob/master/CONTRIBUTING.md).

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance55

Moderate activity, may be stable

Popularity17

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 60.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~19 days

Recently: every ~3 days

Total

8

Last Release

180d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b00d08bd4b0b765ee2d33719a535e6cb49c04fb945078a0809d5c05e6f16ee96?d=identicon)[majidmohammadian](/maintainers/majidmohammadian)

---

Top Contributors

[![MajidMohammadian](https://avatars.githubusercontent.com/u/2099965?v=4)](https://github.com/MajidMohammadian "MajidMohammadian (17 commits)")[![Bagheri-Matin](https://avatars.githubusercontent.com/u/239607447?v=4)](https://github.com/Bagheri-Matin "Bagheri-Matin (11 commits)")

---

Tags

laravelpackagecalendardate-conversionjobmetricdate-formattingmulti-calendar

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/jobmetric-multi-calendar/health.svg)

```
[![Health](https://phpackages.com/badges/jobmetric-multi-calendar/health.svg)](https://phpackages.com/packages/jobmetric-multi-calendar)
```

###  Alternatives

[laraveljutsu/zap

A flexible, performant, and developer-friendly schedule management system for Laravel

1.5k97.9k1](/packages/laraveljutsu-zap)[creasi/laravel-nusa

A Laravel package that aim to provide Indonesia' Administrative Data

997.7k2](/packages/creasi-laravel-nusa)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)