morilog / jalali by morilog
forked from miladr/jalali

This Package helps developers to easily work with Jalali (Shamsi or Iranian) dates in PHP applications, based on Jalali (Shamsi) DateTime class.
634,970
845
17
Package Data
Maintainer Username: morilog
Maintainer Contact: miladr@gmail.com (Milad Rey)
Package Create Date: 2014-10-29
Package Last Update: 2024-01-05
Home Page:
Language: PHP
License: MIT
Last Refreshed: 2024-03-26 03:00:35
Package Statistics
Total Downloads: 634,970
Monthly Downloads: 17,104
Daily Downloads: 552
Total Stars: 845
Total Watchers: 17
Total Forks: 101
Total Open Issues: 11

Build Status morilog/jalali

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 دقیقه پیش
// 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

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