Download the PHP package pulseline/jalali-events without Composer

Features

Jalali Events provides a simple API for working with the Iranian calendar in Laravel applications.

• Fetch complete Jalali calendar years
• Store Iranian events and occasions
• Detect official holidays
• Detect weekends separately from official holidays
• Query individual Jalali dates
• Retrieve all events for a date
• Query arbitrary date ranges
• Count holidays within a range
• Synchronize calendar data from time.ir
• Automatic scheduled synchronization
• Database storage
• JSON storage
• PostgreSQL compatible
• MySQL and MariaDB compatible
• SQLite compatible
• Laravel auto-discovery

Installation

Install the package using Composer:

Laravel will automatically discover the package service provider.

Run the package migrations:

Then synchronize the current Jalali year:

Or synchronize a specific year:

Quick Start

The package provides the JalaliEvents facade.

Get information about a Jalali date:

Example result:

Check Whether a Date Is a Holiday

Returns:

Get Events for a Date

Example:

A single date can contain multiple events.

Query a Date Range

This returns all calendar days between the two supplied Jalali dates.

Holidays in a Date Range

Count Holidays

Calendar Synchronization

Synchronize a specific Jalali year:

Synchronize the current Jalali year:

Synchronization downloads calendar data from the configured upstream source and stores the normalized result locally.

Application queries do not request data from time.ir.

The normal flow is:

This means the application queries its own local storage instead of calling the upstream website for every request.

Storage

Jalali Events supports two storage drivers:

• Database
• JSON

Database Storage

Database storage is the default:

The package creates two tables:

The jalali_calendar_days table stores one record for each calendar day.

The jalali_events table supports multiple events for each day.

PostgreSQL, MySQL, MariaDB and SQLite

By default, Jalali Events uses the Laravel application's default database connection.

For example, if the Laravel application uses PostgreSQL:

Jalali Events will store its tables in the same PostgreSQL database.

No additional configuration is required.

The same approach applies when the main Laravel project uses MySQL, MariaDB, or SQLite.

Dedicated Database Connection

Calendar data can optionally be stored using a separate Laravel database connection.

Then define the jalali connection inside:

Example:

JSON Storage

To use JSON instead of a database:

The default JSON file is stored at:

Publishing Configuration

Publish the package configuration:

This creates:

Configuration

Available environment variables:

Automatic Updates

Automatic synchronization is enabled by default:

Available frequencies:

The default is:

Jalali Events schedules the following command automatically:

The Laravel scheduler must be configured on the host application.

A typical cron entry is:

SSL Verification

SSL verification is enabled by default:

Disabling SSL verification is not recommended in production.

If the development environment uses an internal Certificate Authority or SSL inspection proxy, configure PHP and cURL with the appropriate CA certificate instead of disabling SSL verification.

Calendar Source

The default upstream calendar source is:

The source layer is separated from the rest of the package architecture so alternative calendar providers can be implemented in future versions without changing the public API.

The package dynamically resolves the Next.js Server Action used by the upstream calendar service instead of relying on a permanently hard-coded action identifier.

Since time.ir is an external service, changes to its internal implementation may require a package update.

Architecture

Testing

Install development dependencies:

Run the complete test suite:

or:

Validate Composer metadata:

Requirements

• PHP 8.3+
• Laravel / Illuminate 13.x
• Composer
• PostgreSQL, MySQL, MariaDB, or SQLite
• Internet access during calendar synchronization

The application does not require internet access when reading previously synchronized calendar data.

Contributing

Contributions are welcome.

1. Fork the repository.
2. Create a feature branch.
3. Make the required changes.
4. Add or update tests where appropriate.
5. Run the complete test suite.
6. Submit a pull request.

Repository:

Issues

Bug reports and feature requests can be submitted through GitHub Issues:

Security

For security-related issues, please avoid publishing sensitive information in a public issue.

Contact:

Author

Farzin Bidokhti

GitHub: @farzinbidokhti

Jalali Events is developed and maintained under Pulseline:

github.com/Pulselineir

License

Jalali Events is open-source software licensed under the MIT License.