repository·master·Indexed 21 days ago
https://github.com/morilog/jalaliA high-performance PHP library for working with the Jalali (Persian) solar calendar. It provides tools for calendar conversion, date manipulation, and comparison with a focus on immutability. Key features include a human-readable API, the Jalalian class for date-time manipulation, and CalendarUtils for Gregorian-Jalali conversions and validation. Requires PHP >= 7.1.
The morilog/jalali library provides a high-performance implementation of the Jalali (Persian) solar calendar based on the algorithm by Kazimierz M. Borkowski.
Key features of Version 3 include:
To use the Jalali calendar library in your PHP project, install it using Composer. Ensure your environment meets the minimum requirement of php >= 7.1.
$ composer require morilog/jalali:3.*When using the formatting methods in the jalali package, the syntax follows the standard PHP strftime() format characters. You can use these characters to define how the year, month, day, and other time components are displayed in your Jalali date strings.
/* Refer to PHP strftime() documentation for available format characters */jalali package relies on PHP's internal strtotime() for parsing strings and strftime() for formatting. If you receive unexpected results or false timestamps, it indicates that the class could not parse the input string correctly. Always verify the output of time() to ensure the timestamp is valid.The Jalalian class is the primary tool for manipulating Jalali date-time. You can create instances using several static methods or the jdate() helper (available in version >= 1.1).
Jalalian::now() or jdate(): Gets the current date/time.Jalalian::forge($timestamp) or jdate($timestamp): Creates a date from a Unix timestamp or a human-readable string (e.g., 'last sunday').Jalalian::fromCarbon(Carbon $carbon): Converts a Carbon instance to Jalalian.Jalalian::fromDateTime($dateTime): Converts a his ormat or ew his ormat instance to Jalalian.Jalalian::fromFormat($format, $timestamp): Creates a date from a specific string format.Jalalian::fromDateTime($dateTime): Creates a date from a his ormat or ew his ormat instance or a human-readable string like 'yesterday'.// Current time
$date = jdate();
// From timestamp
$date = jdate(1333857600);
// From human readable string
$date = Jalalian::forge('last sunday');
// From Carbon
$date = Jalalian::fromCarbon(Carbon::now());
// From DateTime
$date = Jalalian::fromDateTime('yesterday');The CalendarUtils class provides static helper methods for calendar-wide operations:
checkDate($year, $month, $day, [$isJalali = true]): Validates if a date exists. Set the 4th parameter to false to check a Gregorian date.toJalali($gYear, $gMonth, $gDay): Converts Gregorian components to a Jalali array [year, month, day].toGregorian($jYear, $jMonth, $jDay): Converts Jalali components to a Gregorian array [year, month, day].strftime($format, [$timestamp, $timezone]): Formats a timestamp into a Jalali date string.createDatetimeFromFormat($format, $jalaiTimeString): Creates a PHP his ormat instance from a Jalali string.createCarbonFromFormat($format, $jalaiTimeString): Creates a his ormat esbot/carbon instance from a Jalali string.convertNumbers($string): Converts between Latin and Persian digits. Use convertNumbers($string, true) to convert Persian to Latin.// Validate date
\Morilog\Jalali\CalendarUtils::checkDate(1391, 2, 30, true); // true
// Convert Gregorian to Jalali
\Morilog\Jalali\CalendarUtils::toJalali(2016, 5, 7); // [1395, 2, 18]
// Convert Persian numbers to Latin
$latin = \Morilog\Jalali\CalendarUtils::convertNumbers('۱۳۹۵-۰۲-۱۹', true); // 1395-02-19The Jalalian class provides methods to perform date arithmetic, returning a new Jalalian instance for chaining.
addDays(int $days), subDays(int $days)addMonths(int $months), subMonths(int $months)addYears(int $years), subYears(int $years)addHours(int $hours), subHours(int $hours)addMinutes(int $minutes), subMinutes(int $minutes)addSeconds(int $secs), subSeconds(int $secs)getNextWeek(), getNextMonth()$date = new Jalalian(1397, 1, 18);
$date->addMonths(1);
$date->subYears(1);
$date->addDays(5);You can format Jalalian objects into strings using the format() method or specialized helpers.
format(string $format): Uses standard PHP date format characters.format('date'): Returns a predefined date format (e.g., 1391-10-02).format('time'): Returns a predefined time format (e.g., 00:00:00).format('datetime'): Returns a predefined datetime format (e.g., 1391-10-02 00:00:00).ago(): Returns a relative 'ago' string in Persian (e.g., '10 دقیقه پیش').toString() or __toString(): Returns the date as a string (e.g., 1397-05-24 00:00:00).$date = Jalalian::forge('last sunday');
// Custom format
$date->format('%B %d، %Y');
// Predefined formats
$date->format('datetime');
$date->format('date');
$date->format('time');
// Relative format
$date->ago();Extract specific parts of a Jalalian date using getter methods:
getYear(): Returns the year.getMonth(): Returns the month.getDay(): Returns the day.getHour(), getMinute(), getSecond(): Returns time components.getDayOfWeek(): Returns the day of the week index.getDayOfYear(): Returns the day of the year.getMonthDays() or getDaysOf(int $monthNumber): Returns the number of days in a month.isLeapYear(): Returns true if the year is a leap year.$date = new Jalalian(1397, 1, 18);
$year = $date->getYear();
$month = $date->getMonth();
$day = $date->getDay();
$isLeap = $date->isLeapYear();To bridge Jalalian with other libraries or data formats:
toCarbon(): Converts the Jalalian instance into a briannesbitt/carbon instance.toArray(): Returns an associative array containing all date components (year, month, day, dayOfWeek, dayOfYear, hour, minute, second, micro, timestamp, formatted, and timezone).$date = new Jalalian(1397, 6, 24);
$carbon = $date->toCarbon();
$array = $date->toArray();Compare Jalalian instances or compare them against Carbon instances using the following methods:
equalsTo(Jalalian $other): Checks if two Jalalian dates are equal.equalsToCarbon(Carbon $carbon): Checks if a Jalalian date equals a Carbon instance.greaterThan(Jalalian $other) / greaterThanCarbon(Carbon $carbon)lessThan(Jalalian $other) / lessThanCarbon(Carbon $carbon)greaterThanOrEqualsTo(Jalalian $other) / greaterThanOrEqualsToCarbon(Carbon $carbon)lessThanOrEqualsTo(Jalalian $other) / lessThanOrEqualsToCarbon(Carbon $carbon)isToday(), isTomorrow(), isYesterday()isPast(), isFuture()$date1 = Jalalian::now();
$date2 = Jalalian::now()->subDays(1);
$date1->greaterThan($date2); // true
$date1->equalsToCarbon(Carbon::now()); // trueYou can create a Jalalian instance using the constructor by providing year, month, day, and optional time components. Alternatively, use static factory methods to create instances from existing date objects or timestamps.
Factory Methods:
now(?\DateTimeZone $timeZone): Returns a Jalalian instance representing the current time.fromCarbon(Carbon $carbon): Creates a Jalalian instance from a Carbon object.fromFormat(string $format, string $timestamp, ?\DateTimeZone $timeZone): Creates an instance by parsing a timestamp string with a specific format.forge($timestamp, ?\DateTimeZone $timeZone): A versatile method that accepts a timestamp (numeric) or a \DateTimeInterface string.fromDateTime(\DateTimeInterface|string $dateTime, ?\DateTimeZone $timeZone): Similar to forge, handles numeric timestamps or date strings.use Morilog//Jalali\Jalalian;
// Using constructor
$date = new Jalalian(1402, 5, 10, 12, 30, 0);
// Using factory methods
$now = Jalalian::now();
$fromCarbon = Jalalian::fromCarbon($carbonInstance);
$fromFormat = Jalalian::fromFormat('Y-m-d', '1402-05-10');
$forged = Jalalian::forge('2023-07-31');