index/src/Io/NetworkStream.php

<?php
// NetworkStream.php
// Created: 2021-04-30
// Updated: 2024-10-02

namespace Index\Io;

use ErrorException;
use RuntimeException;
use Index\Net\{IpAddress,EndPoint};

/**
 * Represents a network socket stream.
 */
class NetworkStream extends GenericStream {
    /**
     * @param string $hostname Hostname to connect to.
     * @param int $port Port to connect at.
     * @param float|null $timeout Amount of seconds until timeout, null for php.ini default.
     * @throws RuntimeException If the socket failed to open.
     */
    public function __construct(string $hostname, int $port, float|null $timeout) {
        try {
            $stream = fsockopen($hostname, $port, $errcode, $errmsg, $timeout);
        } catch(ErrorException $ex) {
            throw new RuntimeException('An error occurred while trying to connect.', $ex->getCode(), $ex);
        }

        if($stream === false)
            throw new RuntimeException('An unhandled error occurred while trying to connect.');

        parent::__construct($stream);
    }

    /**
     * Sets whether the network stream should have blocking reads and writes.
     *
     * @param bool $blocking true to block, false to async.
     */
    public function setBlocking(bool $blocking): void {
        stream_set_blocking($this->stream, $blocking);
    }

    /**
     * Opens a network socket stream to an endpoint represented by an Index EndPoint instance.
     *
     * @param EndPoint $endPoint Host to connect to.
     * @param float|null $timeout Amount of seconds until timeout, null for php.ini default.
     */
    public static function openEndPoint(EndPoint $endPoint, float|null $timeout = null): NetworkStream {
        return new NetworkStream((string)$endPoint, -1, $timeout);
    }

    /**
     * Opens an SSL network socket stream to an endpoint represented by an Index EndPoint instance.
     *
     * @param EndPoint $endPoint Host to connect to.
     * @param float|null $timeout Amount of seconds until timeout, null for php.ini default.
     */
    public static function openEndPointSSL(EndPoint $endPoint, float|null $timeout = null): NetworkStream {
        return new NetworkStream('ssl://' . ((string)$endPoint), -1, $timeout);
    }

    /**
     * Opens a TLS network socket stream to an endpoint represented by an Index EndPoint instance.
     *
     * @param EndPoint $endPoint Host to connect to.
     * @param float|null $timeout Amount of seconds until timeout, null for php.ini default.
     */
    public static function openEndPointTLS(EndPoint $endPoint, float|null $timeout = null): NetworkStream {
        return new NetworkStream('tls://' . ((string)$endPoint), -1, $timeout);
    }

    /**
     * Opens a network socket stream to an endpoint represented by an hostname and port.
     *
     * @param string $hostname Hostname to connect to.
     * @param int $port Port to connect at.
     * @param float|null $timeout Amount of seconds until timeout, null for php.ini default.
     */
    public static function openHost(string $hostname, int $port, float|null $timeout = null): NetworkStream {
        return new NetworkStream($hostname, $port, $timeout);
    }

    /**
     * Opens an SSL network socket stream to an endpoint represented by an hostname and port.
     *
     * @param string $hostname Hostname to connect to.
     * @param int $port Port to connect at.
     * @param float|null $timeout Amount of seconds until timeout, null for php.ini default.
     */
    public static function openHostSSL(string $hostname, int $port, float|null $timeout = null): NetworkStream {
        return new NetworkStream('ssl://' . ((string)$hostname), $port, $timeout);
    }

    /**
     * Opens a TLS network socket stream to an endpoint represented by an hostname and port.
     *
     * @param string $hostname Hostname to connect to.
     * @param int $port Port to connect at.
     * @param float|null $timeout Amount of seconds until timeout, null for php.ini default.
     */
    public static function openHostTLS(string $hostname, int $port, float|null $timeout = null): NetworkStream {
        return new NetworkStream('tls://' . ((string)$hostname), $port, $timeout);
    }

    /**
     * Opens a network socket stream to an endpoint represented by an Index IpAddress instance and port.
     *
     * @param IpAddress $address Address to connect to.
     * @param int $port Port to connect at.
     * @param float|null $timeout Amount of seconds until timeout, null for php.ini default.
     */
    public static function openAddress(IpAddress $address, int $port, float|null $timeout = null): NetworkStream {
        return new NetworkStream($address->getAddress(), $port, $timeout);
    }

    /**
     * Opens an SSL network socket stream to an endpoint represented by an Index IpAddress instance and port.
     *
     * @param IpAddress $address Address to connect to.
     * @param int $port Port to connect at.
     * @param float|null $timeout Amount of seconds until timeout, null for php.ini default.
     */
    public static function openAddressSSL(IpAddress $address, int $port, float|null $timeout = null): NetworkStream {
        return new NetworkStream('ssl://' . $address->getAddress(), $port, $timeout);
    }

    /**
     * Opens a TLS network socket stream to an endpoint represented by an Index IpAddress instance and port.
     *
     * @param IpAddress $address Address to connect to.
     * @param int $port Port to connect at.
     * @param float|null $timeout Amount of seconds until timeout, null for php.ini default.
     */
    public static function openAddressTLS(IpAddress $address, int $port, float|null $timeout = null): NetworkStream {
        return new NetworkStream('tls://' . $address->getAddress(), $port, $timeout);
    }

    /**
     * Opens a network socket stream to an endpoint represented by a UNIX socket path.
     *
     * @param string $path Path to connect to.
     * @param float|null $timeout Amount of seconds until timeout, null for php.ini default.
     */
    public static function openUnix(string $path, float|null $timeout = null): NetworkStream {
        return new NetworkStream('unix://' . $path, -1, $timeout);
    }
}