feature: add Hours endpoint

README.md

@@ -102,7 +102,7 @@ $locations = $client->space()->locations()->cache()->send();
 It is recommended to consult your Simple Cache client's documentation on how to best set up the cache to preserve entries between processes.
 
 ## Limitations
-This client currently only implements the Spaces/Seats endpoints under `/space`.
+This client currently only implements the Spaces/Seats endpoints under `/space` and and the Hours endpoint at `/hours`.
 
 ## Related Projects
 [An application that provides a public interface for space booking](https://github.com/bgsu-lits/book) using this library is also available from the BGSU University Libraries.

src/Action/HoursAction.php

@@ -0,0 +1,115 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lits\LibCal\Action;
+
+use Lits\LibCal\Action;
+use Lits\LibCal\Client;
+use Lits\LibCal\Data\Hours\HoursData;
+use Lits\LibCal\Exception\ActionException;
+
+/** Action to get opening hours for a location. */
+class HoursAction extends Action
+{
+    use TraitIdMultiple;
+    use TraitCache;
+    use TraitCache;
+
+    public ?string $from = null;
+    public ?string $to = null;
+
+    /**
+     * Set the date to retrieve hours from.
+     *
+     * @param string|\DateTimeInterface|null $from Value to set. Strings should
+     *                                             be in yyyy-mm-dd format
+     * @return self A reference to this object for method chaining.
+     * @throws ActionException If an invalid date is specified.
+     */
+    final public function setFrom($from): self
+    {
+        $this->from = self::buildDateString($from);
+
+        return $this;
+    }
+
+    /**
+     * Set the date to retrieve hours to.
+     *
+     * @param string|\DateTimeInterface|null $to Value to set. Strings should
+     *                                           be in yyyy-mm-dd format
+     * @return self A reference to this object for method chaining.
+     * @throws ActionException If an invalid date is specified.
+     */
+    final public function setTo($to): self
+    {
+        $this->to = self::buildDateString($to);
+
+        return $this;
+    }
+
+    /**
+     * @return HoursData[]
+     * @throws \Lits\LibCal\Exception\ClientException
+     */
+    final public function send(): array
+    {
+        $uri = '/' . Client::VERSION . '/hours';
+        $uri = $this->addId($uri);
+        $uri = self::addQuery($uri, 'from', $this->from);
+        $uri = self::addQuery($uri, 'to', $this->to);
+
+        /** @var HoursData[] $result */
+        $result = $this->memoize(
+            $uri,
+            fn (string $uri) => HoursData::fromJsonAsArray(
+                $this->client->get($uri)
+            )
+        );
+
+        return $result;
+    }
+
+    /**
+     * Return a date string in 'yyyy-mm-dd' format.
+     *
+     * @param string|\DateTimeInterface|null $date The date.
+     * @return string|null The date in 'yyyy-mm-dd' format. Null if null input.
+     * @throws ActionException If an invalid date is specified.
+     */
+    private static function buildDateString($date): ?string
+    {
+        if (\is_null($date)) {
+            return null;
+        }
+
+        if ($date instanceof \DateTimeInterface) {
+            return $date->format('Y-m-d');
+        }
+
+        if (!self::dateStringIsValid($date)) {
+            throw new ActionException('Invalid date specified');
+        }
+
+        return $date;
+    }
+
+    /**
+     * Is string date in 'yyyy-mm-dd' format?
+     *
+     * @param string $date Value to set.
+     * @return bool true if the string is in 'yyyy-mm-dd' format,
+     *              false if not
+     */
+    private static function dateStringIsValid(string $date): bool
+    {
+        $date = \filter_var(
+            $date,
+            \FILTER_VALIDATE_REGEXP,
+            ['options' => ['regexp' => '/^\d{4}-\d{2}-\d{2}$/']]
+        );
+
+        return $date !== false;
+    }
+}

src/Client.php

@@ -4,6 +4,7 @@
 
 namespace Lits\LibCal;
 
+use Lits\LibCal\Action\HoursAction;
 use Lits\LibCal\Action\SpaceAction;
 use Lits\LibCal\Data\TokenData;
 use Lits\LibCal\Exception\ClientException;
@@ -182,6 +183,17 @@ public function space(): SpaceAction
         return new SpaceAction($this);
     }
 
+    /**
+     * Retrieve action for LibCal Hours API.
+     *
+     * @param int|int[] $id The id of the location to retrieve.
+     * @return HoursAction Hours lookup action.
+     */
+    public function hours($id): HoursAction
+    {
+        return new HoursAction($this, $id);
+    }
+
     /**
      * Get any memoized value from cache or memory.
      *

src/Data/Hours/DateData.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lits\LibCal\Data\Hours;
+
+use Lits\LibCal\Data;
+
+class DateData extends Data
+{
+    public ?string $status = null;
+
+    public ?string $note = null;
+
+    /** @var OpeningHoursData[] */
+    public array $hours = [];
+}

src/Data/Hours/HoursData.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lits\LibCal\Data\Hours;
+
+use Lits\LibCal\Data;
+
+class HoursData extends Data
+{
+    public ?int $lid = null;
+    public ?string $name = null;
+    public ?string $category = null;
+    public ?string $desc = null;
+
+    public ?string $url = null;
+    public ?string $contact = null;
+    public ?string $lat = null;
+    public ?string $lon = null;
+    public ?string $color = null;
+    public ?string $fn = null;
+
+    public string $parent_lid;
+
+    /** @var DateData[] $dates */
+    public array $dates = [];
+}

src/Data/Hours/OpeningHoursData.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Lits\LibCal\Data\Hours;
+
+use Lits\LibCal\Data;
+
+class OpeningHoursData extends Data
+{
+    public ?string $from = null;
+    public ?string $to = null;
+}