Download the PHP package picobaz/jalaliflow without Composer

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

• Features
• Requirements
• Installation
• Configuration
• Usage
  • Converting Dates
  • Adding Dates
  • Subtracting Dates
  • Calculating Differences
  • Validating Jalali Dates
  • Checking Holidays
  • Managing Events
  • Eloquent Trait
  • Artisan Command
• Advanced Usage
• Contributing
• License

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

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

Installation

1. Install the package via Composer:

2. Publish the configuration file (optional) to customize holidays:

   This will create a config/jalaliflow.php file.

3. Publish and run the migration (required for event scheduling):

   This creates the jalali_events table for storing scheduled events.

4. (Optional) Add the facade to config/app.php (if not auto-registered):

Configuration

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

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

Usage

Converting Dates

Convert between Gregorian and Jalali calendars using the JalaliFlow facade.

Adding Dates

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

Subtracting Dates

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

Calculating Differences

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

Validating Jalali Dates

Check if a Jalali date is valid.

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.

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.

• Check if a date is a holiday: Determine if a specific Jalali date is a holiday (official or custom).

• Add a custom holiday: Add your own holidays to the calendar, such as company events or local celebrations.

• 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).

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

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.

• Calculate Next Run Date: Use getNextRunDate($currentDate, $frequency) to calculate the next execution date.

• Run Scheduled Events: Execute scheduled events with the Artisan command:

• 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:

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

  Ensure the Laravel Scheduler is running:

  Or configure a cron job:

Eloquent Trait

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

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

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.

• Convert from Hijri date: Convert a Hijri date to Gregorian or Jalali format.

• Check for Islamic holidays: Determine if a date is a major Islamic holiday (e.g., Ashura, Eid al-Fitr).

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

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.

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

List holidays for a specific Jalali year:

Output:

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

Override the default format in your code or configuration:

Contributing

We welcome contributions! To contribute:

1. Fork the repository at https://github.com/PicoBaz/JalaliFlow.
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

JalaliFlow is open-source software licensed under the MIT License.

Support: For questions or issues, create a GitHub issue at https://github.com/PicoBaz/JalaliFlow/issues or contact us at [email protected].