InteractsWithTime.php

TLDR

This file provides a trait called InteractsWithTime that contains several methods for interacting with time-related operations. It includes methods for getting the number of seconds until a specific DateTime, getting the "available at" UNIX timestamp, parsing a value into a DateTime instance or interval, getting the current system time, and formatting the total run time for human readability.

Methods

secondsUntil

This method calculates and returns the number of seconds until the given DateTime. The input can be a DateTimeInterface, a DateInterval, or an integer representing seconds.

availableAt

This method calculates and returns the "available at" UNIX timestamp based on the given delay. The delay can be a DateTimeInterface, a DateInterval, or an integer representing seconds.

parseDateInterval

This method checks if the given value is a DateInterval and, if so, converts it to a DateTime instance using Carbon::now()->add() method. It returns the converted value or the original value if it's not an interval.

currentTime

This method returns the current system time as a UNIX timestamp using Carbon::now()->getTimestamp().

runTimeForHumans

This method calculates the total run time in milliseconds between the start time and an optional end time. It returns a formatted string representing the run time in a human-readable format. If the run time is greater than 1000 milliseconds, it uses CarbonInterval::milliseconds()->cascade()->forHumans() to format it. Otherwise, it returns the run time in milliseconds with 2 decimal places.

<?php

namespace Illuminate\Support;

use Carbon\CarbonInterval;
use DateInterval;
use DateTimeInterface;

trait InteractsWithTime
{
    /**
     * Get the number of seconds until the given DateTime.
     *
     * @param  \DateTimeInterface|\DateInterval|int  $delay
     * @return int
     */
    protected function secondsUntil($delay)
    {
        $delay = $this->parseDateInterval($delay);

        return $delay instanceof DateTimeInterface
                            ? max(0, $delay->getTimestamp() - $this->currentTime())
                            : (int) $delay;
    }

    /**
     * Get the "available at" UNIX timestamp.
     *
     * @param  \DateTimeInterface|\DateInterval|int  $delay
     * @return int
     */
    protected function availableAt($delay = 0)
    {
        $delay = $this->parseDateInterval($delay);

        return $delay instanceof DateTimeInterface
                            ? $delay->getTimestamp()
                            : Carbon::now()->addRealSeconds($delay)->getTimestamp();
    }

    /**
     * If the given value is an interval, convert it to a DateTime instance.
     *
     * @param  \DateTimeInterface|\DateInterval|int  $delay
     * @return \DateTimeInterface|int
     */
    protected function parseDateInterval($delay)
    {
        if ($delay instanceof DateInterval) {
            $delay = Carbon::now()->add($delay);
        }

        return $delay;
    }

    /**
     * Get the current system time as a UNIX timestamp.
     *
     * @return int
     */
    protected function currentTime()
    {
        return Carbon::now()->getTimestamp();
    }

    /**
     * Given a start time, format the total run time for human readability.
     *
     * @param  float  $startTime
     * @param  float  $endTime
     * @return string
     */
    protected function runTimeForHumans($startTime, $endTime = null)
    {
        $endTime ??= microtime(true);

        $runTime = ($endTime - $startTime) * 1000;

        return $runTime > 1000
            ? CarbonInterval::milliseconds($runTime)->cascade()->forHumans(short: true)
            : number_format($runTime, 2).'ms';
    }
}