soroosh/jalali

This Package helps developers to easily work with Jalali (Shamsi or Iranian) dates in PHP applications, based on Jalali (Shamsi) DateTime class.

v3.2.1 2022-01-13 13:55 UTC

Requires

• php: ^7.0 | ^7.1 | ^7.2 | ^8.0
• beberlei/assert: 3.*
• nesbot/carbon: ^1.21 || ^2.0

Requires (Dev)

• phpunit/phpunit: ~4.0

MIT

• Milad Rey
• Morteza Parvini
• Soroosh Tanzadeh

• date
• laravel
• datetime
• Jalali
• morilog

README

• Jalali calendar is a solar calendar that was used in Persia, variants of which today are still in use in Iran as well as Afghanistan. Read more on Wikipedia or see Calendar Converter.

• Calendar conversion is based on the algorithm provided by Kazimierz M. Borkowski and has a very good performance.

• CalendarUtils class was ported from jalaali/jalaali-js

Version 3 features

• High human readable API
• DateTime manipulating API
• DateTime comparing API
• Immutable

Run the Composer update command

$ composer require soroosh/jalali:3.*

Basic Usage

In the current version, I introduced Jalalian class for manipulating Jalali date time

Jalalian

In version >= 1.1, you can use jdate() instead of Jalalian::forge();

now([$timestamp = null])

// the default timestamp is Now
$date = \Soroosh\Jalali\Jalalian::now()
// OR
$date = jdate();

// pass timestamps
$date = Jalalian::forge(1333857600);
// OR
$date = jdate(1333857600);

// pass human readable strings to make timestamps
$date = Jalalian::forge('last sunday');

// get the timestamp
$date = Jalalian::forge('last sunday')->getTimestamp(); // 1333857600

// format the timestamp
$date = Jalalian::forge('last sunday')->format('%B %d، %Y'); // دی 02، 1391
$date = Jalalian::forge('today')->format('%A, %d %B %y'); // جمعه، 23 اسفند 97

// get a predefined format
$date = Jalalian::forge('last sunday')->format('datetime'); // 1391-10-02 00:00:00
$date = Jalalian::forge('last sunday')->format('date'); // 1391-10-02
$date = Jalalian::forge('last sunday')->format('time'); // 00:00:00

// get relative 'ago' format
$date = Jalalian::forge('now - 10 minutes')->ago() // 10 دقیقه پیش
// OR
$date = Jalalian::forge('now - 10 minutes')->ago() // 10 دقیقه پیش

Methods api

public static function now(\DateTimeZone $timeZone = null): Jalalian

$jDate = Jalalian::now();

public static function fromCarbon(Carbon $carbon): Jalalian

$jDate = Jalalian::fromCarbon(Carbon::now());

public static function fromFormat(string $format, string $timestamp, \DateTimeZone$timeZone = null): Jalalian 

$jDate = Jalalian::fromFormat('Y-m-d H:i:s', '1397-01-18 12:00:40');

public static function forge($timestamp, \DateTimeZone $timeZone = null): Jalalian

// Alias fo fromDatetime

public static function fromDateTime($dateTime, \DateTimeZone $timeZone = null): Jalalian

$jDate = Jalalian::fromDateTime(Carbon::now())
// OR 
$jDate = Jalalian::fromDateTime(new \DateTime());
// OR
$jDate = Jalalian::fromDateTime('yesterday');

public function getMonthDays(): int

$date = (new Jalalian(1397, 1, 18))->getMonthDays() 
// output: 31

public function getMonth(): int

$date = (new Jalalian(1397, 1, 18))->getMonth() 
// output: 1

public function isLeapYear(): bool

$date = (new Jalalian(1397, 1, 18))->isLeapYear() 
// output: false

public function getYear(): int

$date = (new Jalalian(1397, 1, 18))->getYear() 
// output: 1397

public function subMonths(int $months = 1): Jalalian

$date = (new Jalalian(1397, 1, 18))->subMonths(1)->toString() 
// output: 1396-12-18 00:00:00

public function subYears(int $years = 1): Jalalian

$date = (new Jalalian(1397, 1, 18))->subYears(1)->toString()
// output: 1396-01-18 00:00:00

public function getDay(): int

$date = (new Jalalian(1397, 1, 18))->getDay() 
// output: 18

public function getHour(): int

$date = (new Jalalian(1397, 1, 18, 12, 0, 0))->getHour() 
// output: 12

public function getMinute(): int

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->getMinute() 
// output: 10

public function getSecond(): int

$date = (new Jalalian(1397, 1, 18, 12, 10, 45))->getSecond() 
// output: 45

public function getTimezone(): \DateTimeZone

// Get current timezone

public function addMonths(int $months = 1): Jalalian

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->addMonths(1)->format('m') 
// output: 02

public function addYears(int $years = 1): Jalalian

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->addYears(1)->format('Y') 
// output: 1398

public function getDaysOf(int $monthNumber = 1): int

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->getDaysOf(1) 
// output: 31

public function addDays(int $days = 1): Jalalian

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->addDays(1)->format('d') 
// output: 18

public function toCarbon(): Carbon

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->toCarbon()->toDateTimeString() 
// output: 2018-04-07 12:10:00

public function subDays(int $days = 1): Jalalian

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->subDays(10)->format('d') 
// output: 08

public function addHours(int $hours = 1): Jalalian

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->addHours(1)->format('H') 
// output: 13

public function subHours(int $hours = 1): Jalalian

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->subHours(1)->format('H') 
// output: 11

public function addMinutes(int $minutes = 1): Jalalian

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->addMinutes(10)->format('i') 
// output: 22

public function subMinutes(int $minutes = 1): Jalalian

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->subMinutes(10)->format('i') 
// output: 02

public function addSeconds(int $secs = 1): Jalalian

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->addSeconds(10)->format('s') 
// output: 10

public function subSeconds(int $secs = 1): Jalalian

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->subSeconds(10)->format('i:s') 
// output: 11:40

public function equalsTo(Jalalian $other): bool

$date = (new Jalalian(1397, 1, 18, 12, 10, 0))->equalsTo(Jalalian::now()) 
// output: false

$date = Jalalian::now()->equalsTo(Jalalian::now()) 
// output: true

public function equalsToCarbon(Carbon $carbon): bool

$date = Jalalian::now()->equalsToCarbon(Carbon::now())  
// output: true

public function greaterThan(Jalalian $other): bool

$date = Jalalian::now()->greaterThan(Jalalian::now()->subDays(1)))  
// output: true

public function greaterThanCarbon(Carbon $carbon): bool

$date = Jalalian::now()->greaterThanCarbon(Carbon::now()->subDays(1)))  
// output: true

public function lessThan(Jalalian $other): bool

$date = Jalalian::now()->lessThan(Jalalian::now()->addDays(1)))  
// output: true

public function lessThanCarbon(Carbon $carbon): bool

$date = Jalalian::now()->lessThanCarbon(Carbon::now()->addDays(1)))  
// output: true

public function greaterThanOrEqualsTo(Jalalian $other): bool

$date = Jalalian::now()->greaterThan(Jalalian::now()->subDays(1)))  
// output: true

public function greaterThanOrEqualsToCarbon(Carbon $carbon): bool

$date = Jalalian::now()->greaterThanOrEqualsToCarbon(Carbon::now()))  
// output: true

public function lessThanOrEqualsTo(Jalalian $other): bool

$date = Jalalian::now()->lessThanOrEqualsTo(Jalalian::now()))  
// output: true

public function lessThanOrEqualsToCarbon(Carbon $carbon): bool

$date = Jalalian::now()->lessThanOrEqualsToCarbon(Carbon::now()))  
// output: true

public function isStartOfWeek(): bool

$date = (new Jalalian(1397, 6, 24))->isStartOfWeek()
// output: true

public function isSaturday(): bool

$date = (new Jalalian(1397, 6, 24))->isSaturday()
// output: true

public function isDayOfWeek(int $day): bool

$date = (new Jalalian(1397, 6, 24))->isDayOfWeek(0)
// output: true

public function isEndOfWeek(): bool

$date = (new Jalalian(1397, 6, 24))->isEndOfWeek()
// output: false

public function isFriday(): bool

$date = (new Jalalian(1397, 6, 24))->isFriday()
// output: false

public function isToday(): bool

$date = (new Jalalian(1397, 6, 24))->isToday()
// output: (!maybe) true

public function isTomorrow(): bool

$date = (new Jalalian(1397, 6, 25))->isTomorrow()
// output: true

public function isYesterday(): bool

$date = (new Jalalian(1397, 6, 23))->isYesterday()
// output: true

public function isFuture(): bool

$date = (new Jalalian(1397, 6, 26))->isFuture()
// output: true

public function isPast(): bool

$date = (new Jalalian(1397, 5, 24))->isPast()
// output: true

public function toArray(): array
$date = (new Jalalian(1397, 6, 24))->toArray()
// output: (
//     [year] => 1397
//     [month] => 6
//     [day] => 24
//     [dayOfWeek] => 0
//     [dayOfYear] => 179
//     [hour] => 0
//     [minute] => 0
//     [second] => 0
//     [micro] => 0
//     [timestamp] => 1536969600
//     [formatted] => 1397-06-24 00:00:00
//     [timezone] =>
// )

public function getDayOfWeek(): int

$date = (new Jalalian(1397, 5, 24))->getDayOfWeek()
// output: 0

public function isSunday(): bool

$date = (new Jalalian(1397, 6, 24))->isSunday()
// output: false

public function isMonday(): bool

$date = (new Jalalian(1397, 6, 26))->isMonday()
// output: true

public function isTuesday(): bool

$date = (new Jalalian(1397, 6, 24))->isTuesday()
// output: false

public function isWednesday(): bool

$date = (new Jalalian(1397, 6, 24))->isWednesday()
// output: false

public function isThursday(): bool

$date = (new Jalalian(1397, 6, 22))->isThursday()
// output: true

public function getDayOfYear(): int

$date = (new Jalalian(1397, 5, 24))->getDayOfYear()
// output: 179

public function toString(): string
$date = (new Jalalian(1397, 5, 24))->isPast()
// output: 1397-05-24 00:00:00

public function format(string $format): string

$date = (new Jalalian(1397, 5, 24))->format('y')
// output: 1397
// see php date formats

public function __toString(): string

// Alias of toString()

public function ago(): string

public function getTimestamp(): int

public function getNextWeek(): Jalalian

public function getNextMonth(): Jalalian

CalendarUtils

checkDate($year, $month, $day, [$isJalali = true])

// Check jalali date
\Morilog\Jalali\CalendarUtils::checkDate(1391, 2, 30, true); // true

// Check jalali date
\Morilog\Jalali\CalendarUtils::checkDate(2016, 5, 7); // false

// Check gregorian date
\Morilog\Jalali\CalendarUtils::checkDate(2016, 5, 7, false); // true

toJalali($gYear, $gMonth, $gDay)

\Morilog\Jalali\CalendarUtils::toJalali(2016, 5, 7); // [1395, 2, 18]

toGregorian($jYear, $jMonth, $jDay)

\Morilog\Jalali\CalendarUtils::toGregorian(1395, 2, 18); // [2016, 5, 7]

strftime($format, [$timestamp = false, $timezone = null])

CalendarUtils::strftime('Y-m-d', strtotime('2016-05-8')); // 1395-02-19

createDateTimeFromFormat($format, $jalaiTimeString)

$Jalalian = '1394/11/25 15:00:00';

// get instance of \DateTime
$dateTime = \Morilog\Jalali\CalendarUtils::createDatetimeFromFormat('Y/m/d H:i:s', $Jalalian);

createCarbonFromFormat($format, $jalaiTimeString)

$Jalalian = '1394/11/25 15:00:00';

// get instance of \Carbon\Carbon
$carbon = \Morilog\Jalali\CalendarUtils::createCarbonFromFormat('Y/m/d H:i:s', $Jalalian);

convertNumbers($string)

// convert latin to persian
$date = \Morilog\Jalali\CalendarUtils::strftime('Y-m-d', strtotime('2016-05-8'); // 1395-02-19
\Morilog\Jalali\CalendarUtils::convertNumbers($date); // ۱۳۹۵-۰۲-۱۹

// convert persian to latin
$dateString = \Morilog\Jalali\CalendarUtils::convertNumbers('۱۳۹۵-۰۲-۱۹', true); // 1395-02-19
\Morilog\Jalali\CalendarUtils::createCarbonFromFormat('Y-m-d', $dateString)->format('Y-m-d'); //2016-05-8

Carbon api-difference

You can convert date/time to briannesbitt/carbon, thus being able to use it's API to work with PHP DateTime class.

Difference in months:

// convert persian to Carbon
$date = \Morilog\Jalali\Jalalian::fromFormat('Y-m-d', "1395-02-19")->toCarbon(); 
// ->toString() => Sun May 08 2016 00:00:00 GMT+0000

// Add 4 months to Carbon
$dateAdd4Months = $date->addMonths(4);

// Difference in months
$dateAdd4Months->DiffInMonths($date); //4
$dateAdd4Months->floatDiffInMonths($date); //4.0

Formatting

For help in building your formats, checkout the PHP strftime() docs.

Notes

The class relies on strtotime() to make sense of your strings, and strftime() to handle the formatting. Always check the time() output to see if you get false timestamps, it which case, means the class couldn't understand what you were asking it to do.

License

• This bundle is created based on Laravel-Date by Scott Travis (MIT Licensed).
• Jalali (Shamsi) DateTime class included in the package is created by Sallar Kaboli and is released under the MIT License.
• This package is created and modified by Morteza Parvini for Laravel >= 5 and is released under the MIT License.