[marc-mabe]

This creates the following functions:

DateTime::createFromTimestamp(int|float $timestamp): static
DateTimeImmutable::createFromTimestamp(int|float $timestamp): static

The reason for these functions is the very common case of creating a DateTime[Immutable] object from a unix timestamp.
This currently only works by:

• special timestamp constructor format @<timestamp>
  • needs to be known by studying https://www.php.net/manual/en/datetime.formats.php
  • requires stringifying the timestamp
  • requires handling edge cases like avoiding scientific notation of floating points
• createFromFormat with U / U.u
  • same as @<timstamp> but adds additional differences on integer vs. float
• (new DateTime(...))->setTimestamp()
  • needs instance beforehand which does a current time lookup
  • setTimestamp supports integers only (This probably should allow floats as well in a separate PR)

The new functions avoid the above issues, are self explained and are much faster for this common case as well.

The functions will throw a DateRangeError in case of special floating point numbers or out-of-range of signed long long of timelib.

Internals: https://marc.info/?l=php-internals&m=169850186312326

Bench (doesn't even handle scientific notation of floating points):

<?php

$calls = 10000;
$time = time();
$microtime = microtime(true);
$utc = new DateTimeZone('+00:00');

function p(float $start, float $end, int $calls) {
    printf(
        "\t%ss for %s calls (%Fns per call)\n",
        ($end - $start) / 1000000000,
        $calls,
        ($end - $start) / $calls,
    );
}

foreach ([$time, $microtime] as $t) {
    echo '$t = ' . var_export($t, true) . "\n";

    echo 'new DateTime("@" . $t, $utc): ' . "\n";
    $start = hrtime(true);
    for ($i = 0; $i < $calls; $i += 1) {
        $tmp = new DateTime("@" . $t, $utc);
    }
    $end = hrtime(true);
    p($start, $end, $calls);
    //var_dump($tmp);

    if (is_float($t)) {
        echo 'DateTime::createFromFormat("U.u", $t, $utc): ' . "\n";
        $start = hrtime(true);
        for ($i = 0; $i < $calls; $i += 1) {
            $tmp = DateTime::createFromFormat("U.u", $t, $utc);
        }
        $end = hrtime(true);
        p($start, $end, $calls);
    } else {
        echo 'DateTime::createFromFormat("U", $t, $utc): ' . "\n";
        $start = hrtime(true);
        for ($i = 0; $i < $calls; $i += 1) {
            $tmp = DateTime::createFromFormat("U", $t, $utc);
        }
        $end = hrtime(true);
        p($start, $end, $calls);
    }
    //var_dump($tmp);

    echo 'DateTime::createFromTimestamp($t): ' . "\n";
    $start = hrtime(true);
    for ($i = 0; $i < $calls; $i += 1) {
        $tmp = DateTime::createFromTimestamp($t);
    }
    $end = hrtime(true);
    p($start, $end, $calls);
    //var_dump($tmp);
}

$t = 1697016217
new DateTime("@" . $t, $utc): 
        0.012929698s for 10000 calls (1292.969800ns per call)
DateTime::createFromFormat("U", $t, $utc): 
        0.009363419s for 10000 calls (936.341900ns per call)
DateTime::createFromTimestamp($t): 
        0.004168669s for 10000 calls (416.866900ns per call)
$t = 1697016217.492358
new DateTime("@" . $t, $utc): 
        0.013072768s for 10000 calls (1307.276800ns per call)
DateTime::createFromFormat("U.u", $t, $utc): 
        0.012962979s for 10000 calls (1296.297900ns per call)
DateTime::createFromTimestamp($t): 
        0.00396879s for 10000 calls (396.879000ns per call)

[marc-mabe]

@tentative-return-type makes Carbon compatible with deprecation message

[kamil-tekiela]

The functions can only return false in case of special floating point numbers or not within range of zend_long.

The signatures you listed do not contain false as a possible return type. Why do these functions return false at all? Why not just throw an exception?

[marc-mabe]

The functions can only return false in case of special floating point numbers or not within range of zend_long.

The signatures you listed do not contain false as a possible return type. Why do these functions return false at all? Why not just throw an exception?

@kamil-tekiela Thanks for pointing this out. It has been updated already to throw a DateRangeError as visible in the test. Updated the PR description accordingly.

[marc-mabe]

@derickr I have updated the PR according to your review

[derickr]

I think this looks good, but I have one question left.

[derickr]

Why do you say finite here, and not integer?

[marc-mabe]

I used the word "finite" to cover NAN, +/-INF as well and as a FP is allowed as well "integer" would not be fully correct.
If you feel it's confusing it could also be left out -> "... must be a number between ..."

[derickr]

I have merged this after a rebase, squash, and the addition of the NEWS entry. Thanks!

[derickr]

@marc-mabe Turns out that this failed tests on x32, can you have a look? https://github.com/php/php-src/actions/runs/6964523973/job/18951903197

[marc-mabe]

@marc-mabe Turns out that this failed tests on x32, can you have a look? https://github.com/php/php-src/actions/runs/6964523973/job/18951903197

I'll have a look ... Could you give me a hint for how I can test this without x32 arch 🙏

[derickr]

I run compile my 32-bit build like this:

https://github.com/derickr/php-build/blob/master/build#L68
https://github.com/derickr/php-build/blob/master/build#L138

You can probably get away with just --disable-all.

I guess, this would be minimal:

export CFLAGS="-m32"
export PKG_CONFIG_PATH="/usr/lib/i386-linux-gnu/pkgconfig"
./buildconf
./configure --build=i686-pc-linux-gnu --disable-all
make
make test TESTS=ext/date

[steffenweber]

I'm late to the party but I'm wondering why in contrast to createFromFormat, createFromTimestamp doesn't have a second parameter to specify the timezone. Of course, unix timestamps don't have a timezone but when I'm using the DateTime class to format a date I'll have to call setTimezone now. This feels a little inconvenient (and seems to be a relatively expensive call).

[steffenweber]

To answer my own question, createFromFormat actually doesn't use the timezone parameter either in this case: "The $timezone parameter and the current timezone are ignored when the $datetime parameter either is a UNIX timestamp [...]" – https://www.php.net/manual/en/datetime.construct.php

[kamil-tekiela]

I'm late to the party but I'm wondering why in contrast to createFromFormat, createFromTimestamp doesn't have a second parameter to specify the timezone. Of course, unix timestamps don't have a timezone but when I'm using the DateTime class to format a date I'll have to call setTimezone now. This feels a little inconvenient (and seems to be a relatively expensive call).

Because a UNIX timestamp already contains a time zone. Specifying a time zone would be redundant as you have found out yourself.