feat(timestamp): add now() factories and a DateTimeInterface constructor

[CodeLieutenant]

What

Cassandra\Timestamp gets two convenience factories and a wider constructor.

$ts = Cassandra\Timestamp::now();
$ts = Cassandra\Timestamp::nowUtc();          // alias of now()
$ts = new Cassandra\Timestamp(new DateTime()); // same result as fromDateTime()

Why

new Cassandra\Timestamp(time()) is the common way to get the current time today. A named factory reads better. The constructor accepted only integers, so callers had to remember a second entry point (fromDateTime) for a date and time object.

Notes

• nowUtc() is an alias of now(). A timestamp holds a UTC epoch value in milliseconds, so it carries no zone. The method exists because the name is what users look for.
• A DateTimeInterface together with $microseconds throws InvalidArgumentException. The alternative is to discard the second value without a message.
• The conversion from DateTimeInterface to milliseconds now lives in one helper. The constructor and fromDateTime() share it.
• The first parameter keeps the name $seconds, so named arguments stay compatible.

Changes

• src/DateTime/Timestamp.stub.php, src/DateTime/Timestamp.c
• tests/Unit/DateTime/TimestampTest.php — 8 new cases
• docs/Cassandra/Timestamp.php (also adds the missing fromDateTime entry), website/reference/values.md, website/guide/data-types.md

Test

php -d extension=out/DebugPHP8.4NTS/cassandra.dylib ./vendor/bin/pest tests/Unit/DateTime/
Tests: 2 skipped, 62 passed (96 assertions)

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request