[10.x] Adds timestamp retrieval as Carbon instance from UUID/ULID

[DarkGhostHunter]

What?

Extracts the timestamp from an UUID (v1, v2, v6, v7) or ULID into a Carbon instance.

use Illuminate\Support\Facades\Date;

// Dates from ULID
$date = Date::createFromUid('01H06ZMA15EBJASEXHWJC1SY5F');

// Dates from UUID
$date = Date::createFromUid('01880dfa-2825-72e4-acbb-b1e4981cf8af');

Returns null the UID has no timestamp, or false if the UID is invalid. This allows to check both cases:

$date = Date::createFromUid($uid);

if (is_null($date)) {
    return 'The UID is invalid';
} elseif (!$date) {
    return 'The UID has no timestamp';
}

return $date;

Why?

It saves the step to detect an incoming UID, transform into a UUID/ULID, and then extracting the date, and then transform it into Carbon, all that inside a try-catch if the UID is invalid or has no timestamp.

use Illuminate\Http\Request;
use Illuminate\Support\Str;
use Illuminate\Support\Facades\Date;
use Ramsey\Uuid\Uuid;
use Symfony\Component\Uid\Ulid;

// Before
public function date(Request $request)
{
    $uid = $request->uid;
    
    if (Str::isUlid($uid)) {
        return Date::make(Ulid::fromString($uid)->getDateTime()));
    }
    
    try {
        return Date::make(Uuid::fromString($uid)->getDateTime());
    } catch (\Throwable) {
        return null;
    }
}

[nunomaduro]

Feel that instead of having an API that returns null|false etc, this method should return an exception - specific to Carbon in Laravel - maybe InvalidUidException or something, that specifies what happen on the string message. What do you think @DarkGhostHunter?

[DarkGhostHunter]

I can just return a Carbon instance always, and leave it to the UUID class to throw its own exceptions, one for malformed UUID and the other for not time-based UUID. They're pretty much self explanatory.

This way the dev can know why it failed, at least if it's not passing an ULID.

Better, I could wrap these into an InvalidArgumentException telling the dev he passed confetti.

[nunomaduro]

@DarkGhostHunter Let's have @taylorotwell deciding this.

[DarkGhostHunter]

Okay.

Just to note aside, I think the UUID validator could use a min option to check if the UUID validates to a given version, saving an additional check afterwards. Currently only checks if it's an UUID.

[taylorotwell]

I agree let's just let it throw - updated.