Jalali

https://github.com/morilog/jalali
Admin
A PHP library for manipulating and converting dates using the Jalali (Persian) calendar, providing a...
Tokens:75,445
Snippets:516
Trust Score:7.9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install morilog/jalali 3.* with Composer

Source: https://github.com/morilog/jalali/blob/master/README.md

Install the Jalali calendar library version 3.* via Composer. Requires PHP >= 7.1.

```bash
$ composer require morilog/jalali:3.*
```

--------------------------------

### Error Handling Examples

Source: https://github.com/morilog/jalali/blob/master/_autodocs/errors.md

Code examples demonstrating how to catch exceptions and handle sentinel values in consumer code for the Jalali library.

```APIDOC
## [PHP] Jalalian::ago()

### Description
Returns a formatted relative time string, but returns `false` (a `bool`) when the timestamp is the epoch timestamp `0` (falsy), skipping formatting.

### Method
`Jalalian::ago()`

### Endpoint
`src/Jalalian.php:686-688`

### Parameters
None.

### Return Value
- **string** - Formatted relative time string (normal case)
- **bool** - `false` when `$this->getTimestamp()` is falsy (epoch timestamp `0`)

### Example
```php
$jDate = new Jalalian(1397, 12, 30);
$result = $jDate->ago(); // returns false if timestamp is 0
```
```

```APIDOC
## [PHP] CalendarUtils::parseFromFormat()

### Description
Parses a date string according to a given format. On parse failure, it does **not** throw an exception; instead, it sets the result's `error_count` to `1`.

### Method
`CalendarUtils::parseFromFormat()`

### Endpoint
`src/CalendarUtils.php`

### Parameters
- **format** (string) - Required - The format string used for parsing.
- **dateString** (string) - Required - The date string to parse.

### Return Value
- **object** - Result object with an `error_count` property; `1` indicates a parse failure.

### Example
```php
$result = CalendarUtils::parseFromFormat('Y-m-d', 'invalid-date');
if ($result->error_count === 1) {
    // handle parse failure
}
```
```

```APIDOC
## [PHP] Jalalian::fromDateTime() / Jalalian::forge()

### Description
Constructs a new `Carbon` instance from a given date-time string or object. For non-numeric inputs, an unparseable human-readable string propagates whatever exception `nesbot/carbon` raises (Carbon's own exception types). This repository does not catch or translate it.

### Method
`Jalalian::fromDateTime(string, ...)` / `Jalalian::forge(string, ...)`

### Endpoint
`src/Jalalian.php`

### Parameters
- **dateTime** (string) - Required - A date-time string or object to convert.
- **timeZone** (mixed) - Optional - Timezone for the new `Carbon` instance.

### Exceptions
- **Carbon\Exceptions\InvalidFormatException** - Propagated from `nesbot/carbon` when the input string is unparseable.

### Example
```php
try {
    $jDate = Jalalian::fromDateTime('not-a-date');
} catch (\Carbon\Exceptions\InvalidFormatException $e) {
    // handle invalid format
}
```
```

```APIDOC
## [PHP] Assert\Assertion (beberlei/assert ^3.0)

### Description
Used internally for validation. Its failure exception is `\InvalidArgumentException` per that package's documented default behavior.

### Method
`Assert\Assertion`

### Endpoint
`beberlei/assert ^3.0`

### Parameters
- **value** (mixed) - Required - The value to validate.
- **message** (string) - Optional - Custom error message.

### Exceptions
- **\InvalidArgumentException** - Thrown when validation fails.

### Example
```php
use Assert\Assertion;

try {
    Assertion::integer(123);
} catch (\InvalidArgumentException $e) {
    // handle assertion failure
}
```
```

```APIDOC
## [PHP] JDate::now()->toDateTimeString()

### Description
Converts the current Jalali date to a date-time string with a specified precision. Passing an invalid unit precision throws a `Carbon\Exceptions\UnitException`.

### Method
`JDate::now()->toDateTimeString(string $precision)`

### Endpoint
`src/JDate.php`

### Parameters
- **precision** (string) - Required - The unit precision (e.g., 'second', 'minute', 'hour', 'day', 'month', 'year').

### Exceptions
- **Carbon\Exceptions\UnitException** - Thrown when an invalid unit precision is provided.

### Example
```php
use Carbon\Exceptions\UnitException;

try {
    JDate::now()->toDateTimeString('century');
} catch (UnitException $e) {
    // invalid unit precision
}
```
```

--------------------------------

### isStartOfWeek method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if the date is the start of the week (Saturday in Jalali calendar). The example uses 1397/6/24 and returns true.

```php
public function isStartOfWeek(): bool

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

--------------------------------

### Jalalian::getDay() - get day

Source: https://github.com/morilog/jalali/blob/master/README.md

Get the day of the month. Example returns 18.

```php
public function getDay(): int

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

--------------------------------

### Jalalian::getSecond() - get second

Source: https://github.com/morilog/jalali/blob/master/README.md

Get the second component. Example returns 45.

```php
public function getSecond(): int

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

--------------------------------

### jdate() usage examples

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/jdate-helper.md

Examples of calling jdate() with various input types and using the returned Jalalian instance methods.

```php
$date = jdate();                    // same as Jalalian::now()
$date = jdate('now');               // same as Jalalian::now()
$date = jdate(1333857600);          // numeric epoch timestamp → Jalalian
$date = jdate('last sunday');       // human-readable string parsed by Carbon
$date = jdate('2016-05-07 10:00:00'); // ISO-ish string parsed by Carbon

// all returned values are full Jalalian instances:
$date->getTimestamp();              // int, epoch seconds
$date->format('Y-m-d');             // "1397-01-18"
$date->addDays(1)->format('Y-m-d'); // "1397-01-19" (immutability: new instance)
```

--------------------------------

### equalsToCarbon method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if a Jalalian instance equals a Carbon instance. The example compares now with Carbon::now() and returns true.

```php
public function equalsToCarbon(Carbon $carbon): bool

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

--------------------------------

### subMinutes method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Subtracts minutes from a Jalalian instance. The example subtracts 10 minutes from 12:10:00 and formats the minutes, yielding '02'.

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

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

--------------------------------

### Jalalian::getMinute() - get minute

Source: https://github.com/morilog/jalali/blob/master/README.md

Get the minute component. Example returns 10.

```php
public function getMinute(): int

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

--------------------------------

### isToday method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if the date is today. The example uses 1397/6/24 and the output is noted as possibly true.

```php
public function isToday(): bool

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

--------------------------------

### equalsTo method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if two Jalalian instances are equal. The first example compares a fixed date with now (false), the second compares two now instances (true).

```php
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
```

--------------------------------

### addMinutes method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Adds minutes to a Jalalian instance. The example adds 10 minutes to 12:10:00 and formats the minutes, producing '22'.

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

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

--------------------------------

### isTomorrow method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if the date is tomorrow. The example uses 1397/6/25 and returns true.

```php
public function isTomorrow(): bool

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

--------------------------------

### lessThanOrEqualsTo method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if a Jalalian instance is less than or equal to another. The example compares now with now and returns true.

```php
public function lessThanOrEqualsTo(Jalalian $other): bool

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

--------------------------------

### lessThanOrEqualsToCarbon method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if a Jalalian instance is less than or equal to a Carbon instance. The example compares now with Carbon::now() and returns true.

```php
public function lessThanOrEqualsToCarbon(Carbon $carbon): bool

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

--------------------------------

### toCarbon method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Converts a Jalalian instance to a Carbon instance. The example converts 1397/1/18 12:10:00 and outputs the equivalent Gregorian date-time string.

```php
public function toCarbon(): Carbon

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

--------------------------------

### getFirstDayOfMonth method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Returns the first day of the month for the given Jalalian date. The example for 1397/6/24 outputs 1397, 6, 1.

```php
public function getFirstDayOfMonth(): bool

$date = (new Jalalian(1397, 6, 24))->getFirstDayOfMonth()
// output: 1397, 6, 1
```

--------------------------------

### lessThan method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if a Jalalian instance is less than another. The example compares now with now plus one day and returns true.

```php
public function lessThan(Jalalian $other): bool

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

--------------------------------

### addDays method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Adds a number of days to a Jalalian instance and returns a new instance. The example adds 1 day to the date 1397/1/18 and formats the day as 'd', producing '18'.

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

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

--------------------------------

### lessThanCarbon method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if a Jalalian instance is less than a Carbon instance. The example compares now with Carbon::now()->addDays(1) and returns true.

```php
public function lessThanCarbon(Carbon $carbon): bool

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

--------------------------------

### isYesterday method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if the date is yesterday. The example uses 1397/6/23 and returns true.

```php
public function isYesterday(): bool

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

--------------------------------

### isFuture method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if the date is in the future. The example uses 1397/6/26 and returns true.

```php
public function isFuture(): bool

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

--------------------------------

### subDays method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Subtracts a number of days from a Jalalian instance. The example subtracts 10 days from 1397/1/18 and formats the day, yielding '08'.

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

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

--------------------------------

### addSeconds method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Adds seconds to a Jalalian instance. The example adds 10 seconds to 12:10:00 and formats the seconds, producing '10'.

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

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

--------------------------------

### isPast method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if the date is in the past. The example uses 1397/5/24 and returns true.

```php
public function isPast(): bool

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

--------------------------------

### subSeconds method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Subtracts seconds from a Jalalian instance. The example subtracts 10 seconds from 12:10:00 and formats minutes and seconds, yielding '11:40'.

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

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

--------------------------------

### greaterThan method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if a Jalalian instance is greater than another. The example compares now with now minus one day and returns true.

```php
public function greaterThan(Jalalian $other): bool

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

--------------------------------

### isFriday method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if the date is Friday. The example uses 1397/6/24 and returns false.

```php
public function isFriday(): bool

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

--------------------------------

### greaterThanOrEqualsToCarbon method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if a Jalalian instance is greater than or equal to a Carbon instance. The example compares now with Carbon::now() and returns true.

```php
public function greaterThanOrEqualsToCarbon(Carbon $carbon): bool

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

--------------------------------

### Create and format Jalali dates with Jalalian

Source: https://github.com/morilog/jalali/blob/master/README.md

Create Jalali dates using Jalalian::now(), jdate(), or Jalalian::forge() with timestamps or human-readable strings. Shows how to get timestamps, format dates with custom or predefined formats, and get relative 'ago' strings.

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

--------------------------------

### addHours method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Adds hours to a Jalalian instance. The example adds 1 hour to 12:10:00 and formats the hour, producing '13'.

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

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

--------------------------------

### Example usage of toJalali and toGregorian

Source: https://github.com/morilog/jalali/blob/master/_autodocs/types.md

Shows how to call CalendarUtils::toJalali and CalendarUtils::toGregorian. The comments show the resulting array values.

```php
$j = CalendarUtils::toJalali(2016, 5, 7);   // $j[0]=1395, $j[1]=2, $j[2]=18
$g = CalendarUtils::toGregorian(1395, 2, 18); // $g[0]=2016, $g[1]=5, $g[2]=7
```

--------------------------------

### createCarbonFromFormat usage example

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/calendar-utils.md

Example usage of createCarbonFromFormat. It parses the Jalali string and returns a Carbon instance. The comment shows that formatting with 'Y-m-d H:i:s' yields '2016-03-05 15:00:00'.

```php
$carbon = CalendarUtils::createCarbonFromFormat('Y/m/d H:i:s', '1394/11/25 15:00:00');
// $carbon->format('Y-m-d H:i:s') === '2016-03-05 15:00:00'
```

--------------------------------

### greaterThanCarbon method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if a Jalalian instance is greater than a Carbon instance. The example compares now with Carbon::now()->subDays(1) and returns true.

```php
public function greaterThanCarbon(Carbon $carbon): bool

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

--------------------------------

### subHours method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Subtracts hours from a Jalalian instance. The example subtracts 1 hour from 12:10:00 and formats the hour, yielding '11'.

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

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

--------------------------------

### greaterThanOrEqualsTo method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if a Jalalian instance is greater than or equal to another. The example uses greaterThan with now and now minus one day, returning true.

```php
public function greaterThanOrEqualsTo(Jalalian $other): bool

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

--------------------------------

### convertNumbers usage examples

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/calendar-utils.md

Example usage of convertNumbers. The first call converts Latin digits to Persian, the second converts Persian to Latin when the second argument is true.

```php
CalendarUtils::convertNumbers('1395-02-19');            // ۱۳۹۵-۰۲-۱۹
CalendarUtils::convertNumbers('۱۳۹۵-۰۲-۱۹', true);      // 1395-02-19
```

--------------------------------

### Convert Jalali to Gregorian

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/calendar-utils.md

Example of converting a Jalali date to Gregorian, returning the Gregorian array.

```php
CalendarUtils::toGregorian(1395, 2, 18); // [2016, 5, 7]
```

--------------------------------

### Convert Gregorian to Jalali

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/calendar-utils.md

Example of converting a Gregorian date to Jalali, returning the Jalali array.

```php
CalendarUtils::toJalali(2016, 5, 7); // [1395, 2, 18]
```

--------------------------------

### isDayOfWeek method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if the date falls on a specific day of the week (0 for Saturday). The example uses 1397/6/24 and day 0, returning true.

```php
public function isDayOfWeek(int $day): bool

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

--------------------------------

### checkDate usage examples

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/calendar-utils.md

Usage examples for checkDate. The first call returns true because 1391 is a leap year and Esfand has 30 days; the second returns true for a Gregorian date; the third returns false because 2016 is not a valid Jalali year in range semantics.

```php
CalendarUtils::checkDate(1391, 2, 30, true);  // true  — leap year, Esfand has 30 days
CalendarUtils::checkDate(2016, 5, 7, false);  // true  — Gregorian check
CalendarUtils::checkDate(2016, 5, 7);         // false — 2016 is not a Jalali year in range semantics
```

--------------------------------

### Using Jalalian day-week-month-year navigation methods

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/jalalian.md

Shows how to use the navigation methods on a Jalalian instance. Each method returns a new Jalalian instance representing the start or end of the week, month, year, or quarter. The comments show the expected formatted output for the given dates.

```php
$jDate = new Jalalian(1401, 1, 23);

$jDate->getFirstDayOfWeek()->format('Y-m-d');    // 1401-01-20 (Saturday of the week)
$jDate->getFirstDayOfMonth()->format('Y-m-d');   // 1401-01-01
$jDate->getFirstDayOfYear()->format('Y-m-d');    // 1401-01-01
$jDate->getFirstDayOfQuarter()->format('Y-m-d'); // 1401-01-01 (Q1)
$jDate->getEndDayOfMonth()->format('Y-m-d');     // 1401-01-31 (month 1 has 31 days)

(new Jalalian(1402, 10, 23))->getEndDayOfWeek()->format('Y-m-d'); // 1402-10-29 (Friday)
(new Jalalian(1402, 10, 25))->getEndDayOfYear()->format('Y-m-d'); // 1402-12-29
```

--------------------------------

### Jalalian::getHour() - get hour

Source: https://github.com/morilog/jalali/blob/master/README.md

Get the hour component. Example returns 12.

```php
public function getHour(): int

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

--------------------------------

### Convert Jalali to Gregorian DateTime

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/calendar-utils.md

Example of converting a Jalali date to a Gregorian DateTime object.

```php
$dt = CalendarUtils::toGregorianDate(1395, 2, 18); // \DateTime, 2016-05-07
```

--------------------------------

### Jalalian::getYear() - get year

Source: https://github.com/morilog/jalali/blob/master/README.md

Get the Jalali year. Example returns 1397.

```php
public function getYear(): int

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

--------------------------------

### Jalalian comparison methods usage example

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/jalalian.md

Shows how to use greaterThan, equalsToCarbon, and lessThanOrEqualsTo methods on Jalalian instances. The methods return boolean values based on Carbon comparisons.

```php
Jalalian::now()->greaterThan(Jalalian::now()->subDays(1));          // true
Jalalian::now()->equalsToCarbon(Carbon::now());                    // true
Jalalian::now()->lessThanOrEqualsTo(Jalalian::now());              // true
```

--------------------------------

### Jalalian::getMonth() - get month number

Source: https://github.com/morilog/jalali/blob/master/README.md

Get the Jalali month number (1-12). Example returns 1.

```php
public function getMonth(): int

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

--------------------------------

### Import CalendarUtils

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/calendar-utils.md

Import the CalendarUtils class for Jalali-Gregorian conversions and formatting.

```php
use Morilog\Jalali\CalendarUtils;
```

--------------------------------

### Jalalian::getDayOfYear() - Get day of year

Source: https://github.com/morilog/jalali/blob/master/README.md

Returns the day of the year as an integer. The example returns 179 for 1397-05-24.

```php
public function getDayOfYear(): int

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

--------------------------------

### Jalalian::getMonthDays() - days in month

Source: https://github.com/morilog/jalali/blob/master/README.md

Get the number of days in the month of the Jalali date. Example returns 31.

```php
public function getMonthDays(): int

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

--------------------------------

### Jalalian::getDayOfWeek() - Get day of week

Source: https://github.com/morilog/jalali/blob/master/README.md

Returns the day of the week as an integer (0 for Sunday). The example shows output 0 for 1397-05-24.

```php
public function getDayOfWeek(): int

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

--------------------------------

### Jalalian::getDaysOf() - days in specific month

Source: https://github.com/morilog/jalali/blob/master/README.md

Get the number of days in a given Jalali month. Example for month 1 returns 31.

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

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

--------------------------------

### Jalalian::format() - Format date string

Source: https://github.com/morilog/jalali/blob/master/README.md

Formats the date using PHP date format characters. The example formats 'y' to get the year 1397. See PHP date formats for available options.

```php
public function format(string $format): string

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

--------------------------------

### Jalalian::getTimezone() - get timezone

Source: https://github.com/morilog/jalali/blob/master/README.md

Get the timezone of the Jalalian instance.

```php
public function getTimezone(): \DateTimeZone

// Get current timezone
```

--------------------------------

### isLeapJalaliYear usage examples

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/calendar-utils.md

Usage examples for isLeapJalaliYear. 1395 is a leap year, 1394 is not.

```php
CalendarUtils::isLeapJalaliYear(1395); // true
CalendarUtils::isLeapJalaliYear(1394); // false
```

--------------------------------

### Jalalian::fromFormat() and toCarbon()

Source: https://github.com/morilog/jalali/blob/master/README.md

Create a Jalalian instance from a formatted string and convert it to a Carbon instance.

```APIDOC
## Jalalian::fromFormat() and toCarbon()

### Description
Create a Jalalian instance from a formatted string and convert it to a Carbon instance.

### Method
- (PHP static/instance method)

### Signature
`Jalalian::fromFormat($format, $jalaiTimeString)` and `$jalalian->toCarbon()`

### Parameters
- `$format` (string) - Required - Format string.
- `$jalaiTimeString` (string) - Required - Jalali date/time string.

### Return Value
- Carbon instance.
```

--------------------------------

### isSaturday method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if the date is Saturday. The example uses 1397/6/24 and returns true.

```php
public function isSaturday(): bool

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

--------------------------------

### isEndOfWeek method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Checks if the date is the end of the week (Friday). The example uses 1397/6/24 and returns false.

```php
public function isEndOfWeek(): bool

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

--------------------------------

### Import Jalalian class

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/jalalian.md

Import the `Jalalian` class from the `Morilog\Jalali` namespace.

```php
use Morilog\Jalali\Jalalian;
```

--------------------------------

### Create Jalalian from various inputs with fromDateTime()

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/jalalian.md

Creates a `Jalalian` instance from various input types. If the input is numeric, it uses `Carbon::createFromTimestamp`; otherwise it uses `new Carbon($dateTime, $timeZone)`. Then delegates to `fromCarbon`.

```php
$jDate = Jalalian::fromDateTime(Carbon::now());
$jDate = Jalalian::fromDateTime('yesterday');
$jDate = Jalalian::fromDateTime(time());
```

--------------------------------

### getEndDayOfMonth method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Returns the last day of the month for the given Jalalian date. The example for 1397/6/24 outputs 1397, 6, 30.

```php
public function getEndDayOfMonth(): bool

$date = (new Jalalian(1397, 6, 24))->getEndDayOfMonth()
// output: 1397, 6, 30
```

--------------------------------

### Carbon API difference - Convert Jalali to Carbon and diff

Source: https://github.com/morilog/jalali/blob/master/README.md

Converts a Jalali date to a Carbon instance, then demonstrates Carbon's diff methods. The example adds 4 months and calculates the difference in months.

```php
// 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
```

--------------------------------

### getEndDayOfYear method example

Source: https://github.com/morilog/jalali/blob/master/README.md

Returns the last day of the year for the given Jalalian date. The example for 1397/6/24 outputs 1397, 12, 29.

```php
public function getEndDayOfYear(): bool

$date = (new Jalalian(1397, 6, 24))->getEndDayOfYear()
// output: 1397, 12, 29
```

--------------------------------

### Constructor signature

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/jalalian.md

The constructor accepts year, month, day, and optional hour, minute, second, and timezone. It validates ranges: year 1000-3000, month 1-12, day 1-31 with month-specific bounds, hour 0-24, minute 0-59, second 0-59.

```php
public function __construct(
    int $year,
    int $month,
    int $day,
    int $hour = 0,
    int $minute = 0,
    int $second = 0,
    ?\DateTimeZone $timezone = null
)
```

--------------------------------

### Format Jalalian dates with format() and toString()

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/jalalian.md

Shows formatting a Jalalian date with format() using a custom token and the 'datetime' shortcut, and converting a Jalalian instance to a string with toString(). The output comments show the resulting Persian and Gregorian-style strings.

```php
Jalalian::forge('last sunday')->format('%B %d، %Y'); // دی 02، 1391
Jalalian::forge('last sunday')->format('datetime');  // 1391-10-02 00:00:00
(new Jalalian(1397, 5, 24))->toString();             // 1397-05-24 00:00:00
```

--------------------------------

### jdate()

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/jdate-helper.md

Documentation for the global jdate() helper function that creates Jalalian instances.

```APIDOC
## jdate()

### Description
Global helper function that creates a Jalalian instance from various input types. It is a shortcut for `Jalalian::forge()` and is always available when the package is installed.

### Signature
```php
function jdate($str = null)
```

### Parameters
- **$str** (null|int|string|\DateTimeInterface) - Optional - Anything accepted by `Jalalian::forge($str)`. When null, returns the current date/time.

### Return Value
- **\Morilog\Jalali\Jalalian** - A Jalalian instance representing the parsed date/time.

### Usage Examples
```php
$date = jdate();                    // same as Jalalian::now()
$date = jdate('now');               // same as Jalalian::now()
$date = jdate(1333857600);          // numeric epoch timestamp → Jalalian
$date = jdate('last sunday');       // human-readable string parsed by Carbon
$date = jdate('2016-05-07 10:00:00'); // ISO-ish string parsed by Carbon

// all returned values are full Jalalian instances:
$date->getTimestamp();              // int, epoch seconds
$date->format('Y-m-d');             // "1397-01-18"
$date->addDays(1)->format('Y-m-d'); // "1397-01-19" (immutability: new instance)
```

### Error Handling
Invalid (unparseable) arguments raise an exception originating from the Carbon constructor. Example:
```php
try {
    jdate('not a real date string');
} catch (\Exception $e) {
    // exception originates from new Carbon($str)
}
```

### Notes
- No `$timezone` parameter; timezone is always null.
- Global function, no namespace prefix.
- Loaded automatically via Composer autoload files.
```

--------------------------------

### Jalalian::fromCarbon() - convert Carbon to Jalalian

Source: https://github.com/morilog/jalali/blob/master/README.md

Convert a Carbon instance to a Jalalian instance.

```php
public static function fromCarbon(Carbon $carbon): Jalalian

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

--------------------------------

### Import the Converter trait

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/converter-trait.md

Shows how to reference the Converter trait, which is mixed into Jalalian via `use Converter;`.

```php
use Morilog\Jalali\Converter; // reference the trait; it is mixed into Jalalian via `use Converter;`
```

--------------------------------

### Catch exceptions from Jalalian and CalendarUtils

Source: https://github.com/morilog/jalali/blob/master/_autodocs/errors.md

Shows how to catch exceptions in consumer code for the Jalali library. The first try block catches validation errors from the constructor and arithmetic methods, the second catches conversion/type errors from CalendarUtils, and the third catches trait precision errors using Carbon's UnitException. Note that parse failures do not throw but set error_count to 1, and external exceptions from nesbot/carbon are not caught or translated.

```php
use Morilog\Jalali\Jalalian;
use Morilog\Jalali\CalendarUtils;

// Validation errors — constructor & arithmetic (items 1, 2)
try {
    $jDate = new Jalalian(1397, 12, 30);          // invalid day for non-leap Esfand
    $jDate->addYears(0);                          // invalid multiplier
} catch (\InvalidArgumentException $e) {
    // covers both CalendarUtils::jalaliCal and beberlei/assert failures
}

// Conversion/type errors (items 3, 4)
try {
    CalendarUtils::createDateTime(true);
    CalendarUtils::createTimeZone(new \stdClass());
} catch (\InvalidArgumentException $e) {
    // 'timestamp is not valid' / 'timezone is not valid'
}

// Trait precision errors (item 5)
use Carbon\Exceptions\UnitException;

try {
    JDate::now()->toDateTimeString('century');
} catch (UnitException $e) {
    // invalid unit precision
}
```

--------------------------------

### Using weekday and relative-day predicates

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/jalalian.md

Shows usage of weekday and relative-day predicates on a Jalalian instance. The comments indicate expected boolean results for specific dates.

```php
(new Jalalian(1397, 6, 24))->isSaturday();   // true  (24 Shahrivar 1397 was Saturday)
(new Jalalian(1397, 6, 24))->isStartOfWeek(); // true
(new Jalalian(1397, 6, 26))->isMonday();     // true
(new Jalalian(1397, 6, 26))->isFuture();     // true
```

--------------------------------

### createDatetimeFromFormat usage example

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/calendar-utils.md

Example usage of createDatetimeFromFormat. It parses the Jalali string '1394/11/25 15:00:00' with format 'Y/m/d H:i:s' and returns a Gregorian DateTime. The output format 'Y-m-d H:i:s' yields '2016-03-05 15:00:00'.

```php
$dt = CalendarUtils::createDatetimeFromFormat('Y/m/d H:i:s', '1394/11/25 15:00:00');
$dt->format('Y-m-d H:i:s'); // 2016-03-05 15:00:00
```

--------------------------------

### Switch Global Month Names

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/calendar-utils.md

Method signatures for switching the global month-name set. Both return void and affect subsequent formatting calls.

```php
public static function useAfghanMonthsName()   // sets $monthNames = AFGHAN_MONTHS_NAME
public static function useIranianMonthsName()  // sets $monthNames = IRANIAN_MONTHS_NAME
```

--------------------------------

### isStartOfWeek(): bool

Source: https://github.com/morilog/jalali/blob/master/_autodocs/api-reference/jalalian.md

Checks if the Jalalian instance is the start of the week, which is Saturday.

```APIDOC
## isStartOfWeek(): bool

### Description
Returns true when the Jalalian instance is the start of the week (Saturday).

### Method
isStartOfWeek

### Signature
public function isStartOfWeek(): bool

### Returns
- **bool** - True if the date is Saturday, false otherwise.

```
Tokens:
Raw