Modules

Date
extends Kohana_Date

Date helper.

package
Kohana
category
Helpers
author
Kohana Team
copyright
© 2007-2012 Kohana Team
license
https://kohana.top/license

Class declared in SYSPATH/classes/Date.php on line 3.

Constants

YEAR

integer 31556926

MONTH

integer 2629744

WEEK

integer 604800

DAY

integer 86400

HOUR

integer 3600

MINUTE

integer 60

MONTHS_LONG

string(2) "%B"

MONTHS_SHORT

string(2) "%b"

Properties

public static string $timestamp_format

Default timestamp format for formatted_time

string(11) "Y-m-d H:i:s"

public static string $timezone

Timezone for formatted_time

NULL

Methods

public static adjust( integer $hour , string $ampm ) (defined in Kohana_Date)

Adjusts a non-24-hour number into a 24-hour number.

$hour = Date::adjust(3, 'pm'); // 15

Parameters

  • integer $hour required - Hour to adjust
  • string $ampm required - AM or PM

Return Values

  • string

Source Code

public static function adjust($hour, $ampm)
{
    $hour = (int) $hour;
    $ampm = strtolower($ampm);

    switch ($ampm) {
        case 'am':
            if ($hour == 12) {
                $hour = 0;
            }
            break;
        case 'pm':
            if ($hour < 12) {
                $hour += 12;
            }
            break;
    }

    return sprintf('%02d', $hour);
}

public static ampm( integer $hour ) (defined in Kohana_Date)

Returns AM or PM, based on a given hour (in 24 hour format).

$type = Date::ampm(12); // PM
$type = Date::ampm(1);  // AM

Parameters

  • integer $hour required - Number of the hour

Return Values

  • string

Source Code

public static function ampm($hour)
{
    // Always integer
    $hour = (int) $hour;

    return ($hour > 11) ? 'PM' : 'AM';
}

public static days( integer $month [, integer $year = bool FALSE ] ) (defined in Kohana_Date)

Number of days in a given month and year. Typically used as a shortcut for generating a list that can be used in a form.

Date::days(4, 2010); // 1, 2, 3, ..., 28, 29, 30

Parameters

  • integer $month required - Number of month
  • integer $year = bool FALSE - Number of year to check month, defaults to the current year

Return Values

  • array - A mirrored (foo => foo) array of the days.

Source Code

public static function days($month, $year = false)
{
    static $months;

    if ($year === false) {
        // Use the current year by default
        $year = date('Y');
    }

    // Always integers
    $month = (int) $month;
    $year = (int) $year;

    // We use caching for months, because time functions are used
    if (empty($months[$year][$month])) {
        $months[$year][$month] = [];

        // Use date to find the number of days in the given month
        $total = date('t', mktime(1, 0, 0, $month, 1, $year)) + 1;

        for ($i = 1; $i < $total; $i++) {
            $months[$year][$month][$i] = (string) $i;
        }
    }

    return $months[$year][$month];
}

public static dos2unix( [ integer $timestamp = bool FALSE ] ) (defined in Kohana_Date)

Converts a DOS timestamp to UNIX format.There are very few cases where this is needed, but some binary formats use it (eg: zip files.) Converting the other direction is done using {@link Date::unix2dos}.

$unix = Date::dos2unix($dos);

Parameters

  • integer $timestamp = bool FALSE - DOS timestamp

Return Values

  • integer

Source Code

public static function dos2unix($timestamp = false)
{
    $sec = 2 * ($timestamp & 0x1f);
    $min = ($timestamp >> 5) & 0x3f;
    $hrs = ($timestamp >> 11) & 0x1f;
    $day = ($timestamp >> 16) & 0x1f;
    $mon = ($timestamp >> 21) & 0x0f;
    $year = ($timestamp >> 25) & 0x7f;

    return mktime($hrs, $min, $sec, $mon, $day, $year + 1980);
}

public static formatted_time( [ string $datetime_str = string(3) "now" , string $timestamp_format = NULL , string $timezone = NULL ] ) (defined in Kohana_Date)

Returns a date/time string with the specified timestamp format

$time = Date::formatted_time('5 minutes ago');

Parameters

  • string $datetime_str = string(3) "now" - Datetime string
  • string $timestamp_format = NULL - Timestamp format
  • string $timezone = NULL - Timezone identifier

Tags

Return Values

  • string

Source Code

public static function formatted_time($datetime_str = 'now', $timestamp_format = null, $timezone = null)
{
    $timestamp_format = ($timestamp_format == null) ? Date::$timestamp_format : $timestamp_format;
    $timezone = ($timezone === null) ? Date::$timezone : $timezone;

    $tz = new DateTimeZone($timezone ? $timezone : date_default_timezone_get());
    $time = new DateTime($datetime_str, $tz);

    // Convert the time back to the expected timezone if required (in case the datetime_str provided a timezone,
    // offset or unix timestamp. This also ensures that the timezone reported by the object is correct on HHVM
    // (see https://github.com/facebook/hhvm/issues/2302).
    $time->setTimeZone($tz);

    return $time->format($timestamp_format);
}

public static fuzzy_span( integer $timestamp [, integer $local_timestamp = NULL ] ) (defined in Kohana_Date)

Returns the difference between a time and now in a "fuzzy" way. Displaying a fuzzy time instead of a date is usually faster to read and understand.

$span = Date::fuzzy_span(time() - 10); // "moments ago"
$span = Date::fuzzy_span(time() + 20); // "in moments"

A second parameter is available to manually set the "local" timestamp, however this parameter shouldn't be needed in normal usage and is only included for unit tests

Parameters

  • integer $timestamp required - "remote" timestamp
  • integer $local_timestamp = NULL - "local" timestamp, defaults to time()

Return Values

  • string

Source Code

public static function fuzzy_span($timestamp, $local_timestamp = null)
{
    $local_timestamp = ($local_timestamp === null) ? time() : (int) $local_timestamp;

    // Determine the difference in seconds
    $offset = abs($local_timestamp - $timestamp);

    if ($offset <= Date::MINUTE) {
        $span = 'moments';
    } elseif ($offset < (Date::MINUTE * 20)) {
        $span = 'a few minutes';
    } elseif ($offset < Date::HOUR) {
        $span = 'less than an hour';
    } elseif ($offset < (Date::HOUR * 4)) {
        $span = 'a couple of hours';
    } elseif ($offset < Date::DAY) {
        $span = 'less than a day';
    } elseif ($offset < (Date::DAY * 2)) {
        $span = 'about a day';
    } elseif ($offset < (Date::DAY * 4)) {
        $span = 'a couple of days';
    } elseif ($offset < Date::WEEK) {
        $span = 'less than a week';
    } elseif ($offset < (Date::WEEK * 2)) {
        $span = 'about a week';
    } elseif ($offset < Date::MONTH) {
        $span = 'less than a month';
    } elseif ($offset < (Date::MONTH * 2)) {
        $span = 'about a month';
    } elseif ($offset < (Date::MONTH * 4)) {
        $span = 'a couple of months';
    } elseif ($offset < Date::YEAR) {
        $span = 'less than a year';
    } elseif ($offset < (Date::YEAR * 2)) {
        $span = 'about a year';
    } elseif ($offset < (Date::YEAR * 4)) {
        $span = 'a couple of years';
    } elseif ($offset < (Date::YEAR * 8)) {
        $span = 'a few years';
    } elseif ($offset < (Date::YEAR * 12)) {
        $span = 'about a decade';
    } elseif ($offset < (Date::YEAR * 24)) {
        $span = 'a couple of decades';
    } elseif ($offset < (Date::YEAR * 64)) {
        $span = 'several decades';
    } else {
        $span = 'a long time';
    }

    if ($timestamp <= $local_timestamp) {
        // This is in the past
        return $span . ' ago';
    } else {
        // This in the future
        return 'in ' . $span;
    }
}

public static hours( [ integer $step = integer 1 , boolean $long = bool FALSE , integer $start = NULL ] ) (defined in Kohana_Date)

Number of hours in a day. Typically used as a shortcut for generating a list that can be used in a form.

$hours = Date::hours(); // 01, 02, 03, ..., 10, 11, 12

Parameters

  • integer $step = integer 1 - Amount to increment each step by
  • boolean $long = bool FALSE - Use 24-hour time
  • integer $start = NULL - The hour to start at

Return Values

  • array - A mirrored (foo => foo) array from start-12 or start-23.

Source Code

public static function hours($step = 1, $long = false, $start = null)
{
    // Default values
    $step = (int) $step;
    $long = (bool) $long;
    $hours = [];

    // Set the default start if none was specified.
    if ($start === null) {
        $start = ($long === false) ? 1 : 0;
    }

    $hours = [];

    // 24-hour time has 24 hours, instead of 12
    $size = ($long === true) ? 23 : 12;

    for ($i = $start; $i <= $size; $i += $step) {
        $hours[$i] = (string) $i;
    }

    return $hours;
}

public static minutes( [ integer $step = integer 5 ] ) (defined in Kohana_Date)

Number of minutes in an hour, incrementing by a step. Typically used as a shortcut for generating a list that can be used in a form.

$minutes = Date::minutes(); // 05, 10, 15, ..., 50, 55, 60

Parameters

  • integer $step = integer 5 - Amount to increment each step by, 1 to 30

Tags

Return Values

  • array - A mirrored (foo => foo) array from 1-60.

Source Code

public static function minutes($step = 5)
{
    // Because there are the same number of minutes as seconds in this set,
    // we choose to re-use seconds(), rather than creating an entirely new
    // function. Shhhh, it's cheating! ;) There are several more of these
    // in the following methods.
    return Date::seconds($step);
}

public static months( [ string $format = NULL ] ) (defined in Kohana_Date)

Number of months in a year. Typically used as a shortcut for generating a list that can be used in a form.

By default a mirrored array of $month_number => $month_number is returned

Date::months();
// [1 => 1, 2 => 2, 3 => 3, ..., 12 => 12]

But you can customise this by passing in either Date::MONTHS_LONG

Date::months(Date::MONTHS_LONG);
// [1 => 'January', 2 => 'February', ..., 12 => 'December']

Or Date::MONTHS_SHORT

Date::months(Date::MONTHS_SHORT);
// [1 => 'Jan', 2 => 'Feb', ..., 12 => 'Dec']

Parameters

  • string $format = NULL - The format to use for months

Tags

Return Values

  • array - An array of months based on the specified format

Source Code

public static function months($format = null)
{
    $months = [];

    if ($format === Date::MONTHS_LONG OR $format === Date::MONTHS_SHORT) {
        for ($i = 1; $i <= 12; ++$i) {
            $months[$i] = strftime($format, mktime(0, 0, 0, $i, 1));
        }
    } else {
        $months = Date::hours();
    }

    return $months;
}

public static offset( string $remote [, string $local = NULL , mixed $now = NULL ] ) (defined in Kohana_Date)

Returns the offset (in seconds) between two time zones. Use this to display dates to users in different time zones.

$seconds = Date::offset('America/Chicago', 'GMT');

A list of time zones that PHP supports can be found at http://php.net/timezones.

Parameters

  • string $remote required - Timezone that to find the offset of
  • string $local = NULL - Timezone used as the baseline
  • mixed $now = NULL - UNIX timestamp or date string

Return Values

  • integer

Source Code

public static function offset($remote, $local = null, $now = null)
{
    if ($local === null) {
        // Use the default timezone
        $local = date_default_timezone_get();
    }

    if (is_int($now)) {
        // Convert the timestamp into a string
        $now = date(DateTime::RFC2822, $now);
    }

    // Create timezone objects
    $zone_remote = new DateTimeZone($remote);
    $zone_local = new DateTimeZone($local);

    // Create date objects from timezones
    $time_remote = new DateTime($now, $zone_remote);
    $time_local = new DateTime($now, $zone_local);

    // Find the offset
    $offset = $zone_remote->getOffset($time_remote) - $zone_local->getOffset($time_local);

    return $offset;
}

public static seconds( [ integer $step = integer 1 , integer $start = integer 0 , integer $end = integer 60 ] ) (defined in Kohana_Date)

Number of seconds in a minute, incrementing by a step. Typically used as a shortcut for generating a list that can used in a form.

$seconds = Date::seconds(); // 01, 02, 03, ..., 58, 59, 60

Parameters

  • integer $step = integer 1 - Amount to increment each step by, 1 to 30
  • integer $start = integer 0 - Start value
  • integer $end = integer 60 - End value

Return Values

  • array - A mirrored (foo => foo) array from 1-60.

Source Code

public static function seconds($step = 1, $start = 0, $end = 60)
{
    // Always integer
    $step = (int) $step;

    $seconds = [];

    for ($i = $start; $i < $end; $i += $step) {
        $seconds[$i] = sprintf('%02d', $i);
    }

    return $seconds;
}

public static span( integer $remote [, integer $local = NULL , string $output = string(45) "years,months,weeks,days,hours,minutes,seconds" ] ) (defined in Kohana_Date)

Returns time difference between two timestamps, in human readable format. If the second timestamp is not given, the current time will be used. Also consider using Date::fuzzy_span when displaying a span.

$span = Date::span(60, 182, 'minutes,seconds'); // ['minutes' => 2, 'seconds' => 2]
$span = Date::span(60, 182, 'minutes'); // 2

Parameters

  • integer $remote required - Timestamp to find the span of
  • integer $local = NULL - Timestamp to use as the baseline
  • string $output = string(45) "years,months,weeks,days,hours,minutes,seconds" - Formatting string

Return Values

  • string - When only a single output is requested
  • array - Associative list of all outputs requested

Source Code

public static function span($remote, $local = null, $output = 'years,months,weeks,days,hours,minutes,seconds')
{
    // Normalize output
    $output = trim(strtolower((string) $output));

    if (!$output) {
        // Invalid output
        return false;
    }

    // Array with the output formats
    $output = preg_split('/[^a-z]+/', $output);

    // Convert the list of outputs to an associative array
    $output = array_combine($output, array_fill(0, count($output), 0));

    // Make the output values into keys
    extract(array_flip($output), EXTR_SKIP);

    if ($local === null) {
        // Calculate the span from the current time
        $local = time();
    }

    // Calculate timespan (seconds)
    $timespan = abs($remote - $local);

    if (isset($output['years'])) {
        $timespan -= Date::YEAR * ($output['years'] = (int) floor($timespan / Date::YEAR));
    }

    if (isset($output['months'])) {
        $timespan -= Date::MONTH * ($output['months'] = (int) floor($timespan / Date::MONTH));
    }

    if (isset($output['weeks'])) {
        $timespan -= Date::WEEK * ($output['weeks'] = (int) floor($timespan / Date::WEEK));
    }

    if (isset($output['days'])) {
        $timespan -= Date::DAY * ($output['days'] = (int) floor($timespan / Date::DAY));
    }

    if (isset($output['hours'])) {
        $timespan -= Date::HOUR * ($output['hours'] = (int) floor($timespan / Date::HOUR));
    }

    if (isset($output['minutes'])) {
        $timespan -= Date::MINUTE * ($output['minutes'] = (int) floor($timespan / Date::MINUTE));
    }

    // Seconds ago, 1
    if (isset($output['seconds'])) {
        $output['seconds'] = $timespan;
    }

    if (count($output) === 1) {
        // Only a single output was requested, return it
        return array_pop($output);
    }

    // Return array
    return $output;
}

public static unix2dos( [ integer $timestamp = bool FALSE ] ) (defined in Kohana_Date)

Converts a UNIX timestamp to DOS format. There are very few cases where this is needed, but some binary formats use it (eg: zip files.) Converting the other direction is done using {@link Date::dos2unix}.

$dos = Date::unix2dos($unix);

Parameters

  • integer $timestamp = bool FALSE - UNIX timestamp

Return Values

  • integer

Source Code

public static function unix2dos($timestamp = false)
{
    $timestamp = ($timestamp === false) ? getdate() : getdate($timestamp);

    if ($timestamp['year'] < 1980) {
        return (1 << 21 | 1 << 16);
    }

    $timestamp['year'] -= 1980;

    // What voodoo is this? I have no idea... Geert can explain it though,
    // and that's good enough for me.
    return ($timestamp['year'] << 25 | $timestamp['mon'] << 21 |
        $timestamp['mday'] << 16 | $timestamp['hours'] << 11 |
        $timestamp['minutes'] << 5 | $timestamp['seconds'] >> 1);
}

public static years( [ integer $start = bool FALSE , integer $end = bool FALSE ] ) (defined in Kohana_Date)

Returns an array of years between a starting and ending year. By default, the the current year - 5 and current year + 5 will be used. Typically used as a shortcut for generating a list that can be used in a form.

$years = Date::years(2000, 2010); // 2000, 2001, ..., 2009, 2010

Parameters

  • integer $start = bool FALSE - Starting year (default is current year - 5)
  • integer $end = bool FALSE - Ending year (default is current year + 5)

Return Values

  • array

Source Code

public static function years($start = false, $end = false)
{
    // Default values
    $start = ($start === false) ? (date('Y') - 5) : (int) $start;
    $end = ($end === false) ? (date('Y') + 5) : (int) $end;

    $years = [];

    for ($i = $start; $i <= $end; $i++) {
        $years[$i] = (string) $i;
    }

    return $years;
}