[5.5] New Carbon helper

[carusogabriel]

Recently, two new helpers were added to Laravel: now and today. My first reaction was to add another two ones: tomorrow and yesterday, but it didn't sound the best to do. So, encouraged by that, I've created a new helper: carbon.

This helper will make the work with Carbon a lot easier, especially in views, removing the need of importing Carbon every time.

This supports:

• Datetime: carbon(\DateTime::createFromFormat('Y-m-d H', '2017-10-13 22'));
• String: carbon('2017-10-13 22:00:00');
• Timezone: carbon('tomorrow', 'America/Sao_Paulo');
• Relative phrases from Carbon: carbon('next month');
• Carbon helpers: carbon()->yesterday().

References: laravel/internals#828

[vlakoff]

If $tz = null, the ->setTimezone($tz) would apply the default timezone (see Carbon.php), overriding the timezone possibly already set on the passed DateTime instance.

Therefore, this:

if ($datetime instanceof \DateTime) {
    return Carbon::instance($datetime)->setTimezone($tz);
}

should be replaced with something like:

if ($datetime instanceof \DateTime) {
    $carbon = Carbon::instance($datetime);

    if (!is_null($tz)) {
        $carbon->setTimezone($tz);
    }

    return $carbon;
}

(and adding an unit test as well)

[linaspasv]

@Gabriel-Caruso it's very nice PR! I would just suggest to organise the code of your helper function in a similar style like other ones (see: app, config, redirect, etc.)

function carbon($datetime = null, $tz = null)
{
    if (is_null($datetime)) {
        return new Carbon;
    } 
    
    if ($datetime instanceof \DateTime) {
        if (is_null($tz)) {
            return Carbon::instance($datetime);
        }

        return Carbon::instance($datetime)->setTimezone($tz);
    }

    return Carbon::parse($datetime, $tz);
}

[vlakoff]

Just a nitpick, I'd replace:

return Carbon::parse($datetime, $tz);

with:

return new Carbon($datetime, $tz);

This saves a function call, and the syntaxic sugar is useless here, as this line is not using fluent syntax.
Also, it emphasize the remaining method, Carbon::instance, which contrarily is justified.

[vlakoff]

I had a look at this "carbonize" helper, linked on laravel/ideas#828. There are good things to pick in it.

For instance, this:

if (is_null($datetime)) {
    return new Carbon;
}

should be replaced with:

if (is_null($datetime)) {
    return new Carbon(null, $tz);
}

[sisve]

A quick slightly-relevant note; if you actually need working timezone calculations, stay on Carbon 1.21 - briannesbitt/Carbon#863

[taylorotwell]

No plans to add this to core.

[linaspasv]

Omm... so sad. In any case, good job @Gabriel-Caruso , keep the good work coming, this goes to all my new projects as a 3rd party helper!

[furey]

My implementation's been getting a little love on Twitter so thought I'd share…

if (!function_exists('carbon')) {
    /**
     * @param array $params
     * @return \Carbon\Carbon
     * */
    function carbon(...$params)
    {
        if (!$params) {
            return now();
        }

        if ($params[0] instanceof \DateTime) {
            return \Carbon\Carbon::instance($params[0]);
        }

        if (is_numeric($params[0]) && (string) (int) $params[0] === (string) $params[0]) {
            return \Carbon\Carbon::createFromTimestamp(...$params);
        }

        return \Carbon\Carbon::parse(...$params);
    }
}

Pretty much handles all the things, e.g.:

carbon(); // i.e. now()
carbon(1234567890);
carbon("1234567890");
carbon("yesterday");
carbon($myDateTimeInstance);
carbon($myCarbonInstance);

Tipping my hat to @ryanwinchester for the timestamp string conditional.

Goodbye "use Carbon\Carbon"!

🤓👌