2020/02/09

【CakePHP3】Cake\I18n\Timeクラスのmodify()の単位は、単数形複数形どちらでも良い

CakePHP3のCake\I18n\Timeクラス。PHPのdate()やstrtotime()を組み合わせて書くよりも簡単に、現在日時からN時間前やN時間後などが計算できるので使っている方も多いはず。

僕もちょうど実装で使いたいと思った時にCakeの公式ドキュメントを眺めていたらmodify()の引数で渡す時間の単位がhourだったりhoursだったりで、”s”が付いても付かなくても良さそうな記述になっていて

「どっちが正なんだ！」

と思ったので、ちょっと調べてみた。検証したCakePHPのバージョンは3.6.13。

modify()の引数で渡す時間単位は単数/複数表記のどちらでも対応できるのが正

結論から先に言うと、どっちに統一するのが正という訳ではないようで、hour, hoursでもどちらでもOKというのが仕様のようだ。modify()関数は内部でpreg_match()関数を使用しており、hour, minute, secondというキーワードに反応するようになっている。

    /**
     * Overloaded to ignore time changes.
     *
     * Changing any aspect of the time will be ignored, and the resulting object
     * will have its time frozen to 00:00:00.
     *
     * @param string $relative The relative change to make.
     * @return static A new date with the applied date changes.
     */
    public function modify($relative)
    {
        if (preg_match('/hour|minute|second/', $relative)) {
            return $this;
        }
        $new = parent::modify($relative);
        if ($new->format('H:i:s') !== '00:00:00') {
            return $new->setTime(0, 0, 0);
        }

        return $new;
    }

/**

* Overloaded to ignore time changes.

* Changing any aspect of the time will be ignored, and the resulting object

* will have its time frozen to 00:00:00.

* @param string $relative The relative change to make.

* @return static A new date with the applied date changes.

public function modify($relative)

{

if (preg_match('/hour|minute|second/', $relative)) {

return $this;

}

$new = parent::modify($relative);

if ($new->format('H:i:s') !== '00:00:00') {

return $new->setTime(0, 0, 0);

}

return $new;

}

実際のコードは↑のようになっており、hoursやminutesのようにsが付いていてもpreg_match()で検出できるようになっているのだ。

その上で、

じゃあ単数形複数形をどう使い分けると良いのだろう？

と疑問が湧いたのだが、英語のお作法に習って考えると

1の場合は1 hour, 1 minute, 1 secondで単数形
2以上の場合は2 hours, 2 minutes, 2 secondsで複数形

にすれば良さそうだと思い至った。

実際Cakeの公式ドキュメントでも1の時は単数形で記載されており、2以上の時は複数形で記載されていたので、たぶんその解釈で合っていると思われる。メモ。