ClientInterface.php

<?php

namespace OpenStack\Common\Transport;

/**
 * Describes a transport client.
 *
 * Transport clients are responsible for moving data from the remote cloud to
 * the local host. Transport clients are responsible only for the transport
 * protocol, not for the payloads.
 *
 * The current OpenStack services implementation is oriented toward
 * REST-based services, and consequently the transport layers are
 * HTTP/HTTPS, and perhaps SPDY some day. The interface reflects this.
 * it is not designed as a protocol-neutral transport layer
 */
interface ClientInterface
{
    /**
     * Create a new Request object.
     *
     * @param string          $method  HTTP method
     * @param string|Url      $uri     URL the request will send to
     * @param string|resource $body    Entity body being sent
     * @param array           $options Configuration options, such as headers
     *
     * @return RequestInterface
     */
    public function createRequest($method, $uri = null, $body = null, array $options = []);

    /**
     * Sends a request.
     *
     * @param RequestInterface $request Request to execute
     *
     * @return ResponseInterface
     */
    public function send(RequestInterface $request);

    /**
     * Sets a particular configuration option, depending on how the client
     * implements it. It could, for example, alter cURL configuration or a
     * default header.
     *
     * @param string $key   The key being updated
     * @param mixed  $value The value being set
     */
    public function setOption($key, $value);

    /**
     * Returns the value of a particular configuration option. If the options
     * is not set, NULL is returned.
     *
     * @param string $key The option name
     * @return mixed|null
     */
    public function getOption($key);

    /**
     * Returns the base URL that the client points towards.
     *
     * @return string
     */
    public function getBaseUrl();

    /**
     * Throws a semantic error based on the type of HTTP response that was
     * returned.
     *
     * @throw \Exception
     */
    public function handleRequestException(RequestInterface $request, ResponseInterface $response);
}