phan/phan

Hello,

With the method below:

private function getDocumentRoot(): string
{
    return realpath(__DIR__ . "/web/");
}

Phan returns the following error:

PhanPossiblyFalseTypeReturn Returning realpath((__DIR__ . '/web/')) of type false|string but getDocumentRoot() is declared to return string (false is incompatible)

It is an entirely valid error: realpath() can return string or false, while getDocumentRoot() is declared to return a string exclusively.

My question is: how to address this issue in the state of the art?

The options I thought about are the following:

1) Specific Exception:

private function getDocumentRoot(): string
{
    $result = realpath(__DIR__ . "/web/");

    if (!is_string($result)) {
        throw new \RuntimeException("Cannot compute document root");
    }

    return $result;
}

While this makes the Phan error dissappear, it just changes the way to catch the exception from \TypeError to \RuntimeException. Somehow it feels non natural to remap the \TypeError to something else, this leads to the next option:

2) Throwing \TypeError manually:

private function getDocumentRoot(): string
{
    $result = realpath(__DIR__ . "/web/");

    if (!is_string($result)) {
        throw new \TypeError("Cannot compute document root");
    }

    return $result;
}

As option 1), it "solves" the reported issue, however it re-implements the natural behaviour of PHP itself: it really feels like boilerplate code.

3) Acknowledging that a TypeError can occur:

/**
 * @throws \TypeError
 */
private function getDocumentRoot(): string
{
    return realpath(__DIR__ . "/web/");
}

While potentially no additional code involved, it could "mark" that a \TypeError is possible and should not be reported as something not handled. However, using @throws does not make the issue dissappear.

4) Suppressing the issue locally:

/**
 * @suppress PhanPossiblyFalseTypeReturn
 */
private function getDocumentRoot(): string
{
    return realpath(__DIR__ . "/web/");
}

This is supressing the issue, however, I feel that @suppress is more like a workaround to tackle edge cases while this seems pretty common. It also feels more like silencing it over declaring an intention.

I'd like to know how you usually deal with that situation and what the best practices are.