Intermittent PHP warning: "imap_open(): Couldn't open stream"

I have a cron job that pulls emails from a gmail account once every 5 minutes. I am using the ddboer/imap library to authentication and every so often (approx once every 2 - 3 days) it has an issue connecting.

My code is fairly basic and looks something like this:

$server = new Server('imap.gmail.com');

try {
    $connection = $server->authenticate($username, $password);
} catch (Exception $e) {
    echo $e->getMessage();
}

The output when it fails is:

[E_WARNING] Authentication failed for user "user@example.com": imap_open(): Couldn't open stream {imap.gmail.com:993/imap/ssl/validate-cert}
imap_alerts (0):
imap_errors (1):
- Can not authenticate to IMAP server: [CLOSED] IMAP connection broken (authenticate)

It has been very difficult to troubleshoot since the issue is intermittent. The following common issues have already been addressed:

Less Secure Apps have been enabled/allowed
Display Unlock Captcha has been completed
Credentials, port and endpoint are all correct
My server's network is not experiencing connectivity issues during times when it fails to connect

The important thing to note here is that the script succeeds +99% of the time and only fails occasionally, but it happens regularly enough that it prompted this question.

Solution

Given that:

your code almost always works
you're connecting to a server that you have no control over
this server may be thousands of kilometres away, with dozens of networks between you

I'd just accept that sometimes $#i† happens, and make sure you're prepared for it:

$server = new Server('imap.gmail.com');

$retries = -1;
while (true) {
    try {
        $connection = $server->authenticate($username, $password);
        break;
    } catch (Exception $e) {
        if ($retries++ > 2) {
            echo $e->getMessage();
            break;
        }
        sleep(pow(2, $retries));
    }
}

So in case of an error, this would retry after 1 second, then retry after 2 seconds, then retry after 4 seconds, before giving up. Tweak these thresholds as needed.