Moving forward: a TODO

[bjornpost]

Some refactoring ideas to improve the library, ideas are mostly proposed to reduce code complexity for the main classes (HarvestApi and HarvestReport):

• Reduce \Harvest\HarvestApi (maybe rename it to ..\Connection?) to something which will just handle authentication and create a \Harvest\HttpClient instance (we should be able to overload the used client class, f.e. \Harvest\Test\MockedHttpClient, which will use cached responses).
• Move the methods of each API (Tasks, Clients, Projects, Time, etc.) to its own class. This will introduce a new class for each API, f.e. \Harvest\Api\Tasks, with the methods getTasks, getTask, create.., update.., delete... You get the point. While we're at it we can also rename them to something a bit more concise, like list(), get(), create(), etc.
• Introduce a protected $properties on each Model which describes valid attributes in a XML request/response and their type (int, string, DateTime, etc.). We could do some marshaling to convert these values when reading from the API, so we return a DateTime object instead of a string.

A rough idea of how these changes could affect the public API:

<?php
    $harvest = new \Harvest\HarvestApi;
    $harvest->authenticate('user', 'pass');
    try {
        /**
         * The api() method will return a \Harvest\Api\X instance or throws
         * a \Harvest\Exception\UnknownApiException because the requested
         * API does not exist. The index() call will return the actual data.
         *
         */
        $tasks = $harvest->api('task')->index();
    } catch (\Harvest\Exception $e) {
        /**
         * A bunch of Exceptions could be thrown, like:
         *  - \Harvest\Exception\AuthenticationException
         *  - \Harvest\Exception\UnknownApiException
         *  - \Harvest\Exception\IncompleteRequestException
         *  - \Harvest\Exception\ApiLimitExceedException
         *  - ...?
         *
         */
    }

When we start moving things around, we should think about how we can make the library easy to test without requiring an internet connection. Maybe we could mock HTTP requests and responses? That way we know for sure our requests were valid at one point in time, but we won't be notified if Harvest decides to update their API (and syntax). Our tests will still pass.

[bjornpost]

Thoughts, @peschee?

[bjornpost]

Update; I've started working on this in bjornpost/hapi/rewrite.

[peschee]

Hey @bjornpost, sorry for my late reply. I'm currently quite busy. The steps you outlines seem totally valid to me. I'm currently not using the Harvest API anywhere in production, but I think we should think about proper testing of all the API methods.

Maybe you could have a look at using https://github.com/guzzle/guzzle as a dependency for the underlying HTTP communication. This would probably also ease the testing, since we could start using mocks http://docs.guzzlephp.org/en/latest/testing.html?highlight=mock I assume testing against the live API ist not very practical, even though yes, we won't notice when Harvest changes something. For proper internet tests, Harvest should provide a test account with example data. I'm not sure they offer that.