PHPDoc return type with extended Factory pattern

I want to use an abstract base class with common functionality for factories to extend, which works, but I don't know how to accurately specify the return type and have it detected by PHPStorm.

Here's an example. Is there a way I can document in PHPDoc that AppleFactory::make() returns AppleInterface and OrangeFactory::make() returns OrangeInterface?

<?php
namespace App\Factories;

abstract class AbstractFactory {

    /** @var array $drivers */
    protected $drivers;

    /**
     * instantiate the driver based on the given driver identifier
     * @param string $driver Driver identifier.
     * @return ???
     * @throws UnknownDriverException If driver string is not in list of available drivers.
     */
    public function make($driver) {
        $class = $this->className($driver);

        if (is_null($class))
            throw new UnknownDriverException($driver);

        return new $class;
    }

    /**
     * get the full class name for the driver
     * @param string $driver String mapping of class.
     * @return string
     */
    public function className($driver) {
        return isset($this->drivers[$driver]) ? $this->drivers[$driver] : null;
    }

}

class AppleFactory extends AbstractFactory {

    protected $drivers = [
        // both implement AppleInterface
        'fuji' => \App\Apples\Fuji::class,
        'gala' => \App\Apples\Gala::class
    ];

}

class OrangeFactory extends AbstractFactory {

    protected $drivers = [
        // both implement OrangeInterface
        'navel' => \App\Oranges\Navel::class,
        'blood' => \App\Oranges\Blood::class
    ];

}

Solution

Is there a way I can document in PHPDoc that AppleFactory::make() returns AppleInterface and OrangeFactory::make() returns OrangeInterface?

Based on your requirements above - a standard @method should do the job -- needs to be placed in PHPDoc comment for that class (AppleFactory and OrangeFactory accordingly). Something like this:

 @method AppleInterface make($driver)

At the same time, since you do pass parameter to a factory method .. and returned instance has strong relation to that -- have a look at Advanced Metadata support in PhpStorm (IDE specific functionality). This is what Laravel IDE helper (for example) uses to provide better IDE integration with this framework.

More on this: https://confluence.jetbrains.com/display/PhpStorm/PhpStorm+Advanced+Metadata