morilog/jalali

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

Fund package maintenance!
Issuehunt

Installs: 632 805

Dependents: 49

Suggesters: 0

Security: 0

Stars: 838

Watchers: 17

Forks: 113

Open Issues: 10

v3.4.1 2023-03-22 22:34 UTC

README

Version 3 features

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

Installation Version 3.*

If you are using version <= 2.*, please read old docs

Requirements:

  • php >= 7.0

Run the Composer update command

$ composer require morilog/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 = \Morilog\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 دقیقه پیش

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