PHPackages                             picobaz/jalaliflow - 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. [Localization & i18n](/categories/localization)
4. /
5. picobaz/jalaliflow

ActiveLibrary[Localization & i18n](/categories/localization)

picobaz/jalaliflow
==================

A Laravel package for advanced Jalali (Persian) calendar management

1.0.8(11mo ago)1515MITPHPPHP ^8.1

Since May 14Pushed 8mo ago1 watchersCompare

[ Source](https://github.com/PicoBaz/jalaliflow)[ Packagist](https://packagist.org/packages/picobaz/jalaliflow)[ RSS](/packages/picobaz-jalaliflow/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (5)Versions (7)Used By (0)

[![Latest Version on Packagist](https://camo.githubusercontent.com/ff23d6176827bc27551eb9a24ba092ecbd52bed242f8d341a5cda4b9eeb1d591/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7069636f62617a2f6a616c616c69666c6f772e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/picobaz/jalaliflow)[![Total Downloads](https://camo.githubusercontent.com/cca84e51b3a1b6d9d1c21ba26e1074cd6217dd2920eddb6463c6af9e46f6b06d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7069636f62617a2f6a616c616c69666c6f772e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/picobaz/jalaliflow)[![License](https://camo.githubusercontent.com/35f09210cfea2cab748817f8352134a59983091f44870cc18f301ad305b2aa17/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7069636f62617a2f6a616c616c69666c6f772e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/picobaz/jalaliflow)

JalaliFlow Documentation
========================

[](#jalaliflow-documentation)

**JalaliFlow** is a powerful Laravel package designed to handle Persian (Jalali) calendar operations with ease. It provides advanced date conversion, holiday management, and event scheduling, seamlessly integrated with Laravel’s ecosystem. With support for Jalali and Gregorian calendars, holiday checking, and automated event scheduling, JalaliFlow is ideal for projects targeting Persian-speaking audiences.

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
    - [Converting Dates](#converting-dates)
    - [Adding Dates](#adding-dates)
    - [Subtracting Dates](#subtracting-dates)
    - [Calculating Differences](#calculating-differences)
    - [Validating Jalali Dates](#validating-jalali-dates)
    - [Checking Holidays](#checking-holidays)
    - [Managing Events](#managing-events)
    - [Eloquent Trait](#eloquent-trait)
    - [Artisan Command](#artisan-command)
- [Advanced Usage](#advanced-usage)
- [Contributing](#contributing)
- [License](#license)

Features
--------

[](#features)

- **Date Conversion**: Convert between Jalali and Gregorian calendars with customizable formats.
- **Date Manipulation**: Add or subtract days, weeks, months, or years, respecting Jalali calendar rules.
- **Holiday Management**: Check official Persian holidays with a preloaded list.
- **Event Scheduling**: Schedule events to run daily, weekly, monthly, or yearly with database persistence.
- **Laravel Integration**:
    - Eloquent Trait for automatic date conversion in models.
    - Artisan commands for listing holidays and running scheduled events.
- **Validation**: Validate Jalali dates for accuracy.
- **Configurable**: Customize holidays and settings via a configuration file.
- **Extensible**: Future support for external APIs (e.g., Google Calendar) planned.

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Laravel 9.0, 10.0, 11.0, or 12.0
- Composer

Installation
------------

[](#installation)

1. Install the package via Composer:

    ```
    composer require picobaz/jalaliflow
    ```
2. Publish the configuration file (optional) to customize holidays:

    ```
    php artisan vendor:publish --tag=jalaliflow
    ```

    This will create a `config/jalaliflow.php` file.
3. Publish and run the migration (required for event scheduling):

    ```
    php artisan vendor:publish --tag=jalaliflow
    php artisan migrate
    ```

    This creates the `jalali_events` table for storing scheduled events.
4. (Optional) Add the facade to `config/app.php` (if not auto-registered):

    ```
    'aliases' => [
        'JalaliFlow' => PicoBaz\JalaliFlow\Facades\JalaliFlow::class,
    ],
    ```

Configuration
-------------

[](#configuration)

The `config/jalaliflow.php` file allows you to customize the package’s behavior. Default settings include:

```
return [
    'date_format' => 'Y/m/d', // Default Jalali date format
    'locale' => 'fa',        // Default language for date display
    'timezone' => 'Asia/Tehran', // Default timezone
    'holidays' => [
        '1404/01/01' => 'Norouz',
        '1404/01/02' => 'Norouz',
        // Add more holidays here
    ],
];
```

Modify these settings to change the date format, locale, timezone, or holiday list.

Usage
-----

[](#usage)

### Converting Dates

[](#converting-dates)

Convert between Gregorian and Jalali calendars using the `JalaliFlow` facade.

```
use PicoBaz\JalaliFlow\Facades\JalaliFlow;

// Convert Gregorian to Jalali
echo JalaliFlow::toJalali('2025-05-14'); // Output: 1404/02/24

// Convert Jalali to Gregorian
echo JalaliFlow::toGregorian('1404/02/24'); // Output: 2025-05-14

// Custom format
echo JalaliFlow::toJalali('2025-05-14', 'Y-m-d'); // Output: 1404-02-24
```

### Adding Dates

[](#adding-dates)

Add days, weeks, months, or years to a Jalali date, respecting variable month lengths and leap years.

```
echo JalaliFlow::addDay('1404/02/24', 5);   // Output: 1404/02/29
echo JalaliFlow::addWeek('1404/02/24', 2);  // Output: 1404/03/08
echo JalaliFlow::addMonth('1404/02/24', 1); // Output: 1404/03/24
echo JalaliFlow::addYear('1404/02/24', 1);  // Output: 1405/02/24
```

### Subtracting Dates

[](#subtracting-dates)

Subtract days, weeks, months, or years from a Jalali date.

```
echo JalaliFlow::subDay('1404/02/24', 5);   // Output: 1404/02/19
echo JalaliFlow::subWeek('1404/02/24', 2);  // Output: 1404/02/10
echo JalaliFlow::subMonth('1404/02/24', 1); // Output: 1404/01/24
echo JalaliFlow::subYear('1404/02/24', 1);  // Output: 1403/02/24
```

### Calculating Differences

[](#calculating-differences)

Calculate the difference between two Jalali dates in days, weeks, months, or years.

```
echo JalaliFlow::diff('1404/02/24', '1405/01/01', 'day');   // Output: ~312
echo JalaliFlow::diff('1404/02/24', '1405/01/01', 'week');  // Output: ~44.57
echo JalaliFlow::diff('1404/02/24', '1405/01/01', 'month'); // Output: ~10.3
echo JalaliFlow::diff('1404/02/24', '1405/01/01', 'year');  // Output: ~0.86
```

### Validating Jalali Dates

[](#validating-jalali-dates)

Check if a Jalali date is valid.

```
echo JalaliFlow::validateJalaliDate('1404/02/24') ? 'Valid' : 'Invalid'; // Output: Valid
echo JalaliFlow::validateJalaliDate('1404/12/31') ? 'Valid' : 'Invalid'; // Output: Invalid
```

### Displaying Relative Jalali Dates

[](#displaying-relative-jalali-dates)

The `toRelativeJalali` method allows you to convert a Gregorian date to a relative Jalali string, such as "today", "yesterday", or "3 days ago". This is useful for user-friendly date displays in applications like chat or notification systems.

```
use PicoBaz\JalaliFlow\Facades\JalaliFlow;

// Assuming today is 1404/02/24 (2025-05-22)
echo JalaliFlow::toRelativeJalali('2025-05-22'); // Output: امروز
echo JalaliFlow::toRelativeJalali('2025-05-21'); // Output: دیروز
echo JalaliFlow::toRelativeJalali('2025-05-24'); // Output: ۲ روز بعد
echo JalaliFlow::toRelativeJalali('2025-05-19'); // Output: ۳ روز پیش
echo JalaliFlow::toRelativeJalali('2025-05-19', 'Asia/Tehran', 'en'); // Output: 3 days ago
```

### Managing Holidays

[](#managing-holidays)

`JalaliFlow` provides powerful methods to manage official and custom holidays in the Jalali calendar. These are perfect for scheduling, reservation systems, or any application needing to track holidays and working days.

- **Get holidays for a specific year:**Retrieve a list of official and custom holidays for a given Jalali year.

    ```
    use PicoBaz\JalaliFlow\Facades\JalaliFlow;

    $holidays = JalaliFlow::getHolidays(1404);
    foreach ($holidays as $date => $description) {
        echo "$date: $description\n";
    }
    // Example output:
    // 1404/01/01: نوروز
    // 1404/01/02: نوروز
    // 1404/01/03: نوروز
    // 1404/01/04: نوروز
    // 1404/01/13: روز طبیعت
    // 1404/12/29: روز ملی شدن صنعت نفت
    ```
- **Check if a date is a holiday:**Determine if a specific Jalali date is a holiday (official or custom).

    ```
    use PicoBaz\JalaliFlow\Facades\JalaliFlow;

    try {
        $date = '1404/01/01';
        echo JalaliFlow::isHoliday($date) ? "$date is a holiday" : "$date is not a holiday";
        // Output: 1404/01/01 is a holiday

        $date = '1404/02/24';
        echo JalaliFlow::isHoliday($date) ? "$date is a holiday" : "$date is not a holiday";
        // Output: 1404/02/24 is not a holiday
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage();
    }
    ```
- **Add a custom holiday:**Add your own holidays to the calendar, such as company events or local celebrations.

    ```
    use PicoBaz\JalaliFlow\Facades\JalaliFlow;

    try {
        JalaliFlow::addCustomHoliday('1404/06/15', 'Company Anniversary');
        echo JalaliFlow::isHoliday('1404/06/15') ? 'Custom holiday added' : 'Failed to add holiday';
        // Output: Custom holiday added

        // Verify in holidays list
        $holidays = JalaliFlow::getHolidays(1404);
        echo isset($holidays['1404/06/15']) ? "Found: {$holidays['1404/06/15']}" : 'Not found';
        // Output: Found: Company Anniversary
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage();
    }
    ```
- **Check if a date is a working day:**Determine if a date is a working day (not a holiday and not a Friday, the official weekend in Iran).

    ```
    use PicoBaz\JalaliFlow\Facades\JalaliFlow;

    try {
        $date = '1404/02/24';
        echo JalaliFlow::isWorkingDay($date) ? "$date is a working day" : "$date is not a working day";
        // Output: 1404/02/24 is a working day (assuming it's not a Friday)

        $date = '1404/01/01';
        echo JalaliFlow::isWorkingDay($date) ? "$date is a working day" : "$date is not a working day";
        // Output: 1404/01/01 is not a working day (Nowruz holiday)
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage();
    }
    ```

**Note:** The `isWorkingDay` method considers Fridays as non-working days, as they are the official weekend in Iran. Ensure the date is in `Y/m/d` format (e.g., `1404/02/24`).

### Managing Events

[](#managing-events)

Schedule events to run daily, weekly, monthly, or yearly with database persistence.

- **Create an Event:**Use `createEvent($name, $frequency, $startDate, $action)` to schedule an event.

    ```
    use PicoBaz\JalaliFlow\Facades\JalaliFlow;
    use Illuminate\Support\Facades\DB;

    // Example: Add a daily record to the database
    JalaliFlow::createEvent(
        name: 'Add Daily Record',
        frequency: 'daily',
        startDate: '1404/02/24',
        action: function () {
            DB::table('records')->insert(['created_at' => now()]);
        }
    );

    // Example: Call a class method monthly
    JalaliFlow::createEvent(
        name: 'Monthly Report',
        frequency: 'monthly',
        startDate: '1404/02/24',
        action: 'App\Services\ReportService@generateMonthly'
    );
    ```
- **Calculate Next Run Date:**Use `getNextRunDate($currentDate, $frequency)` to calculate the next execution date.

    ```
    echo JalaliFlow::getNextRunDate('1404/02/24', 'daily');   // Output: 1404/02/25
    echo JalaliFlow::getNextRunDate('1404/02/24', 'weekly');  // Output: 1404/03/01
    echo JalaliFlow::getNextRunDate('1404/02/24', 'monthly'); // Output: 1404/03/24
    echo JalaliFlow::getNextRunDate('1404/02/24', 'yearly');  // Output: 1405/02/24
    ```
- **Run Scheduled Events:**Execute scheduled events with the Artisan command:

    ```
    php artisan jalali:run-events
    ```
- **Setup Scheduler:**To run events automatically, configure the Laravel Scheduler to execute the `jalali:run-events` command daily.

    **For Laravel 11 and 12:**Add the following to `routes/console.php`:

    ```
    use Illuminate\Support\Facades\Schedule;

    Schedule::command('jalali:run-events')->daily();
    ```

    **For Laravel 9 and 10:**Add the following to `app/Console/Kernel.php`:

    ```
    protected function schedule(Schedule $schedule)
    {
        $schedule->command('jalali:run-events')->daily();
    }
    ```

    Ensure the Laravel Scheduler is running:

    ```
    php artisan schedule:work
    ```

    Or configure a cron job:

    ```
    * * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
    ```

### Eloquent Trait

[](#eloquent-trait)

Use the `JalaliDate` trait to automatically convert dates in Eloquent models.

```
use Illuminate\Database\Eloquent\Model;
use PicoBaz\JalaliFlow\Traits\JalaliDate;

class Post extends Model
{
    use JalaliDate;
}
```

Access the `jalali_date` attribute to get the `created_at` date in Jalali format:

```
$post = Post::first();
echo $post->jalali_date; // Output: 1404/02/24
```

### Managing Hijri (Islamic) Dates

[](#managing-hijri-islamic-dates)

`JalaliFlow` supports conversion to and from Hijri (Islamic) dates, as well as checking for major Islamic holidays. This is ideal for religious or cultural applications.

- **Convert to Hijri date:**Convert a Gregorian or Jalali date to a Hijri date.

    ```
    use PicoBaz\JalaliFlow\Facades\JalaliFlow;

    try {
        echo JalaliFlow::toHijri('2025-05-22', 'gregorian', 'Y/m/d');
        // Output: 1446/11/14
        echo JalaliFlow::toHijri('1404/02/24', 'jalali', 'Y/m/d');
        // Output: 1446/11/14
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage();
    }
    ```
- **Convert from Hijri date:**Convert a Hijri date to Gregorian or Jalali format.

    ```
    use PicoBaz\JalaliFlow\Facades\JalaliFlow;

    try {
        echo JalaliFlow::fromHijri('1446/11/14', 'gregorian', 'Y-m-d');
        // Output: 2025-05-22
        echo JalaliFlow::fromHijri('1446/11/14', 'jalali', 'Y/m/d');
        // Output: 1404/02/24
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage();
    }
    ```
- **Check for Islamic holidays:**Determine if a date is a major Islamic holiday (e.g., Ashura, Eid al-Fitr).

    ```
    use PicoBaz\JalaliFlow\Facades\JalaliFlow;

    try {
        $date = '1404/04/25'; // Approximate date for Ashura 1446
        echo JalaliFlow::isIslamicHoliday($date, 'jalali') ? "$date is an Islamic holiday" : "$date is not an Islamic holiday";
        // Output: 1404/04/25 is an Islamic holiday (if Ashura)

        $date = '1404/02/24';
        echo JalaliFlow::isIslamicHoliday($date, 'jalali') ? "$date is an Islamic holiday" : "$date is not an Islamic holiday";
        // Output: 1404/02/24 is not an Islamic holiday
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage();
    }
    ```

**Note:** Hijri date conversions are approximate due to the simplified algorithm. For precise conversions, consider integrating with an external API. Dates must be in `Y/m/d` format for Hijri and Jalali, or `Y-m-d` for Gregorian.

### Calculating Working Days Between Dates

[](#calculating-working-days-between-dates)

`JalaliFlow` provides a method to calculate the number of working days (excluding holidays and Fridays) between two Jalali dates. This is ideal for payroll systems, project management, or scheduling applications.

- **Calculate working days between two Jalali dates:**Returns the number of working days, including the start date but excluding the end date. ```
    use PicoBaz\JalaliFlow\Facades\JalaliFlow;

    try {
        $days = JalaliFlow::workingDaysBetween('1404/02/20', '1404/02/27');
        echo "Working days: $days";
        // Output: Working days: 5 (assuming no holidays, excluding Friday)

        $days = JalaliFlow::workingDaysBetween('1404/01/01', '1404/01/07');
        echo "Working days: $days";
        // Output: Working days: 2 (excluding Nowruz holidays and Friday)

        $days = JalaliFlow::workingDaysBetween('1404/02/24', '1404/02/24');
        echo "Working days: $days";
        // Output: Working days: 0 (same start and end date)
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage();
    }
    ```

**Note:** Dates must be in `Y/m/d` format. The method uses `isWorkingDay` to exclude holidays and Fridays (the official weekend in Iran). Ensure holiday data is up-to-date for accurate results.

### Artisan Command

[](#artisan-command)

List holidays for a specific Jalali year:

```
php artisan jalali:holidays 1404
```

Output:

```
Holidays for 1404:
1404/01/01: Norouz
1404/01/02: Norouz

```

Advanced Usage
--------------

[](#advanced-usage)

> **Note**: Some advanced features (e.g., Google Calendar integration, dynamic holiday fetching) are planned for future releases and not yet implemented.

### Custom Date Formats

[](#custom-date-formats)

Override the default format in your code or configuration:

```
echo JalaliFlow::toJalali('2025-05-14', 'Y-m-d H:i:s'); // Output: 1404-02-24 00:00:00
```

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

[](#contributing)

We welcome contributions! To contribute:

1. Fork the repository at .
2. Create a feature branch (`git checkout -b feature/YourFeature`).
3. Commit your changes (`git commit -m "Add YourFeature"`).
4. Push to the branch (`git push origin feature/YourFeature`).
5. Open a pull request.

Please include tests and update the documentation for new features.

License
-------

[](#license)

JalaliFlow is open-source software licensed under the [MIT License](LICENSE).

---

**Support**: For questions or issues, create a GitHub issue at  or contact us at .

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance55

Moderate activity, may be stable

Popularity13

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~1 days

Total

6

Last Release

359d ago

PHP version history (2 changes)v1.0.3PHP ^8.0

v1.0.4PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/59c9ff1dfbbfe06642f32c2181c3b8af7e0bc190f3625d761f6199809b21b330?d=identicon)[PicoBaz](/maintainers/PicoBaz)

---

Top Contributors

[![PicoBaz](https://avatars.githubusercontent.com/u/89545937?v=4)](https://github.com/PicoBaz "PicoBaz (28 commits)")

---

Tags

datetimeevent-schedulerholiday-managerjalalilaravellocalizationpersian-calendarphplaraveleventsdatecalendarJalalipersian

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/picobaz-jalaliflow/health.svg)

```
[![Health](https://phpackages.com/badges/picobaz-jalaliflow/health.svg)](https://phpackages.com/packages/picobaz-jalaliflow)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[fumeapp/modeltyper

Generate TypeScript interfaces from Laravel Models

196277.9k](/packages/fumeapp-modeltyper)[miladr/jalali

This Package helps developers to easily work with Jalali (Shamsi or Iranian) dates in Laravel 4 applications, based on Jalali (Shamsi) DateTime class. This Package is based on a Laravel 3 bundle sallar/laravel-jdate by Sallar Kaboli.

479.6k2](/packages/miladr-jalali)[kerigard/laravel-lang-ru

Ru lang for Laravel

2116.8k](/packages/kerigard-laravel-lang-ru)[highsolutions/laravel-translation-manager

Manage Laravel Translations

1518.8k](/packages/highsolutions-laravel-translation-manager)[amendozaaguiar/laravel-lat-es

Archivos de traducción al español latinoamericano para Laravel (auth, pagination, passwords, validation).

198.5k](/packages/amendozaaguiar-laravel-lat-es)

PHPackages © 2026

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