Hi Timo!
I like the idea of simplifying the name and discouraging the use of MWTimestamp.
However, I'd like to take this opportunity to encourage the use of objects to
represent timestamps, instead of strings.This is better for static analysis and
IDE support, and also removes the requirement that everything that takes
timestamp parameter needs to apply conversion, or declare what format it accepts.
Since the focus of the static utility class is converting, maybe it should be
called TimeFormat. But I'd be fine with Timestamp as well. What I'd like to see
is a method similar to convert() that returns a DateTime object. parse(), maybe.
We should discourage the use of ConvertibeTimestamp objects and deprecate all
non-static parts of that class, in favor of DateTime. Or we could make it a
subclass of DateTime. Then the name "Timestamp" would be appropriate.
-- daniel
Am 18.04.2025 um 21:27 schrieb Krinkle:
https://gerrit.wikimedia.org/r/c/mediawiki/libs/Timestamp/+/1137473
I'd like to make this library more appealing for direct use in MediaWiki.
The current lengthy name of its primary entrypoint is imho off-putting,
and implies a working model that we may have originally envisioned
but is not how it works in practice.
Rather than creating and holding object references that one can convert,
the API has been much improved and simplified over the years to be
stateless and working with just scalar values in, and scalar values out.
The versatile parsing features and mocking capabilities are probably
as significant nowadays if not more so, than the fact that it can
return/convert several different string formats.
As such, I suggest we rename the class to plain "Timestamp".
As before, the place where conversion happens from caller perspective,
is the Timestamp::convert() method, which is imho well-named.
*== Example: Convert a timestamp ==*
// Traditional MediaWiki
class FooBar {
public function execute( $a, $data ) {
if ( $a ) {
$touched = *wfTimestamp*( TS_UNIX, $data->getTime() );
}
}
}
// Middle-school MediaWiki
use MediaWiki\Utils\MWTimestamp;
class FooBar {
public function execute( $a, $data ) {
if ( $a ) {
$touched = *MWTimestamp::convert*( TS_UNIX, $data->getTime() );
}
}
}
// Future A
use Wikimedia\Timestamp\ConvertibleTimestamp;
class FooBar {
public function execute( $a, $data ) {
if ( $a ) {
$touched = *ConvertibleTimestamp::convert*( TS_UNIX, $data->getTime() );
}
}
}
// Future B
use Wikimedia\Timestamp\Timestamp;
class FooBar {
public function execute( $a, $data ) {
if ( $a ) {
$touched = *Timestamp::convert*( TS_UNIX, $data->getTime() );
}
}
}
```
*== Example: Get current time ==*
Here the name seems even more out of place, as there is not only no
convertible object in sight, there is also no conversion intent as far as
the caller is concerned.
$now = *wfTimestamp*( TS_MW );
$now = *MWTimestamp::now*( TS_MW );
$now = *ConvertibleTimestamp::now*( TS_MW );
$now = *Timestamp::now*( TS_MW );
Like with T253461: Liberate the @ for AtEase
<https://phabricator.wikimedia.org/T253461>, I would recommend this
be a low-key and smooth migration. No disruption, no en-mass patches,
no deprecation, and no planned removal. Just a simple class alias.
If and when in a few years there is a good reason for a semver-major
release to wikimedia/timestamp, we can revisit this at that time.
--
Timo Tijhof
_______________________________________________
Wikitech-l mailing list [email protected]
To unsubscribe send an email [email protected]
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
--
Daniel Kinzler
Principal Software Engineer
MediaWiki Engineering Group
Wikimedia Foundation
_______________________________________________
Wikitech-l mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/
