HasTimestamps.php

TLDR

This file contains the HasTimestamps trait, which is used in the Laravel framework's Eloquent ORM. The trait provides methods related to timestamps in a model, such as updating the update timestamp, setting the created and updated timestamps, getting fresh timestamps, and determining if the model uses timestamps.

Methods

touch

Updates the model's update timestamp. If an attribute name is provided as an argument, it updates only that specific attribute. Returns true if the save operation is successful, false if the model does not use timestamps, or false if the save operation fails.

touchQuietly

Updates the model's update timestamp without raising any events. Calls the touch method under the hood. Returns the result of the touch method.

updateTimestamps

Updates the creation and update timestamps of the model. If the model is not yet persisted (created), it sets the created timestamp. The update timestamp is set only if the column is not dirty. Returns the model instance.

setCreatedAt

Sets the value of the "created at" attribute. Accepts a value as an argument and assigns it to the "created at" attribute of the model. Returns the model instance.

setUpdatedAt

Sets the value of the "updated at" attribute. Accepts a value as an argument and assigns it to the "updated at" attribute of the model. Returns the model instance.

freshTimestamp

Returns a fresh timestamp for the model as a Carbon instance.

freshTimestampString

Returns a fresh timestamp for the model as a string.

usesTimestamps

Determines if the model uses timestamps. Returns true if the timestamps property is true and the model's class is not listed in the ignoreTimestampsOn array.

getCreatedAtColumn

Returns the name of the "created at" column.

getUpdatedAtColumn

Returns the name of the "updated at" column.

getQualifiedCreatedAtColumn

Returns the fully qualified name of the "created at" column.

getQualifiedUpdatedAtColumn

Returns the fully qualified name of the "updated at" column.

withoutTimestamps

Disables timestamps for the current class during the given callback scope. Accepts a callback function as an argument and executes it after disabling timestamps. Returns the result of the callback function.

withoutTimestampsOn

Disables timestamps for the given model classes during the given callback scope. Accepts an array of model classes and a callback function as arguments. The given model classes are added to the ignoreTimestampsOn array temporarily, and the callback function is executed. After the callback is executed, the given model classes are removed from the ignoreTimestampsOn array. Returns the result of the callback function.

isIgnoringTimestamps

Determines if the given model class (or the current class if no argument is provided) is ignoring timestamps. Checks if the model class or any of its parents is listed in the ignoreTimestampsOn array. Returns true if timestamps are ignored, otherwise false.

<?php

namespace Illuminate\Database\Eloquent\Concerns;

use Illuminate\Support\Facades\Date;

trait HasTimestamps
{
    /**
     * Indicates if the model should be timestamped.
     *
     * @var bool
     */
    public $timestamps = true;

    /**
     * The list of models classes that have timestamps temporarily disabled.
     *
     * @var array
     */
    protected static $ignoreTimestampsOn = [];

    /**
     * Update the model's update timestamp.
     *
     * @param  string|null  $attribute
     * @return bool
     */
    public function touch($attribute = null)
    {
        if ($attribute) {
            $this->$attribute = $this->freshTimestamp();

            return $this->save();
        }

        if (! $this->usesTimestamps()) {
            return false;
        }

        $this->updateTimestamps();

        return $this->save();
    }

    /**
     * Update the model's update timestamp without raising any events.
     *
     * @param  string|null  $attribute
     * @return bool
     */
    public function touchQuietly($attribute = null)
    {
        return static::withoutEvents(fn () => $this->touch($attribute));
    }

    /**
     * Update the creation and update timestamps.
     *
     * @return $this
     */
    public function updateTimestamps()
    {
        $time = $this->freshTimestamp();

        $updatedAtColumn = $this->getUpdatedAtColumn();

        if (! is_null($updatedAtColumn) && ! $this->isDirty($updatedAtColumn)) {
            $this->setUpdatedAt($time);
        }

        $createdAtColumn = $this->getCreatedAtColumn();

        if (! $this->exists && ! is_null($createdAtColumn) && ! $this->isDirty($createdAtColumn)) {
            $this->setCreatedAt($time);
        }

        return $this;
    }

    /**
     * Set the value of the "created at" attribute.
     *
     * @param  mixed  $value
     * @return $this
     */
    public function setCreatedAt($value)
    {
        $this->{$this->getCreatedAtColumn()} = $value;

        return $this;
    }

    /**
     * Set the value of the "updated at" attribute.
     *
     * @param  mixed  $value
     * @return $this
     */
    public function setUpdatedAt($value)
    {
        $this->{$this->getUpdatedAtColumn()} = $value;

        return $this;
    }

    /**
     * Get a fresh timestamp for the model.
     *
     * @return \Illuminate\Support\Carbon
     */
    public function freshTimestamp()
    {
        return Date::now();
    }

    /**
     * Get a fresh timestamp for the model.
     *
     * @return string
     */
    public function freshTimestampString()
    {
        return $this->fromDateTime($this->freshTimestamp());
    }

    /**
     * Determine if the model uses timestamps.
     *
     * @return bool
     */
    public function usesTimestamps()
    {
        return $this->timestamps && ! static::isIgnoringTimestamps($this::class);
    }

    /**
     * Get the name of the "created at" column.
     *
     * @return string|null
     */
    public function getCreatedAtColumn()
    {
        return static::CREATED_AT;
    }

    /**
     * Get the name of the "updated at" column.
     *
     * @return string|null
     */
    public function getUpdatedAtColumn()
    {
        return static::UPDATED_AT;
    }

    /**
     * Get the fully qualified "created at" column.
     *
     * @return string|null
     */
    public function getQualifiedCreatedAtColumn()
    {
        return $this->qualifyColumn($this->getCreatedAtColumn());
    }

    /**
     * Get the fully qualified "updated at" column.
     *
     * @return string|null
     */
    public function getQualifiedUpdatedAtColumn()
    {
        return $this->qualifyColumn($this->getUpdatedAtColumn());
    }

    /**
     * Disable timestamps for the current class during the given callback scope.
     *
     * @param  callable  $callback
     * @return mixed
     */
    public static function withoutTimestamps(callable $callback)
    {
        return static::withoutTimestampsOn([static::class], $callback);
    }

    /**
     * Disable timestamps for the given model classes during the given callback scope.
     *
     * @param  array  $models
     * @param  callable  $callback
     * @return mixed
     */
    public static function withoutTimestampsOn($models, $callback)
    {
        static::$ignoreTimestampsOn = array_values(array_merge(static::$ignoreTimestampsOn, $models));

        try {
            return $callback();
        } finally {
            static::$ignoreTimestampsOn = array_values(array_diff(static::$ignoreTimestampsOn, $models));
        }
    }

    /**
     * Determine if the given model is ignoring timestamps / touches.
     *
     * @param  string|null  $class
     * @return bool
     */
    public static function isIgnoringTimestamps($class = null)
    {
        $class ??= static::class;

        foreach (static::$ignoreTimestampsOn as $ignoredClass) {
            if ($class === $ignoredClass || is_subclass_of($class, $ignoredClass)) {
                return true;
            }
        }

        return false;
    }
}