時刻と日付

CodeIgniter は、PHP の DateTimeImmutable オブジェクトに基づいて構築された、完全にローカライズされた不変の日付/時刻クラスを提供します。ただし、Intl 拡張機能の機能を使用して、タイムゾーン間で時刻を変換し、さまざまなロケールに合わせて出力を正しく表示します。このクラスは Time クラスであり、CodeIgniter\I18n 名前空間に存在します。

注意

Time クラスは DateTimeImmutable を拡張しているため、このクラスが提供しない機能が必要な場合は、DateTimeImmutable クラス自体の中に見つけることができるでしょう。

注意

v4.3.0 より前は、Time クラスは DateTime を拡張しており、一部の継承されたメソッドが現在のオブジェクトの状態を変更していました。このバグは v4.3.0 で修正されました。下位互換性のために古い Time クラスが必要な場合は、当面の間、非推奨の TimeLegacy クラスを使用できます。

インスタンス化 

新しい Time インスタンスを作成する方法はいくつかあります。1 つ目は、他のクラスと同じように新しいインスタンスを作成することです。

この方法で作成する場合、目的の時刻を表す文字列を渡すことができます。これは、PHP の strtotime() 関数が解析できる任意の文字列にすることができます。

<?php

use CodeIgniter\I18n\Time;

$myTime = new Time('+3 week');
$myTime = new Time('now');

タイムゾーンとロケールを表す文字列をそれぞれ 2 番目と 3 番目のパラメーターで渡すことができます。タイムゾーンは、PHP の DateTimeZone クラスでサポートされている任意のタイムゾーンにすることができます。ロケールは、PHP の Locale クラスでサポートされている任意のロケールにすることができます。ロケールまたはタイムゾーンが指定されていない場合は、アプリケーションのデフォルトが使用されます。

<?php

use CodeIgniter\I18n\Time;

$myTime = new Time('now', 'America/Chicago', 'en_US');

now()

Time クラスには、クラスをインスタンス化するためのいくつかのヘルパーメソッドがあります。その最初のものが now() メソッドで、現在の時刻に設定された新しいインスタンスを返します。タイムゾーンとロケールを表す文字列をそれぞれ 2 番目と 3 番目のパラメーターで渡すことができます。ロケールまたはタイムゾーンが指定されていない場合は、アプリケーションのデフォルトが使用されます。

<?php

use CodeIgniter\I18n\Time;

$myTime = Time::now('America/Chicago', 'en_US');

parse()

このヘルパーメソッドは、デフォルトのコンストラクターの静的なバージョンです。最初のパラメーターとして DateTimeImmutable のコンストラクターとして受け入れられる文字列、2 番目のパラメーターとしてタイムゾーン、3 番目のパラメーターとしてロケールを受け取ります。

<?php

use CodeIgniter\I18n\Time;

$myTime = Time::parse('next Tuesday', 'America/Chicago', 'en_US');

today()

日付が現在の日付に設定され、時刻が真夜中に設定された新しいインスタンスを返します。最初のパラメーターと 2 番目のパラメーターでタイムゾーンとロケールの文字列を受け入れます。

<?php

use CodeIgniter\I18n\Time;

$myTime = Time::today('America/Chicago', 'en_US');

yesterday()

日付が昨日の日付に設定され、時刻が真夜中に設定された新しいインスタンスを返します。最初のパラメーターと 2 番目のパラメーターでタイムゾーンとロケールの文字列を受け入れます。

<?php

use CodeIgniter\I18n\Time;

$myTime = Time::yesterday('America/Chicago', 'en_US');

tomorrow()

日付が明日の日付に設定され、時刻が真夜中に設定された新しいインスタンスを返します。最初のパラメーターと 2 番目のパラメーターでタイムゾーンとロケールの文字列を受け入れます。

<?php

use CodeIgniter\I18n\Time;

$myTime = Time::tomorrow('America/Chicago', 'en_US');

createFromDate()

年、月、日の個別の入力を指定すると、新しいインスタンスが返されます。これらのパラメーターのいずれかが指定されていない場合は、現在の値を使用して入力されます。4 番目と 5 番目のパラメーターでタイムゾーンとロケールの文字列を受け入れます。

<?php

use CodeIgniter\I18n\Time;

$today       = Time::createFromDate();     // Uses current year, month, and day
$anniversary = Time::createFromDate(2018); // Uses current month and day
$date        = Time::createFromDate(2018, 3, 15, 'America/Chicago', 'en_US');

createFromTime()

createFromDate() と同様ですが、時間、分、秒のみに対応します。Time インスタンスの日付部分に現在の日付を使用します。4 番目と 5 番目のパラメーターでタイムゾーンとロケールの文字列を受け入れます。

<?php

use CodeIgniter\I18n\Time;

$lunch  = Time::createFromTime(11, 30);     // 11:30 am today
$dinner = Time::createFromTime(18, 00, 00); // 6:00 pm today
$time   = Time::createFromTime($hour, $minutes, $seconds, $timezone, $locale);

create()

前の 2 つのメソッドの組み合わせで、年、月、日、時間、分、秒を個別のパラメーターとして受け取ります。指定されていない値は、現在の日付と時刻を使用して決定されます。4 番目と 5 番目のパラメーターでタイムゾーンとロケールの文字列を受け入れます。

<?php

use CodeIgniter\I18n\Time;

$time = Time::create($year, $month, $day, $hour, $minutes, $seconds, $timezone, $locale);

createFromFormat()

これは、DateTimeImmutable の同じ名前のメソッドの代替です。これにより、タイムゾーンを同時に設定でき、DateTimeImmutable ではなく Time インスタンスが返されます。

<?php

use CodeIgniter\I18n\Time;

$time = Time::createFromFormat('j-M-Y', '15-Feb-2009', 'America/Chicago');

createFromTimestamp()

このメソッドは、UNIX タイムスタンプと、オプションでタイムゾーンとロケールを受け取り、新しい Time インスタンスを作成します。

<?php

use CodeIgniter\I18n\Time;

$time = Time::createFromTimestamp(1501821586, 'America/Chicago', 'en_US');

createFromInstance()

DateTime インスタンスを提供する他のライブラリを操作する場合、このメソッドを使用して、DateTime インスタンスを Time インスタンスに変換し、オプションでロケールを設定できます。タイムゾーンは、渡された DateTime インスタンスから自動的に決定されます。

<?php

use CodeIgniter\I18n\Time;

$dt   = new \DateTime('now');
$time = Time::createFromInstance($dt, 'en_US');

toDateTime()

インスタンス化ではありませんが、このメソッドは instance メソッドの逆で、Time インスタンスを DateTime インスタンスに変換できます。これにより、タイムゾーン設定は保持されますが、DateTime はロケールを認識しないため、ロケールは失われます。

<?php

use CodeIgniter\I18n\Time;

$datetime = Time::toDateTime();

値の表示 

Time クラスは DateTimeImmutable を拡張しているため、format() メソッドを含む、提供されているすべての出力メソッドを利用できます。ただし、DateTimeImmutable メソッドはローカライズされた結果を提供しません。Time クラスは、値のローカライズされたバージョンを表示するための多くのヘルパーメソッドを提供します。

toLocalizedString()

これは、DateTimeImmutable の format() メソッドのローカライズされたバージョンです。ただし、使い慣れている可能性のある値の代わりに、IntlDateFormatter クラスで受け入れられる値を使用する必要があります。値の完全なリストは、こちらにあります。

<?php

use CodeIgniter\I18n\Time;

// Locale: en
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toLocalizedString('MMM d, yyyy'); // March 9, 2016

// Locale: fa
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toLocalizedString('MMM d, yyyy'); // مارس ۹, ۲۰۱۶

toDateTimeString()

これは、IntlDateFormatter を操作するための 3 つのヘルパーメソッドの最初のものであり、値を記憶する必要はありません。これは、(Y-m-d H:i:s) としてフォーマットされた文字列のローカライズされたバージョンを返します。

<?php

use CodeIgniter\I18n\Time;

// Locale: en
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toDateTimeString(); // 2016-03-09 12:00:00

// Locale: fa
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toDateTimeString(); // ۲۰۱۶-۰۳-۰۹ ۱۲:۰۰:۰۰

toDateString()

時間のローカライズされた日付部分のみを表示します。

<?php

use CodeIgniter\I18n\Time;

// Locale: en
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toDateString(); // 2016-03-09

// Locale: fa
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toDateString(); // ۲۰۱۶-۰۳-۰۹

toTimeString()

値のローカライズされた時間部分のみを表示します。

<?php

use CodeIgniter\I18n\Time;

// Locale: en
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toTimeString(); // 12:00:00

// Locale: fa
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');
echo $time->toTimeString(); // ۱۲:۰۰:۰۰

humanize()

このメソッドは、現在の日時とインスタンスの差を、人間が理解しやすい形式で表示する文字列を返します。「3時間前」、「1ヶ月後」などの文字列を作成できます。

<?php

use CodeIgniter\I18n\Time;

// Assume current time is: March 10, 2017 (America/Chicago)
$time = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');

echo $time->humanize(); // 1 year ago

表示される正確な時間は、次の方法で決定されます。

時間差	結果
$time > 1年 && < 2年	1年後 / 1年前
$time > 1ヶ月 && < 1年	6ヶ月後 / 6ヶ月前
$time > 7日 && < 1ヶ月	3週間後 / 3週間前
$time > 今日 && < 7日	4日後 / 4日前
$time == 明日 / 昨日	明日 / 昨日
$time > 59分 && < 1日	2時間後 / 2時間前
$time > 現在 && < 1時間	35分後 / 35分前
$time == 現在	今

使用される正確な言語は、言語ファイル **Time.php** で制御されます。

個々の値の操作 

Timeオブジェクトは、既存のインスタンスの年、月、時間など、個々の項目を取得および設定するための多くのメソッドを提供します。次のメソッドで取得されるすべての値は完全にローカライズされ、Timeインスタンスが作成されたロケールを尊重します。

次のすべてのgetX()メソッドとsetX()メソッドは、クラスプロパティであるかのように使用することもできます。したがって、getYear()のようなメソッドへの呼び出しは、$time->yearなどを介してアクセスすることもできます。

ゲッター 

次の基本的なゲッターが存在します。

<?php

use CodeIgniter\I18n\Time;

$time = Time::parse('August 12, 2016 4:15:23pm');

// The output may vary based on locale.
echo $time->getYear();   // '2016'
echo $time->getMonth();  // '8'
echo $time->getDay();    // '12'
echo $time->getHour();   // '16'
echo $time->getMinute(); // '15'
echo $time->getSecond(); // '23'

echo $time->year;   // '2016'
echo $time->month;  // '8'
echo $time->day;    // '12'
echo $time->hour;   // '16'
echo $time->minute; // '15'
echo $time->second; // '23'

これらに加えて、日付に関する追加情報を提供するための多くのメソッドが存在します。

<?php

use CodeIgniter\I18n\Time;

$time = Time::parse('August 12, 2016 4:15:23pm');

// The output may vary based on locale.
echo $time->getDayOfWeek();   // '6'
echo $time->getDayOfYear();   // '225'
echo $time->getWeekOfMonth(); // '2'
echo $time->getWeekOfYear();  // '33'
echo $time->getTimestamp();   // 1471018523 - UNIX timestamp (locale independent)
echo $time->getQuarter();     // '3'

echo $time->dayOfWeek;   // '6'
echo $time->dayOfYear;   // '225'
echo $time->weekOfMonth; // '2'
echo $time->weekOfYear;  // '33'
echo $time->timestamp;   // 1471018523
echo $time->quarter;     // '3'

getAge()

Timeインスタンスと現在時刻の間の年齢（年単位）を返します。誕生日を基に誰かの年齢を確認するのに最適です。

<?php

use CodeIgniter\I18n\Time;

$time = Time::parse('5 years ago');

echo $time->getAge(); // 5
echo $time->age;      // 5

getDST()

Timeインスタンスが現在夏時間を観測しているかどうかに基づいて、booleanのtrue/falseを返します。

<?php

use CodeIgniter\I18n\Time;

echo Time::createFromDate(2012, 1, 1)->getDst(); // false
echo Time::createFromDate(2012, 9, 1)->dst;      // true

getLocal()

Timeインスタンスがアプリケーションが現在実行されているタイムゾーンと同じタイムゾーンにある場合にbooleanのtrueを返します。

<?php

use CodeIgniter\I18n\Time;

echo Time::now()->getLocal();           // true
echo Time::now('Europe/London')->local; // false

getUtc()

TimeインスタンスがUTC時間の場合にbooleanのtrueを返します。

<?php

use CodeIgniter\I18n\Time;

echo Time::now('America/Chicago')->getUtc(); // false
echo Time::now('UTC')->utc;                  // true

getTimezone()

Timeインスタンスのタイムゾーンを設定した新しいDateTimeZoneオブジェクトを返します。

<?php

use CodeIgniter\I18n\Time;

$tz = Time::now()->getTimezone();
$tz = Time::now()->timezone;

echo $tz->getName();
echo $tz->getOffset();

getTimezoneName()

Timeインスタンスの完全なタイムゾーン文字列を返します。

<?php

use CodeIgniter\I18n\Time;

echo Time::now('America/Chicago')->getTimezoneName(); // America/Chicago
echo Time::now('Europe/London')->timezoneName;        // Europe/London

セッター 

次の基本的なセッターが存在します。設定された値が範囲外の場合、InvalidArgumentExeptionがスローされます。

注意

すべてのセッターは、元のインスタンスには触れずに、新しいTimeインスタンスを返します。

注意

すべてのセッターは、値が範囲外の場合、InvalidArgumentExceptionをスローします。

<?php

$time = $time->setYear(2017);
$time = $time->setMonth(4);       // April
$time = $time->setMonth('April');
$time = $time->setMonth('Feb');   // February
$time = $time->setDay(25);
$time = $time->setHour(14);       // 2:00 pm
$time = $time->setMinute(30);
$time = $time->setSecond(54);

setTimezone()

現在のタイムゾーンから新しいタイムゾーンに時間を変換します。

<?php

use CodeIgniter\I18n\Time;

$time  = Time::parse('13 May 2020 10:00', 'America/Chicago');
$time2 = $time->setTimezone('Europe/London'); // Returns new instance converted to new timezone

echo $time->getTimezoneName();  // American/Chicago
echo $time2->getTimezoneName(); // Europe/London

echo $time->toDateTimeString();  // 2020-05-13 10:00:00
echo $time2->toDateTimeString(); // 2020-05-13 18:00:00

setTimestamp()

日付が新しいタイムスタンプに設定された新しいインスタンスを返します。

<?php

use CodeIgniter\I18n\Time;

$time  = Time::parse('May 10, 2017', 'America/Chicago');
$time2 = $time->setTimestamp(strtotime('April 1, 2017'));

echo $time->toDateTimeString();  // 2017-05-10 00:00:00
echo $time2->toDateTimeString(); // 2017-04-01 00:00:00

値の変更 

次のメソッドを使用すると、現在時刻に値を加算または減算して日付を変更できます。これにより、既存のTimeインスタンスは変更されませんが、新しいインスタンスが返されます。

<?php

$time = $time->addSeconds(23);
$time = $time->addMinutes(15);
$time = $time->addHours(12);
$time = $time->addDays(21);
$time = $time->addMonths(14);
$time = $time->addYears(5);

$time = $time->subSeconds(23);
$time = $time->subMinutes(15);
$time = $time->subHours(12);
$time = $time->subDays(21);
$time = $time->subMonths(14);
$time = $time->subYears(5);

2つの時刻の比較 

次のメソッドを使用すると、1つのTimeインスタンスを別のTimeインスタンスと比較できます。すべての比較は、異なるタイムゾーンが正しく応答するように、比較を行う前に最初にUTCに変換されます。

equals()

渡された日時が現在のインスタンスと等しいかどうかを判断します。この場合の「等しい」とは、同じ時点を表すことを意味し、両方の時間がUTCに変換されて比較されるため、同じタイムゾーンである必要はありません。

<?php

use CodeIgniter\I18n\Time;

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'Europe/London');

$time1->equals($time2); // true

テスト対象の値は、Timeインスタンス、DateTimeインスタンス、または新しいDateTimeインスタンスが理解できる形式で日付と時刻全体を含む文字列にすることができます。最初のパラメーターとして文字列を渡す場合は、2番目のパラメーターとしてタイムゾーン文字列を渡すことができます。タイムゾーンが指定されていない場合は、システムデフォルトが使用されます。

<?php

$time1->equals('January 11, 2017 03:50:00', 'Europe/London'); // true

sameAs()

これはequals()メソッドと同じですが、日付、時刻、およびタイムゾーンがすべて同じ場合にのみtrueを返します。

<?php

use CodeIgniter\I18n\Time;

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'Europe/London');

$time1->sameAs($time2); // false
$time2->sameAs('January 10, 2017 21:50:00', 'America/Chicago'); // true

isBefore()

渡された時間が現在のインスタンスより前であるかどうかを確認します。比較は、両方の時間のUTCバージョンに対して行われます。

<?php

use CodeIgniter\I18n\Time;

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'America/Chicago');

$time1->isBefore($time2); // true
$time2->isBefore($time1); // false

テスト対象の値は、Timeインスタンス、DateTimeインスタンス、または新しいDateTimeインスタンスが理解できる形式で日付と時刻全体を含む文字列にすることができます。最初のパラメーターとして文字列を渡す場合は、2番目のパラメーターとしてタイムゾーン文字列を渡すことができます。タイムゾーンが指定されていない場合は、システムデフォルトが使用されます。

<?php

$time1->isBefore('March 15, 2013', 'America/Chicago'); // false

isAfter()

isBefore()とまったく同じように動作しますが、時間が渡された時間より後かどうかを確認します。

<?php

use CodeIgniter\I18n\Time;

$time1 = Time::parse('January 10, 2017 21:50:00', 'America/Chicago');
$time2 = Time::parse('January 11, 2017 03:50:00', 'America/Chicago');

$time1->isAfter($time2); // false
$time2->isAfter($time1); // true

差異の表示 

2つの時刻を直接比較するには、difference()メソッドを使用します。このメソッドは、CodeIgniter\I18n\TimeDifferenceインスタンスを返します。最初のパラメーターは、Timeインスタンス、DateTimeインスタンス、または日付/時刻を含む文字列のいずれかです。最初のパラメーターに文字列が渡された場合、2番目のパラメーターはタイムゾーン文字列にすることができます。

<?php

use CodeIgniter\I18n\Time;

$time = Time::parse('March 10, 2017', 'America/Chicago');

$diff = $time->difference(Time::now());
$diff = $time->difference(new \DateTime('July 4, 1975', 'America/Chicago'));
$diff = $time->difference('July 4, 1975 13:32:05', 'America/Chicago');

TimeDifferenceインスタンスを取得したら、2つの時間差に関する情報を見つけるために使用できるいくつかのメソッドがあります。返される値は、過去にあった場合は負、元の時間から未来の場合は正になります。

<?php

use CodeIgniter\I18n\Time;

$current = Time::parse('March 10, 2017', 'America/Chicago');
$test    = Time::parse('March 10, 2010', 'America/Chicago');

$diff = $current->difference($test);

echo $diff->getYears();   // -7
echo $diff->getMonths();  // -84
echo $diff->getWeeks();   // -365
echo $diff->getDays();    // -2557
echo $diff->getHours();   // -61368
echo $diff->getMinutes(); // -3682080
echo $diff->getSeconds(); // -220924800

getX()メソッドを使用するか、プロパティであるかのように計算された値にアクセスできます。

<?php

echo $diff->years;   // -7
echo $diff->months;  // -84
echo $diff->weeks;   // -365
echo $diff->days;    // -2557
echo $diff->hours;   // -61368
echo $diff->minutes; // -3682080
echo $diff->seconds; // -220924800

humanize()

Timeのhumanize()メソッドと同様に、これは、時間差を、人間が理解しやすい形式で表示する文字列を返します。「3時間前」、「1ヶ月後」などの文字列を作成できます。最大の違いは、ごく最近の日付の処理方法にあります。

<?php

use CodeIgniter\I18n\Time;

$current = Time::parse('March 10, 2017', 'America/Chicago');
$test    = Time::parse('March 9, 2016 12:00:00', 'America/Chicago');

$diff = $current->difference($test);

echo $diff->humanize(); // 1 year ago

表示される正確な時間は、次の方法で決定されます。

時間差	結果
$time > 1年 && < 2年	1年後 / 1年前
$time > 1ヶ月 && < 1年	6ヶ月後 / 6ヶ月前
$time > 7日 && < 1ヶ月	3週間後 / 3週間前
$time > 今日 && < 7日	4日後 / 4日前
$time > 1時間 && < 1日	8時間後 / 8時間前
$time > 1分 && < 1時間	35分後 / 35分前
$time < 1分	今

使用される正確な言語は、言語ファイル **Time.php** で制御されます。