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 -- wikitech-l@lists.wikimedia.org
To unsubscribe send an email to wikitech-l-le...@lists.wikimedia.org
https://lists.wikimedia.org/postorius/lists/wikitech-l.lists.wikimedia.org/