{"id":28285570,"url":"https://github.com/picobaz/jalaliflow","last_synced_at":"2026-03-02T13:03:01.231Z","repository":{"id":293335038,"uuid":"983722603","full_name":"PicoBaz/jalaliflow","owner":"PicoBaz","description":"JalaliFlow: A robust Laravel package for Persian (Jalali) calendar operations. Seamlessly convert dates, manage holidays, and schedule events with Laravel integration. Perfect for Persian apps and localization!","archived":false,"fork":false,"pushed_at":"2025-08-27T11:07:31.000Z","size":51,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-27T20:27:24.436Z","etag":null,"topics":["datetime","event-scheduler","holiday-manager","jalali","laravel","localization","persian-calendar","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PicoBaz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-14T20:16:13.000Z","updated_at":"2025-08-27T11:15:13.000Z","dependencies_parsed_at":"2025-05-14T20:45:56.562Z","dependency_job_id":"10cac612-7d63-495e-afa5-a197d69ec0b9","html_url":"https://github.com/PicoBaz/jalaliflow","commit_stats":null,"previous_names":["picobaz/jalaliflow"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/PicoBaz/jalaliflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PicoBaz%2Fjalaliflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PicoBaz%2Fjalaliflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PicoBaz%2Fjalaliflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PicoBaz%2Fjalaliflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PicoBaz","download_url":"https://codeload.github.com/PicoBaz/jalaliflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PicoBaz%2Fjalaliflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30003475,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T12:19:43.414Z","status":"ssl_error","status_checked_at":"2026-03-02T12:19:02.215Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["datetime","event-scheduler","holiday-manager","jalali","laravel","localization","persian-calendar","php"],"created_at":"2025-05-21T19:17:16.743Z","updated_at":"2026-03-02T13:03:01.197Z","avatar_url":"https://github.com/PicoBaz.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Latest Version on Packagist](https://img.shields.io/packagist/v/picobaz/jalaliflow.svg?style=flat-square)](https://packagist.org/packages/picobaz/jalaliflow)\n[![Total Downloads](https://img.shields.io/packagist/dt/picobaz/jalaliflow.svg?style=flat-square)](https://packagist.org/packages/picobaz/jalaliflow)\n[![License](https://img.shields.io/packagist/l/picobaz/jalaliflow.svg?style=flat-square)](https://packagist.org/packages/picobaz/jalaliflow)\n# JalaliFlow Documentation\n\n**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.\n\n## Table of Contents\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n    - [Converting Dates](#converting-dates)\n    - [Adding Dates](#adding-dates)\n    - [Subtracting Dates](#subtracting-dates)\n    - [Calculating Differences](#calculating-differences)\n    - [Validating Jalali Dates](#validating-jalali-dates)\n    - [Checking Holidays](#checking-holidays)\n    - [Managing Events](#managing-events)\n    - [Eloquent Trait](#eloquent-trait)\n    - [Artisan Command](#artisan-command)\n- [Advanced Usage](#advanced-usage)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n- **Date Conversion**: Convert between Jalali and Gregorian calendars with customizable formats.\n- **Date Manipulation**: Add or subtract days, weeks, months, or years, respecting Jalali calendar rules.\n- **Holiday Management**: Check official Persian holidays with a preloaded list.\n- **Event Scheduling**: Schedule events to run daily, weekly, monthly, or yearly with database persistence.\n- **Laravel Integration**:\n    - Eloquent Trait for automatic date conversion in models.\n    - Artisan commands for listing holidays and running scheduled events.\n- **Validation**: Validate Jalali dates for accuracy.\n- **Configurable**: Customize holidays and settings via a configuration file.\n- **Extensible**: Future support for external APIs (e.g., Google Calendar) planned.\n\n## Requirements\n- PHP 8.1 or higher\n- Laravel 9.0, 10.0, 11.0, or 12.0\n- Composer\n\n## Installation\n1. Install the package via Composer:\n   ```bash\n   composer require picobaz/jalaliflow\n   ```\n\n2. Publish the configuration file (optional) to customize holidays:\n   ```bash\n   php artisan vendor:publish --tag=jalaliflow\n   ```\n   This will create a `config/jalaliflow.php` file.\n\n3. Publish and run the migration (required for event scheduling):\n   ```bash\n   php artisan vendor:publish --tag=jalaliflow\n   php artisan migrate\n   ```\n   This creates the `jalali_events` table for storing scheduled events.\n\n4. (Optional) Add the facade to `config/app.php` (if not auto-registered):\n   ```php\n   'aliases' =\u003e [\n       'JalaliFlow' =\u003e PicoBaz\\JalaliFlow\\Facades\\JalaliFlow::class,\n   ],\n   ```\n\n## Configuration\nThe `config/jalaliflow.php` file allows you to customize the package’s behavior. Default settings include:\n\n```php\nreturn [\n    'date_format' =\u003e 'Y/m/d', // Default Jalali date format\n    'locale' =\u003e 'fa',        // Default language for date display\n    'timezone' =\u003e 'Asia/Tehran', // Default timezone\n    'holidays' =\u003e [\n        '1404/01/01' =\u003e 'Norouz',\n        '1404/01/02' =\u003e 'Norouz',\n        // Add more holidays here\n    ],\n];\n```\n\nModify these settings to change the date format, locale, timezone, or holiday list.\n\n## Usage\n\n### Converting Dates\nConvert between Gregorian and Jalali calendars using the `JalaliFlow` facade.\n\n```php\nuse PicoBaz\\JalaliFlow\\Facades\\JalaliFlow;\n\n// Convert Gregorian to Jalali\necho JalaliFlow::toJalali('2025-05-14'); // Output: 1404/02/24\n\n// Convert Jalali to Gregorian\necho JalaliFlow::toGregorian('1404/02/24'); // Output: 2025-05-14\n\n// Custom format\necho JalaliFlow::toJalali('2025-05-14', 'Y-m-d'); // Output: 1404-02-24\n```\n\n### Adding Dates\nAdd days, weeks, months, or years to a Jalali date, respecting variable month lengths and leap years.\n\n```php\necho JalaliFlow::addDay('1404/02/24', 5);   // Output: 1404/02/29\necho JalaliFlow::addWeek('1404/02/24', 2);  // Output: 1404/03/08\necho JalaliFlow::addMonth('1404/02/24', 1); // Output: 1404/03/24\necho JalaliFlow::addYear('1404/02/24', 1);  // Output: 1405/02/24\n```\n\n### Subtracting Dates\nSubtract days, weeks, months, or years from a Jalali date.\n\n```php\necho JalaliFlow::subDay('1404/02/24', 5);   // Output: 1404/02/19\necho JalaliFlow::subWeek('1404/02/24', 2);  // Output: 1404/02/10\necho JalaliFlow::subMonth('1404/02/24', 1); // Output: 1404/01/24\necho JalaliFlow::subYear('1404/02/24', 1);  // Output: 1403/02/24\n```\n\n### Calculating Differences\nCalculate the difference between two Jalali dates in days, weeks, months, or years.\n\n```php\necho JalaliFlow::diff('1404/02/24', '1405/01/01', 'day');   // Output: ~312\necho JalaliFlow::diff('1404/02/24', '1405/01/01', 'week');  // Output: ~44.57\necho JalaliFlow::diff('1404/02/24', '1405/01/01', 'month'); // Output: ~10.3\necho JalaliFlow::diff('1404/02/24', '1405/01/01', 'year');  // Output: ~0.86\n```\n\n### Validating Jalali Dates\nCheck if a Jalali date is valid.\n\n```php\necho JalaliFlow::validateJalaliDate('1404/02/24') ? 'Valid' : 'Invalid'; // Output: Valid\necho JalaliFlow::validateJalaliDate('1404/12/31') ? 'Valid' : 'Invalid'; // Output: Invalid\n```\n### Displaying Relative Jalali Dates\n\nThe `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.\n\n```php\nuse PicoBaz\\JalaliFlow\\Facades\\JalaliFlow;\n\n// Assuming today is 1404/02/24 (2025-05-22)\necho JalaliFlow::toRelativeJalali('2025-05-22'); // Output: امروز\necho JalaliFlow::toRelativeJalali('2025-05-21'); // Output: دیروز\necho JalaliFlow::toRelativeJalali('2025-05-24'); // Output: ۲ روز بعد\necho JalaliFlow::toRelativeJalali('2025-05-19'); // Output: ۳ روز پیش\necho JalaliFlow::toRelativeJalali('2025-05-19', 'Asia/Tehran', 'en'); // Output: 3 days ago\n```\n\n### Managing Holidays\n\n`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.\n\n- **Get holidays for a specific year:**\n  Retrieve a list of official and custom holidays for a given Jalali year.\n  ```php\n  use PicoBaz\\JalaliFlow\\Facades\\JalaliFlow;\n\n  $holidays = JalaliFlow::getHolidays(1404);\n  foreach ($holidays as $date =\u003e $description) {\n      echo \"$date: $description\\n\";\n  }\n  // Example output:\n  // 1404/01/01: نوروز\n  // 1404/01/02: نوروز\n  // 1404/01/03: نوروز\n  // 1404/01/04: نوروز\n  // 1404/01/13: روز طبیعت\n  // 1404/12/29: روز ملی شدن صنعت نفت\n  ```\n\n- **Check if a date is a holiday:**\n  Determine if a specific Jalali date is a holiday (official or custom).\n  ```php\n  use PicoBaz\\JalaliFlow\\Facades\\JalaliFlow;\n\n  try {\n      $date = '1404/01/01';\n      echo JalaliFlow::isHoliday($date) ? \"$date is a holiday\" : \"$date is not a holiday\";\n      // Output: 1404/01/01 is a holiday\n\n      $date = '1404/02/24';\n      echo JalaliFlow::isHoliday($date) ? \"$date is a holiday\" : \"$date is not a holiday\";\n      // Output: 1404/02/24 is not a holiday\n  } catch (Exception $e) {\n      echo \"Error: \" . $e-\u003egetMessage();\n  }\n  ```\n\n- **Add a custom holiday:**\n  Add your own holidays to the calendar, such as company events or local celebrations.\n  ```php\n  use PicoBaz\\JalaliFlow\\Facades\\JalaliFlow;\n\n  try {\n      JalaliFlow::addCustomHoliday('1404/06/15', 'Company Anniversary');\n      echo JalaliFlow::isHoliday('1404/06/15') ? 'Custom holiday added' : 'Failed to add holiday';\n      // Output: Custom holiday added\n\n      // Verify in holidays list\n      $holidays = JalaliFlow::getHolidays(1404);\n      echo isset($holidays['1404/06/15']) ? \"Found: {$holidays['1404/06/15']}\" : 'Not found';\n      // Output: Found: Company Anniversary\n  } catch (Exception $e) {\n      echo \"Error: \" . $e-\u003egetMessage();\n  }\n  ```\n\n- **Check if a date is a working day:**\n  Determine if a date is a working day (not a holiday and not a Friday, the official weekend in Iran).\n  ```php\n  use PicoBaz\\JalaliFlow\\Facades\\JalaliFlow;\n\n  try {\n      $date = '1404/02/24';\n      echo JalaliFlow::isWorkingDay($date) ? \"$date is a working day\" : \"$date is not a working day\";\n      // Output: 1404/02/24 is a working day (assuming it's not a Friday)\n\n      $date = '1404/01/01';\n      echo JalaliFlow::isWorkingDay($date) ? \"$date is a working day\" : \"$date is not a working day\";\n      // Output: 1404/01/01 is not a working day (Nowruz holiday)\n  } catch (Exception $e) {\n      echo \"Error: \" . $e-\u003egetMessage();\n  }\n  ```\n\n**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`).\n### Managing Events\nSchedule events to run daily, weekly, monthly, or yearly with database persistence.\n\n- **Create an Event:**\n  Use `createEvent($name, $frequency, $startDate, $action)` to schedule an event.\n  ```php\n  use PicoBaz\\JalaliFlow\\Facades\\JalaliFlow;\n  use Illuminate\\Support\\Facades\\DB;\n\n  // Example: Add a daily record to the database\n  JalaliFlow::createEvent(\n      name: 'Add Daily Record',\n      frequency: 'daily',\n      startDate: '1404/02/24',\n      action: function () {\n          DB::table('records')-\u003einsert(['created_at' =\u003e now()]);\n      }\n  );\n\n  // Example: Call a class method monthly\n  JalaliFlow::createEvent(\n      name: 'Monthly Report',\n      frequency: 'monthly',\n      startDate: '1404/02/24',\n      action: 'App\\Services\\ReportService@generateMonthly'\n  );\n  ```\n\n- **Calculate Next Run Date:**\n  Use `getNextRunDate($currentDate, $frequency)` to calculate the next execution date.\n  ```php\n  echo JalaliFlow::getNextRunDate('1404/02/24', 'daily');   // Output: 1404/02/25\n  echo JalaliFlow::getNextRunDate('1404/02/24', 'weekly');  // Output: 1404/03/01\n  echo JalaliFlow::getNextRunDate('1404/02/24', 'monthly'); // Output: 1404/03/24\n  echo JalaliFlow::getNextRunDate('1404/02/24', 'yearly');  // Output: 1405/02/24\n  ```\n\n- **Run Scheduled Events:**\n  Execute scheduled events with the Artisan command:\n  ```bash\n  php artisan jalali:run-events\n  ```\n\n- **Setup Scheduler:**\n  To run events automatically, configure the Laravel Scheduler to execute the `jalali:run-events` command daily.\n\n  **For Laravel 11 and 12:**\n  Add the following to `routes/console.php`:\n  ```php\n  use Illuminate\\Support\\Facades\\Schedule;\n\n  Schedule::command('jalali:run-events')-\u003edaily();\n  ```\n\n  **For Laravel 9 and 10:**\n  Add the following to `app/Console/Kernel.php`:\n  ```php\n  protected function schedule(Schedule $schedule)\n  {\n      $schedule-\u003ecommand('jalali:run-events')-\u003edaily();\n  }\n  ```\n\n  Ensure the Laravel Scheduler is running:\n  ```bash\n  php artisan schedule:work\n  ```\n  Or configure a cron job:\n  ```bash\n  * * * * * cd /path-to-your-project \u0026\u0026 php artisan schedule:run \u003e\u003e /dev/null 2\u003e\u00261\n  ```\n\n### Eloquent Trait\nUse the `JalaliDate` trait to automatically convert dates in Eloquent models.\n\n```php\nuse Illuminate\\Database\\Eloquent\\Model;\nuse PicoBaz\\JalaliFlow\\Traits\\JalaliDate;\n\nclass Post extends Model\n{\n    use JalaliDate;\n}\n```\n\nAccess the `jalali_date` attribute to get the `created_at` date in Jalali format:\n\n```php\n$post = Post::first();\necho $post-\u003ejalali_date; // Output: 1404/02/24\n```\n### Managing Hijri (Islamic) Dates\n\n`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.\n\n- **Convert to Hijri date:**\n  Convert a Gregorian or Jalali date to a Hijri date.\n  ```php\n  use PicoBaz\\JalaliFlow\\Facades\\JalaliFlow;\n\n  try {\n      echo JalaliFlow::toHijri('2025-05-22', 'gregorian', 'Y/m/d');\n      // Output: 1446/11/14\n      echo JalaliFlow::toHijri('1404/02/24', 'jalali', 'Y/m/d');\n      // Output: 1446/11/14\n  } catch (Exception $e) {\n      echo \"Error: \" . $e-\u003egetMessage();\n  }\n  ```\n\n- **Convert from Hijri date:**\n  Convert a Hijri date to Gregorian or Jalali format.\n  ```php\n  use PicoBaz\\JalaliFlow\\Facades\\JalaliFlow;\n\n  try {\n      echo JalaliFlow::fromHijri('1446/11/14', 'gregorian', 'Y-m-d');\n      // Output: 2025-05-22\n      echo JalaliFlow::fromHijri('1446/11/14', 'jalali', 'Y/m/d');\n      // Output: 1404/02/24\n  } catch (Exception $e) {\n      echo \"Error: \" . $e-\u003egetMessage();\n  }\n  ```\n\n- **Check for Islamic holidays:**\n  Determine if a date is a major Islamic holiday (e.g., Ashura, Eid al-Fitr).\n  ```php\n  use PicoBaz\\JalaliFlow\\Facades\\JalaliFlow;\n\n  try {\n      $date = '1404/04/25'; // Approximate date for Ashura 1446\n      echo JalaliFlow::isIslamicHoliday($date, 'jalali') ? \"$date is an Islamic holiday\" : \"$date is not an Islamic holiday\";\n      // Output: 1404/04/25 is an Islamic holiday (if Ashura)\n\n      $date = '1404/02/24';\n      echo JalaliFlow::isIslamicHoliday($date, 'jalali') ? \"$date is an Islamic holiday\" : \"$date is not an Islamic holiday\";\n      // Output: 1404/02/24 is not an Islamic holiday\n  } catch (Exception $e) {\n      echo \"Error: \" . $e-\u003egetMessage();\n  }\n  ```\n\n**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.\n\n### Calculating Working Days Between Dates\n\n`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.\n\n- **Calculate working days between two Jalali dates:**\n  Returns the number of working days, including the start date but excluding the end date.\n  ```php\n  use PicoBaz\\JalaliFlow\\Facades\\JalaliFlow;\n\n  try {\n      $days = JalaliFlow::workingDaysBetween('1404/02/20', '1404/02/27');\n      echo \"Working days: $days\";\n      // Output: Working days: 5 (assuming no holidays, excluding Friday)\n\n      $days = JalaliFlow::workingDaysBetween('1404/01/01', '1404/01/07');\n      echo \"Working days: $days\";\n      // Output: Working days: 2 (excluding Nowruz holidays and Friday)\n\n      $days = JalaliFlow::workingDaysBetween('1404/02/24', '1404/02/24');\n      echo \"Working days: $days\";\n      // Output: Working days: 0 (same start and end date)\n  } catch (Exception $e) {\n      echo \"Error: \" . $e-\u003egetMessage();\n  }\n  ```\n\n**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.\n### Artisan Command\nList holidays for a specific Jalali year:\n\n```bash\nphp artisan jalali:holidays 1404\n```\n\nOutput:\n```\nHolidays for 1404:\n1404/01/01: Norouz\n1404/01/02: Norouz\n```\n\n## Advanced Usage\n\u003e **Note**: Some advanced features (e.g., Google Calendar integration, dynamic holiday fetching) are planned for future releases and not yet implemented.\n\n### Custom Date Formats\nOverride the default format in your code or configuration:\n\n```php\necho JalaliFlow::toJalali('2025-05-14', 'Y-m-d H:i:s'); // Output: 1404-02-24 00:00:00\n```\n\n## Contributing\nWe welcome contributions! To contribute:\n1. Fork the repository at [https://github.com/PicoBaz/JalaliFlow](https://github.com/PicoBaz/JalaliFlow).\n2. Create a feature branch (`git checkout -b feature/YourFeature`).\n3. Commit your changes (`git commit -m \"Add YourFeature\"`).\n4. Push to the branch (`git push origin feature/YourFeature`).\n5. Open a pull request.\n\nPlease include tests and update the documentation for new features.\n\n## License\nJalaliFlow is open-source software licensed under the [MIT License](LICENSE).\n\n---\n\n**Support**: For questions or issues, create a GitHub issue at [https://github.com/PicoBaz/JalaliFlow/issues](https://github.com/PicoBaz/JalaliFlow/issues) or contact us at [picobaz3@gmail.com](mailto:picobaz3@gmail.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpicobaz%2Fjalaliflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpicobaz%2Fjalaliflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpicobaz%2Fjalaliflow/lists"}