Proyectos de Subversion Moodle

<?php

// This file is part of Moodle - http://moodle.org/

//

// Moodle is free software: you can redistribute it and/or modify

// it under the terms of the GNU General Public License as published by

// the Free Software Foundation, either version 3 of the License, or

// (at your option) any later version.

//

// Moodle is distributed in the hope that it will be useful,

// but WITHOUT ANY WARRANTY; without even the implied warranty of

// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

// GNU General Public License for more details.

//

// You should have received a copy of the GNU General Public License

// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

namespace core_calendar\output;

Use DateTimeInterface;

use DateTimeImmutable;

use core\output\templatable;

use core\output\renderable;

use core\output\renderer_base;

use core\url;

/**

 * Class humantimeperiod.

 *

 * This class is used to render a time period as a human readable date.

 * The main difference between userdate and this class is that this class

 * will render the date as "Today", "Yesterday", "Tomorrow" if the date is

 * close to the current date. Also, it will add styling if the date

 * is near.

 *

 * @package    core_calendar

 * @copyright  2025 Amaia Anabitarte <amaia@moodle.com>

 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

 */

class humantimeperiod implements renderable, templatable {

    /** @var int|null Number of seconds that indicates a nearby date. Default to DAYSECS. Use null for no indication. */

    protected $near = DAYSECS;

    /** @var url|null URL to link the date to. */

    protected ?url $link = null;

    /** @var string|null An optional date format to apply. */

    protected ?string $langtimeformat = null;

    /** @var bool Whether to use human common words or not. */

    protected bool $userelatives = true;

    /**

     * Class constructor.

     *

     * @param DateTimeImmutable $startdatetime The starting timestamp.

     * @param DateTimeImmutable|null $enddatetime The ending timestamp.

     */

    protected function __construct(

        /** @var DateTimeImmutable $startdatetime The starting date time. */

        protected DateTimeImmutable $startdatetime,

        /** @var DateTimeImmutable|null $enddatetime The ending date time. */

        protected ?DateTimeImmutable $enddatetime,

    ) {

    }

    /**

     * Creates a new humantimeperiod instance from a timestamp.

     *

     * @param int $starttimestamp The starting timestamp.

     * @param int|null $endtimestamp The ending timestamp.

     * @param int|null $near The number of seconds that indicates a nearby date. Default to DAYSECS, use null for no indication.

     * @param url|null $link URL to link the date to.

     * @param string|null $langtimeformat Lang date and time format to use to format the date.

     * @param bool $userelatives Whether to use human common words or not.

     * @return humantimeperiod The new instance.

     */

    public static function create_from_timestamp(

        int $starttimestamp,

        ?int $endtimestamp,

        ?int $near = DAYSECS,

        ?url $link = null,

        ?string $langtimeformat = null,

        bool $userelatives = true,

    ): self {

        return self::create_from_datetime(

            (new DateTimeImmutable("@{$starttimestamp}")),

            $endtimestamp ? (new DateTimeImmutable("@{$endtimestamp}")) : null,

            $near,

            $link,

            $langtimeformat,

            $userelatives

        );

    }

    /**

     * Creates a new humantimeperiod instance from a datetime.

     *

     * @param DateTimeInterface $startdatetime The starting datetime.

     * @param DateTimeInterface|null $enddatetime The ending datetime.

     * @param int|null $near The number of seconds that indicates a nearby date. Default to DAYSECS, use null for no indication.

     * @param url|null $link URL to link the date to.

     * @param string|null $langtimeformat Lang date and time format to use to format the date.

     * @param bool $userelatives Whether to use human common words or not.

     * @return humantimeperiod The new instance.

     */

    public static function create_from_datetime(

        DateTimeInterface $startdatetime,

        ?DateTimeInterface $enddatetime,

        ?int $near = DAYSECS,

        ?url $link = null,

        ?string $langtimeformat = null,

        bool $userelatives = true,

    ): self {

        // Always use an Immutable object to ensure that the value does not change externally before it is rendered.

        if (!($startdatetime instanceof DateTimeImmutable)) {

            $startdatetime = DateTimeImmutable::createFromInterface($startdatetime);

        }

        if ($enddatetime != null && !($enddatetime instanceof DateTimeImmutable)) {

            $enddatetime = DateTimeImmutable::createFromInterface($enddatetime);

        }

        return (new self($startdatetime, $enddatetime))

            ->set_near_limit($near)

            ->set_link($link)

            ->set_lang_time_format($langtimeformat)

            ->set_use_relatives($userelatives);

    }

    /**

     * Sets the number of seconds within which a date is considered near.

     *

     * @param int|null $near The number of seconds within which a date is considered near.

     * @return humantimeperiod The instance.

     */

    public function set_near_limit(?int $near): self {

        $this->near = $near;

        return $this;

    }

    /**

     * Sets the link for the date. If null, no link will be added.

     *

     * @param url|null $link The link for the date.

     * @return humantimeperiod The instance.

     */

    public function set_link(?url $link): self {

        $this->link = $link;

        return $this;

    }

    /**

     * Sets an optional date format to apply.

     *

     * @param string|null $langtimeformat Lang date and time format to use to format the date.

     * @return humantimeperiod The instance.

     */

    public function set_lang_time_format(?string $langtimeformat): self {

        $this->langtimeformat = $langtimeformat;

        return $this;

    }

    /**

     * Sets whether to use human relative terminology.

     *

     * @param bool $userelatives Whether to use human relative terminology.

     * @return humantimeperiod The instance.

     */

    public function set_use_relatives(bool $userelatives): self {

        $this->userelatives = $userelatives;

        return $this;

    }

    #[\Override]

    public function export_for_template(renderer_base $output): array {

        $period = $this->format_period();

        return [

            'startdate' => $period['startdate']->export_for_template($output),

            'enddate' => $period['enddate'] ? $period['enddate']->export_for_template($output) : null,

        ];

    }

    /**

     * Format a time periods based on 2 dates.

     *

     * @return array An array of one or two humandate elements.

     */

    private function format_period(): array {

        $linkstart = null;

        $linkend = null;

        if ($this->link) {

            $linkstart = new url($this->link, ['view' => 'day', 'time' => $this->startdatetime->getTimestamp()]);

            $linkend = new url($this->link, ['view' => 'day', 'time' => $this->enddatetime->getTimestamp()]);

        }

        $startdate = humandate::create_from_datetime(

            datetime: $this->startdatetime,

            near: $this->near,

            link: $linkstart,

            langtimeformat: $this->langtimeformat,

            userelatives: $this->userelatives

        );

        if ($this->enddatetime == null || $this->startdatetime == $this->enddatetime) {

            return [

                'startdate' => $startdate,

                'enddate' => null,

            ];

        }

        // Get the midnight of the day the event will start.

        $usermidnightstart = usergetmidnight($this->startdatetime->getTimestamp());

        // Get the midnight of the day the event will end.

        $usermidnightend = usergetmidnight($this->enddatetime->getTimestamp());

        // Check if we will still be on the same day.

        $issameday = ($usermidnightstart == $usermidnightend);

        $enddate = humandate::create_from_datetime(

            datetime: $this->enddatetime,

            near: $this->near,

            timeonly: $issameday,

            link: $linkend,

            langtimeformat: $this->langtimeformat,

            userelatives: $this->userelatives

        );

        return [

            'startdate' => $startdate,

            'enddate' => $enddate,

        ];

    }

}