IDE friendly API

[stof]

It would be great if the different sub-APIs could be exposed through dedicated methods in the main client rather than having to use ->api('issues') which breaks any kind of autocompletion or type checks on the library usage.

[jbrooksuk]

Technically all the api method is doing is just calling initialising a class. That's all the dedicated methods would have to do.

[stof]

yep, but the api() method is not friendly with the IDE, because the returned classes all have a different API. So the only thing the IDE can knwo about them is that them implement setPerPage($perPage) and getPerPage(), which is quite useless. Having dedicated methods would allow documenting the return type of each method properly

[jbrooksuk]

Yeah, I completely agree. Would the IDE be able to pick up the magic __call method?

[jbrooksuk]

@stof not sure if you read my previous comment, but GitHub hid the second part of it.

[stof]

@jbrooksuk if you document them properly with @method on the class, yes

[jbrooksuk]

That's probably a good way of doing it then, I'd say.

/**
 * @param string $name
 *
 * @method me()
 * @method current_user()
 * 
 * @return ApiInterface
 *
 * @throws InvalidArgumentException
 */
public function __call($name) {
    switch ($name) {
        case 'me':
        case 'current_user':
            $api = new Api\CurrentUser($this);
            break;

        case 'ent':
        case 'enterprise':
            $api = new Api\Enterprise($this);
            break;

        case 'git':
        case 'git_data':
            $api = new Api\GitData($this);
            break;

        case 'gist':
        case 'gists':
            $api = new Api\Gists($this);
            break;

        case 'issue':
        case 'issues':
            $api = new Api\Issue($this);
            break;

        case 'markdown':
            $api = new Api\Markdown($this);
            break;

        case 'organization':
        case 'organizations':
            $api = new Api\Organization($this);
            break;

        case 'pr':
        case 'pull_request':
        case 'pull_requests':
            $api = new Api\PullRequest($this);
            break;

        case 'repo':
        case 'repos':
        case 'repository':
        case 'repositories':
            $api = new Api\Repo($this);
            break;

        case 'team':
        case 'teams':
            $api = new Api\Organization\Teams($this);
            break;

        case 'user':
        case 'users':
            $api = new Api\User($this);
            break;

        case 'authorization':
        case 'authorizations':
            $api = new Api\Authorizations($this);
            break;

        case 'meta':
            $api = new Api\Meta($this);
            break;

        default:
            throw new InvalidArgumentException(sprintf('Undefined api instance called: "%s"', $name));
    }

    return $api;
}

I don't use the @method block, so I'm not sure how it works, but the actual code should.

[stof]

@method goes in the class phpdoc, not in the method phpdoc.

/**
 * @method Api\CurrentUser currentUser()
 * @method Api\CurrentUser me()
 */
class Client
{
    // ...
}

and as shown in my sample, I would use a camelCased method name rather than underscores.

[jbrooksuk]

Ah right, I see. That's easily doable. If I make a PR, will @knpEdgar merge?

[Nek-]

I'm 👍 with it :) .

[GrahamCampbell]

👍 for 1.3 or 2.0.

[jbrooksuk]

Ok guys, I'll do it now 😄

[stof]

given that adding this API (without removing ->api($type)) is BC, it can go in 1.3

[jbrooksuk]

This change seems too simple... Adding a PR now.