PHP OOP: Unique method per argument type?

Question

I'm writing a little homebrew ORM (academic interest). I'm trying to adhere to the TDD concept as a training exercise, and as part of that exercise I'm writing documentation for the API as I develop the class.

Case in point - I'm working on a classic "getCollection" type mapper class. I want it to be able to retrieve collections of asset X (let's say blog posts) for a specific user, and also collections based on an arbitrary array of numeric values. So - you might have a method like any one of these

$User = $UserMapper->load(1);
$ArticleCollection = $ArticleMapper->getCollection(range(10,20));
$ArticleCollection = $ArticleMapper->getCollection($User);
$ArticleCollection = $ArticleMapper->getCollection($User->getId());

So, in writing the documentation for the getCollection method - I want to declare the @param variable in the Docblock. Is it better to have a unique method for each argument type, or is it acceptable to have a method that delegates to the correct internal method/class based on argument type?

Answer 1

It is acceptable to have a method that delegates to the correct internal method. You could document it like this:

@param Array|User|Integer $argName optional explanation

but then again, there is no one hindering you having one method each

public function getCollectionByRange(array $range)
public function getCollectionByUser(User $user)
public function getCollectionByUserId($id)

In addition, you could use the magic __call method to pretend the above methods exist and then capture method calls to them and delegate to your internal methods (ZF does that f.i. for finding dependant database rows). You would document these methods with the @method annotation in the Class DocBlock. But keep in mind that the magic methods are always slower over having and/or calling the appropriate methods directly.

Use what you think makes most sense for your application and usecase.

Answer 2

You could achieve something like method overloading by checking the type of the passed parameter at runtime (PHP does not support this concept known from other languages like ADA, Java, C# or C++ e.g.):

[...]
/**
 * @param  User|array|integer $user
 * @return array
 */
public function getCollection($user) {
    // perhaps a switch-case would be better here
    if ($user instanceof User) {
        // do what has to be done if you passed in a User object
    } else if (is_int($user) {
        // do what has to be done if you passed in a user id
    } else if (is_array($user)) {
        // do what has to be done if you passed in an array of user ids
    }
}
[...]