talal424/calendars

PHP 5.5+ Support for various world calendars including Islamic calendar (UmmAlQura)

Calendars

This is a replica of Keith Wood's Calendar jQuery plugin written in PHP, _(*1)

This plugin provides support for various world calendars., _(*2)

Until now the available calendars are:, _(*3)

• Georgian calendar
• Umm al-Qura calendar (originally written by Amro Osama)

still yet to come and contributes are very welcome., _(*4)

Install:

• clone from Git or download then require the autoloader:

require 'path/to/Calendars/src/CalendarsAutoloader.php';

• or require from composer then require composer's autoloader:

composer require talal424/calendars

```php require 'vendor/autoload.php';, <sub>(*5)</sub>

Usage & examples:
===================

```php

<?php

use Talal424\Calendars\Calendars;

// get UmmAlQura calendar
$UmmAlQura = Calendars::calendar('UmmAlQura'); //object Talal424\Calendars\UmmAlQuraCalendar
// get Gregorian calendar
$Gregorian = Calendars::calendar('Gregorian'); // returns object Talal424\Calendars\GregorianCalendar

// get a new date
// $year, $month, $day 
$date = $UmmAlQura->newDate(1406,4,9); // returns object Talal424\Calendars\CDate

// $format, CDate $date, $settings
echo $UmmAlQura->formatDate('yyyy/mm/dd E',$date,['localNumbers'=>false]); // returns string
// 1406/04/09 AH

// or

// $format, $settings
echo $date->formatDate('yyyy/mm/dd'); // returns string
// ١٤٠٦/٠٤/٠٩

// convert UmmAlQura date to Julian date
$jd = $date->toJD(); // returns string

$date = $Gregorian->fromJD($jd); // returns object Talal424\Calendars\CDate

// $format, $settings
echo $date->formatDate('yyyy/mm/dd'); // returns string
// 1985/12/21

// you can also do this
$date = $Gregorian->newDate(); // returns today's date object Talal424\Calendars\CDate
// this would use the default format of the calendar (Gregorian) 'mm/dd/yyyy'
echo $date; // returns string
// 01/28/2017

Localisation and Languages

Talal424\Calendars\Calendars

this class has the exception messages stored as $regionalOptions, <sub>(*6)</sub>

$defaultLanguage = 'english'; // this will be used for all calendars later on unless language code is set when calendar is called.

$regionalOptions = [
    //Language Code
    'Arabic' => [
        'invalidCalendar' => 'لم يتم العثور على التقويم: {0}',
    ],
    'English' => [
        'invalidCalendar' => 'Calendar {0} not found',
    ]
];

it can be overwritten by any calendar, so you can make a special message for a specific calendar. this will be explain later on., <sub>(*7)</sub>

Calendars::setLanguage('Arabic'); // this will set Arabic as the default language

// get UmmAlQura calendar
$UmmAlQura = Calendars::calendar('UmmAlQura'); // this will load the calendar with the default language and settings.

$UmmAlQura = Calendars::calendar('UmmAlQura','Arabic'); // this will load the calendar with the Arabic language and settings.

if the language is not set the default language will be used. if the default language is not set or not found, the first language will be used. if none is found an exception will be thrown., <sub>(*8)</sub>

Other Calendars

classes of calendars have the language and settings stored in $regionalOptions, <sub>(*9)</sub>

each language code can have its own settings and language, and it can have these attributes:, <sub>(*10)</sub>

• epochs: The epoch names.
• monthNames: The long names of the months of the year.
• monthNamesShort: The short names of the months of the year.
• dayNames: The long names of the days of the week.
• dayNamesShort: The short names of the days of the week.
• localNumbers: true/false subtitue the digits with ones supplied e.g Arabic/Indian digits
• digits: The digits to subtitute
• dateFormat: The date format for this calendar.

plus any exception message., <sub>(*11)</sub>

example:, <sub>(*12)</sub>

$regionalOptions = [
    'US' => [
        'invalidYear' => 'Dude! {0} year is not right', // example for overriding an exception message
        'epochs' => ['BCE', 'CE'],
        'monthNames' => ['January', 'February', 'March', 'April', 'May', 'June','July', 'August', 'September', 'October', 'November', 'December'],
        'monthNamesShort' => ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
        'dayNames' => ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
        'dayNamesShort' => ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
        'digits' => null,
        'localNumbers' => false,
        'dateFormat' => 'mm/dd/yyyy',
    ],
    'UK' => [
        'epochs' => ['BCE', 'CE'],
        'monthNames' => ['January', 'February', 'March', 'April', 'May', 'June','July', 'August', 'September', 'October', 'November', 'December'],
        'monthNamesShort' => ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
        'dayNames' => ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
        'dayNamesShort' => ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
        'digits' => null,
        'localNumbers' => false,
        'dateFormat' => 'dd/mm/yyyy',
    ],
];

you can also if you use one language but different settings - just like our example above - by setting days and months names as default properties and then make the ' can be changed ' settings inside the $regionalOptions array, <sub>(*13)</sub>

example:, <sub>(*14)</sub>

class GregorianCalendar extends BaseCalendar
{
    public $name = 'Gregorian';
    public $hasYearZero = false;
    public $minMonth = 1;
    public $firstMonth = 1;
    public $minDay = 1;
    public $daysPerMonth = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
    public $jdEpoch = 1721425.5;

    public $epochs = ['BCE', 'CE'];
    public $monthNames = ['January', 'February', 'March', 'April', 'May', 'June','July', 'August', 'September', 'October', 'November', 'December'];
    public $monthNamesShort = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
    public $dayNames = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
    public $dayNamesShort = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
    public $digits = null;
    public $localNumbers = false;


    public $regionalOptions = [
        'US' => [
            'dateFormat' => 'mm/dd/yyyy',
        ],
        'UK' => [
            'dateFormat' => 'dd/mm/yyyy',
        ],
    ];
}

Date formats:

The format can be combinations of the following:, <sub>(*15)</sub>

• d - day of month (no leading zero)
• dd - day of month (two digit)
• o - day of year (no leading zeros)
• oo - day of year (three digit)
• D - day name short
• DD - day name long
• w - week of year (no leading zero)
• ww - week of year (two digit)
• m - month of year (no leading zero)
• mm - month of year (two digit)
• M - month name short
• MM - month name long
• E - the epoch designator for this date, e.g. BCE or CE.
• yy - year (two digit)
• yyyy - year (four digit)
• YYYY - formatted year
• J - Julian date (days since January 1, 4713 BCE Greenwich noon)
• @ - Unix timestamp (s since 01/01/1970)
• ! - Windows ticks (100ns since 01/01/0001)
• '...' - literal text
• '' - single quote