[github/shaarli/Shaarli.git] / application / helper / DailyPageHelper.php

<?php

declare(strict_types=1);

namespace Shaarli\Helper;

use DatePeriod;
use DateTimeImmutable;
use Exception;
use Shaarli\Bookmark\Bookmark;
use Slim\Http\Request;

class DailyPageHelper
{
    public const MONTH = 'month';
    public const WEEK = 'week';
    public const DAY = 'day';

    /**
     * Extracts the type of the daily to display from the HTTP request parameters
     *
     * @param Request $request HTTP request
     *
     * @return string month/week/day
     */
    public static function extractRequestedType(Request $request): string
    {
        if ($request->getQueryParam(static::MONTH) !== null) {
            return static::MONTH;
        } elseif ($request->getQueryParam(static::WEEK) !== null) {
            return static::WEEK;
        }

        return static::DAY;
    }

    /**
     * Extracts a DateTimeImmutable from provided HTTP request.
     * If no parameter is provided, we rely on the creation date of the latest provided created bookmark.
     * If the datastore is empty or no bookmark is provided, we use the current date.
     *
     * @param string        $type           month/week/day
     * @param string|null   $requestedDate  Input string extracted from the request
     * @param Bookmark|null $latestBookmark Latest bookmark found in the datastore (by date)
     *
     * @return DateTimeImmutable from input or latest bookmark.
     *
     * @throws Exception Type not supported.
     */
    public static function extractRequestedDateTime(
        string $type,
        ?string $requestedDate,
        Bookmark $latestBookmark = null
    ): DateTimeImmutable {
        $format = static::getFormatByType($type);
        if (empty($requestedDate)) {
            return $latestBookmark instanceof Bookmark
                ? new DateTimeImmutable($latestBookmark->getCreated()->format(\DateTime::ATOM))
                : new DateTimeImmutable()
            ;
        }

        // W is not supported by createFromFormat...
        if ($type === static::WEEK) {
            return (new DateTimeImmutable())
                ->setISODate((int) substr($requestedDate, 0, 4), (int) substr($requestedDate, 4, 2))
            ;
        }

        return DateTimeImmutable::createFromFormat($format, $requestedDate);
    }

    /**
     * Get the DateTime format used by provided type
     * Examples:
     *   - day: 20201016 (<year><month><day>)
     *   - week: 202041 (<year><week number>)
     *   - month: 202010 (<year><month>)
     *
     * @param string $type month/week/day
     *
     * @return string DateTime compatible format
     *
     * @see https://www.php.net/manual/en/datetime.format.php
     *
     * @throws Exception Type not supported.
     */
    public static function getFormatByType(string $type): string
    {
        switch ($type) {
            case static::MONTH:
                return 'Ym';
            case static::WEEK:
                return 'YW';
            case static::DAY:
                return 'Ymd';
            default:
                throw new Exception('Unsupported daily format type');
        }
    }

    /**
     * Get the first DateTime of the time period depending on given datetime and type.
     * Note: DateTimeImmutable is required because we rely heavily on DateTime->modify() syntax
     *       and we don't want to alter original datetime.
     *
     * @param string             $type      month/week/day
     * @param DateTimeImmutable $requested DateTime extracted from request input
     *                                      (should come from extractRequestedDateTime)
     *
     * @return \DateTimeInterface First DateTime of the time period
     *
     * @throws Exception Type not supported.
     */
    public static function getStartDateTimeByType(string $type, DateTimeImmutable $requested): \DateTimeInterface
    {
        switch ($type) {
            case static::MONTH:
                return $requested->modify('first day of this month midnight');
            case static::WEEK:
                return $requested->modify('Monday this week midnight');
            case static::DAY:
                return $requested->modify('Today midnight');
            default:
                throw new Exception('Unsupported daily format type');
        }
    }

    /**
     * Get the last DateTime of the time period depending on given datetime and type.
     * Note: DateTimeImmutable is required because we rely heavily on DateTime->modify() syntax
     *       and we don't want to alter original datetime.
     *
     * @param string             $type      month/week/day
     * @param DateTimeImmutable $requested DateTime extracted from request input
     *                                      (should come from extractRequestedDateTime)
     *
     * @return \DateTimeInterface Last DateTime of the time period
     *
     * @throws Exception Type not supported.
     */
    public static function getEndDateTimeByType(string $type, DateTimeImmutable $requested): \DateTimeInterface
    {
        switch ($type) {
            case static::MONTH:
                return $requested->modify('last day of this month 23:59:59');
            case static::WEEK:
                return $requested->modify('Sunday this week 23:59:59');
            case static::DAY:
                return $requested->modify('Today 23:59:59');
            default:
                throw new Exception('Unsupported daily format type');
        }
    }

    /**
     * Get localized description of the time period depending on given datetime and type.
     * Example: for a month period, it returns `October, 2020`.
     *
     * @param string             $type            month/week/day
     * @param \DateTimeImmutable $requested       DateTime extracted from request input
     *                                            (should come from extractRequestedDateTime)
     * @param bool               $includeRelative Include relative date description (today, yesterday, etc.)
     *
     * @return string Localized time period description
     *
     * @throws Exception Type not supported.
     */
    public static function getDescriptionByType(
        string $type,
        \DateTimeImmutable $requested,
        bool $includeRelative = true
    ): string {
        switch ($type) {
            case static::MONTH:
                return $requested->format('F') . ', ' . $requested->format('Y');
            case static::WEEK:
                $requested = $requested->modify('Monday this week');
                return t('Week') . ' ' . $requested->format('W') . ' (' . format_date($requested, false) . ')';
            case static::DAY:
                $out = '';
                if ($includeRelative && $requested->format('Ymd') === date('Ymd')) {
                    $out = t('Today') . ' - ';
                } elseif ($includeRelative && $requested->format('Ymd') === date('Ymd', strtotime('-1 days'))) {
                    $out = t('Yesterday') . ' - ';
                }
                return $out . format_date($requested, false);
            default:
                throw new Exception('Unsupported daily format type');
        }
    }

    /**
     * Get the number of items to display in the RSS feed depending on the given type.
     *
     * @param string $type month/week/day
     *
     * @return int number of elements
     *
     * @throws Exception Type not supported.
     */
    public static function getRssLengthByType(string $type): int
    {
        switch ($type) {
            case static::MONTH:
                return 12; // 1 year
            case static::WEEK:
                return 26; // ~6 months
            case static::DAY:
                return 30; // ~1 month
            default:
                throw new Exception('Unsupported daily format type');
        }
    }

    /**
     * Get the number of items to display in the RSS feed depending on the given type.
     *
     * @param string             $type      month/week/day
     * @param ?DateTimeImmutable $requested Currently only used for UT
     *
     * @return DatePeriod number of elements
     *
     * @throws Exception Type not supported.
     */
    public static function getCacheDatePeriodByType(string $type, DateTimeImmutable $requested = null): DatePeriod
    {
        $requested = $requested ?? new DateTimeImmutable();

        return new DatePeriod(
            static::getStartDateTimeByType($type, $requested),
            new \DateInterval('P1D'),
            static::getEndDateTimeByType($type, $requested)
        );
    }
}
Commit	Line	Data
	1	<?php
	2
	3	declare(strict_types=1);
	4
	5	namespace Shaarli\Helper;
	6
	7	use DatePeriod;
	8	use DateTimeImmutable;
	9	use Exception;
	10	use Shaarli\Bookmark\Bookmark;
	11	use Slim\Http\Request;
	12
	13	class DailyPageHelper
	14	{
	15	public const MONTH = 'month';
	16	public const WEEK = 'week';
	17	public const DAY = 'day';
	18
	19	/**
	20	* Extracts the type of the daily to display from the HTTP request parameters
	21	*
	22	* @param Request $request HTTP request
	23	*
	24	* @return string month/week/day
	25	*/
	26	public static function extractRequestedType(Request $request): string
	27	{
	28	if ($request->getQueryParam(static::MONTH) !== null) {
	29	return static::MONTH;
	30	} elseif ($request->getQueryParam(static::WEEK) !== null) {
	31	return static::WEEK;
	32	}
	33
	34	return static::DAY;
	35	}
	36
	37	/**
	38	* Extracts a DateTimeImmutable from provided HTTP request.
	39	* If no parameter is provided, we rely on the creation date of the latest provided created bookmark.
	40	* If the datastore is empty or no bookmark is provided, we use the current date.
	41	*
	42	* @param string $type month/week/day
	43	* @param string\|null $requestedDate Input string extracted from the request
	44	* @param Bookmark\|null $latestBookmark Latest bookmark found in the datastore (by date)
	45	*
	46	* @return DateTimeImmutable from input or latest bookmark.
	47	*
	48	* @throws Exception Type not supported.
	49	*/
	50	public static function extractRequestedDateTime(
	51	string $type,
	52	?string $requestedDate,
	53	Bookmark $latestBookmark = null
	54	): DateTimeImmutable {
	55	$format = static::getFormatByType($type);
	56	if (empty($requestedDate)) {
	57	return $latestBookmark instanceof Bookmark
	58	? new DateTimeImmutable($latestBookmark->getCreated()->format(\DateTime::ATOM))
	59	: new DateTimeImmutable()
	60	;
	61	}
	62
	63	// W is not supported by createFromFormat...
	64	if ($type === static::WEEK) {
	65	return (new DateTimeImmutable())
	66	->setISODate((int) substr($requestedDate, 0, 4), (int) substr($requestedDate, 4, 2))
	67	;
	68	}
	69
	70	return DateTimeImmutable::createFromFormat($format, $requestedDate);
	71	}
	72
	73	/**
	74	* Get the DateTime format used by provided type
	75	* Examples:
	76	* - day: 20201016 (<year><month><day>)
	77	* - week: 202041 (<year><week number>)
	78	* - month: 202010 (<year><month>)
	79	*
	80	* @param string $type month/week/day
	81	*
	82	* @return string DateTime compatible format
	83	*
	84	* @see https://www.php.net/manual/en/datetime.format.php
	85	*
	86	* @throws Exception Type not supported.
	87	*/
	88	public static function getFormatByType(string $type): string
	89	{
	90	switch ($type) {
	91	case static::MONTH:
	92	return 'Ym';
	93	case static::WEEK:
	94	return 'YW';
	95	case static::DAY:
	96	return 'Ymd';
	97	default:
	98	throw new Exception('Unsupported daily format type');
	99	}
	100	}
	101
	102	/**
	103	* Get the first DateTime of the time period depending on given datetime and type.
	104	* Note: DateTimeImmutable is required because we rely heavily on DateTime->modify() syntax
	105	* and we don't want to alter original datetime.
	106	*
	107	* @param string $type month/week/day
	108	* @param DateTimeImmutable $requested DateTime extracted from request input
	109	* (should come from extractRequestedDateTime)
	110	*
	111	* @return \DateTimeInterface First DateTime of the time period
	112	*
	113	* @throws Exception Type not supported.
	114	*/
	115	public static function getStartDateTimeByType(string $type, DateTimeImmutable $requested): \DateTimeInterface
	116	{
	117	switch ($type) {
	118	case static::MONTH:
	119	return $requested->modify('first day of this month midnight');
	120	case static::WEEK:
	121	return $requested->modify('Monday this week midnight');
	122	case static::DAY:
	123	return $requested->modify('Today midnight');
	124	default:
	125	throw new Exception('Unsupported daily format type');
	126	}
	127	}
	128
	129	/**
	130	* Get the last DateTime of the time period depending on given datetime and type.
	131	* Note: DateTimeImmutable is required because we rely heavily on DateTime->modify() syntax
	132	* and we don't want to alter original datetime.
	133	*
	134	* @param string $type month/week/day
	135	* @param DateTimeImmutable $requested DateTime extracted from request input
	136	* (should come from extractRequestedDateTime)
	137	*
	138	* @return \DateTimeInterface Last DateTime of the time period
	139	*
	140	* @throws Exception Type not supported.
	141	*/
	142	public static function getEndDateTimeByType(string $type, DateTimeImmutable $requested): \DateTimeInterface
	143	{
	144	switch ($type) {
	145	case static::MONTH:
	146	return $requested->modify('last day of this month 23:59:59');
	147	case static::WEEK:
	148	return $requested->modify('Sunday this week 23:59:59');
	149	case static::DAY:
	150	return $requested->modify('Today 23:59:59');
	151	default:
	152	throw new Exception('Unsupported daily format type');
	153	}
	154	}
	155
	156	/**
	157	* Get localized description of the time period depending on given datetime and type.
	158	* Example: for a month period, it returns `October, 2020`.
	159	*
	160	* @param string $type month/week/day
	161	* @param \DateTimeImmutable $requested DateTime extracted from request input
	162	* (should come from extractRequestedDateTime)
	163	* @param bool $includeRelative Include relative date description (today, yesterday, etc.)
	164	*
	165	* @return string Localized time period description
	166	*
	167	* @throws Exception Type not supported.
	168	*/
	169	public static function getDescriptionByType(
	170	string $type,
	171	\DateTimeImmutable $requested,
	172	bool $includeRelative = true
	173	): string {
	174	switch ($type) {
	175	case static::MONTH:
	176	return $requested->format('F') . ', ' . $requested->format('Y');
	177	case static::WEEK:
	178	$requested = $requested->modify('Monday this week');
	179	return t('Week') . ' ' . $requested->format('W') . ' (' . format_date($requested, false) . ')';
	180	case static::DAY:
	181	$out = '';
	182	if ($includeRelative && $requested->format('Ymd') === date('Ymd')) {
	183	$out = t('Today') . ' - ';
	184	} elseif ($includeRelative && $requested->format('Ymd') === date('Ymd', strtotime('-1 days'))) {
	185	$out = t('Yesterday') . ' - ';
	186	}
	187	return $out . format_date($requested, false);
	188	default:
	189	throw new Exception('Unsupported daily format type');
	190	}
	191	}
	192
	193	/**
	194	* Get the number of items to display in the RSS feed depending on the given type.
	195	*
	196	* @param string $type month/week/day
	197	*
	198	* @return int number of elements
	199	*
	200	* @throws Exception Type not supported.
	201	*/
	202	public static function getRssLengthByType(string $type): int
	203	{
	204	switch ($type) {
	205	case static::MONTH:
	206	return 12; // 1 year
	207	case static::WEEK:
	208	return 26; // ~6 months
	209	case static::DAY:
	210	return 30; // ~1 month
	211	default:
	212	throw new Exception('Unsupported daily format type');
	213	}
	214	}
	215
	216	/**
	217	* Get the number of items to display in the RSS feed depending on the given type.
	218	*
	219	* @param string $type month/week/day
	220	* @param ?DateTimeImmutable $requested Currently only used for UT
	221	*
	222	* @return DatePeriod number of elements
	223	*
	224	* @throws Exception Type not supported.
	225	*/
	226	public static function getCacheDatePeriodByType(string $type, DateTimeImmutable $requested = null): DatePeriod
	227	{
	228	$requested = $requested ?? new DateTimeImmutable();
	229
	230	return new DatePeriod(
	231	static::getStartDateTimeByType($type, $requested),
	232	new \DateInterval('P1D'),
	233	static::getEndDateTimeByType($type, $requested)
	234	);
	235	}
	236	}