feature: add Hours endpoint

[Otterfan]

We use both the Spaces and Hours endpoints, so I added access to /hours.

$response = $client->hours([501, 23312])
                   ->setFrom('2024-06-01')
                   ->setTo('2024-06-02')
                   ->send();

Output looks like:

array(1) {
  [0]=>
  object(Lits\LibCal\Data\Hours\HoursData)#36 (11) {
    ["lid"]=>
    int(501)
    ["name"]=>
    string(15) "O'Neill Library"
    ["category"]=>
    string(7) "library"
    ["desc"]=>
    string(0) ""
    ["url"]=>
    string(37) "https://libguides.bc.edu/oneill/hours"
    ["contact"]=>
    string(0) ""
    ["lat"]=>
    string(0) ""
    ["lon"]=>
    NULL
    ["color"]=>
    string(7) "#000000"
    ["fn"]=>
    string(0) ""
    ["parent_lid"]=>
    uninitialized(string)
    ["dates"]=>
    array(2) {
      ["2024-06-01"]=>
      object(Lits\LibCal\Data\Hours\DateData)#54 (3) {
        ["status"]=>
        string(4) "open"
        ["note"]=>
        NULL
        ["hours"]=>
        array(1) {
          [0]=>
          object(Lits\LibCal\Data\Hours\OpeningHoursData)#50 (2) {
            ["from"]=>
            string(6) "9:00am"
            ["to"]=>
            string(6) "5:00pm"
          }
        }
      }
      ["2024-06-02"]=>
      object(Lits\LibCal\Data\Hours\DateData)#48 (3) {
        ["status"]=>
        string(4) "open"
        ["note"]=>
        NULL
        ["hours"]=>
        array(1) {
          [0]=>
          object(Lits\LibCal\Data\Hours\OpeningHoursData)#60 (2) {
            ["from"]=>
            string(7) "11:00am"
            ["to"]=>
            string(6) "7:00pm"
          }
        }
      }
    }
  }
}

It passes all tests under PHP7.4.

A couple of points to notice:

• The Hours API only has a single endpoint, which makes Client::hours($id) a little different from Client::space(). I tried to make it fit in spirit.

• The response format for the /hours endpoint is a bit wonky and isn't documented correctly in LibCal. Specifically, the dates value is not an array, it's an object with date strings as names and date objects as values. This makes it kind of hard to extract DateTime objects for hours without resorting to a HoursData::setDate() function.

  I decided to stick with the out-of-the-box functionality JsonMapper provides and just represent dates as an associative array keyed by the string value of the date ('2024-06-02') pointing to an object that contains hours as strings ('11:00am'). Our use case is display and not manipulation, so this was sufficient.

And thanks for the library, btw!

Cheers,
Ben

[kloor]

Thank you very much for this contribution. I've reviewed the code and commented on parts where there were mostly just style changes I would like to see, but all-in-all it works well.

I agree that it is probably best to use an associative array for the dates object to match what the API produces.

I did notice that if I set the from date ahead of the end date (which both default to the current date), the API errors out with this plain text error message:
"from" date cannot be later than "to" date

This is different than any of the /space endpoints, that would provide a JSON-formatted message. This results in the error the client produces being not particularly helpful, so the Client class should be updated to interpret non-JSON error responses as plain text. But, that isn't a necessary change for this pull request.

[kloor]

Organizationally, this should be before the space() method in this class.

[kloor]

Duplicate use Traitcache;

[kloor]

Entire class should be final instead of individual methods.

[kloor]

I think the buildDateString() and dateStringIsValid() static methods should just be put in the abstract Action class, so then they could also be used by TraitDate instead of duplicating code.

[kloor]

I'd probably name this isValidDateString() instead.

[kloor]

The type of $dates in the comment should be: array<string, DateData>

[kloor]

I'd probably make both $from and $to non-nullable as well.

[kloor]

Class should be final.

[kloor]

Class should be final.

[kloor]

Class should be final.