1<?php
  2
  3// SPDX-FileCopyrightText: 2004-2023 Ryan Parman, Sam Sneddon, Ryan McCue
  4// SPDX-FileCopyrightText: 2014 PHP Framework Interoperability Group
  5// SPDX-License-Identifier: MIT
  6
  7declare(strict_types=1);
  8
  9namespace SimplePie\HTTP;
 10
 11/**
 12 * HTTP Response interface
 13 *
 14 * This interface must be interoperable with Psr\Http\Message\ResponseInterface
 15 * @see https://www.php-fig.org/psr/psr-7/#33-psrhttpmessageresponseinterface
 16 *
 17 * @internal
 18 */
 19interface Response
 20{
 21    /**
 22     * Return the string representation of the permanent URI of the requested resource
 23     * (the first location after a prefix of (only) permanent redirects).
 24     *
 25     * Depending on which components of the URI are present, the resulting
 26     * string is either a full URI or relative reference according to RFC 3986,
 27     * Section 4.1. The method concatenates the various components of the URI,
 28     * using the appropriate delimiters:
 29     *
 30     * - If a scheme is present, it MUST be suffixed by ":".
 31     * - If an authority is present, it MUST be prefixed by "//".
 32     * - The path can be concatenated without delimiters. But there are two
 33     *   cases where the path has to be adjusted to make the URI reference
 34     *   valid as PHP does not allow to throw an exception in __toString():
 35     *     - If the path is rootless and an authority is present, the path MUST
 36     *       be prefixed by "/".
 37     *     - If the path is starting with more than one "/" and no authority is
 38     *       present, the starting slashes MUST be reduced to one.
 39     * - If a query is present, it MUST be prefixed by "?".
 40     * - If a fragment is present, it MUST be prefixed by "#".
 41     *
 42     * @see http://tools.ietf.org/html/rfc3986#section-4.1
 43     */
 44    public function get_permanent_uri(): string;
 45
 46    /**
 47     * Return the string representation of the final requested URL after following all redirects.
 48     *
 49     * Depending on which components of the URI are present, the resulting
 50     * string is either a full URI or relative reference according to RFC 3986,
 51     * Section 4.1. The method concatenates the various components of the URI,
 52     * using the appropriate delimiters:
 53     *
 54     * - If a scheme is present, it MUST be suffixed by ":".
 55     * - If an authority is present, it MUST be prefixed by "//".
 56     * - The path can be concatenated without delimiters. But there are two
 57     *   cases where the path has to be adjusted to make the URI reference
 58     *   valid as PHP does not allow to throw an exception in __toString():
 59     *     - If the path is rootless and an authority is present, the path MUST
 60     *       be prefixed by "/".
 61     *     - If the path is starting with more than one "/" and no authority is
 62     *       present, the starting slashes MUST be reduced to one.
 63     * - If a query is present, it MUST be prefixed by "?".
 64     * - If a fragment is present, it MUST be prefixed by "#".
 65     *
 66     * @see http://tools.ietf.org/html/rfc3986#section-4.1
 67     */
 68    public function get_final_requested_uri(): string;
 69
 70    /**
 71     * Gets the response status code.
 72     *
 73     * The status code is a 3-digit integer result code of the server's attempt
 74     * to understand and satisfy the request.
 75     *
 76     * @return int Status code.
 77     */
 78    public function get_status_code(): int;
 79
 80    /**
 81     * Retrieves all message header values.
 82     *
 83     * The keys represent the header name as it will be sent over the wire, and
 84     * each value is an array of strings associated with the header.
 85     *
 86     *     // Represent the headers as a string
 87     *     foreach ($message->get_headers() as $name => $values) {
 88     *         echo $name . ': ' . implode(', ', $values);
 89     *     }
 90     *
 91     *     // Emit headers iteratively:
 92     *     foreach ($message->get_headers() as $name => $values) {
 93     *         foreach ($values as $value) {
 94     *             header(sprintf('%s: %s', $name, $value), false);
 95     *         }
 96     *     }
 97     *
 98     * @return array<non-empty-array<string>> Returns an associative array of the message's headers.
 99     *     Each key MUST be a header name, and each value MUST be an array of
100     *     strings for that header.
101     */
102    public function get_headers(): array;
103
104    /**
105     * Checks if a header exists by the given case-insensitive name.
106     *
107     * @param string $name Case-insensitive header field name.
108     * @return bool Returns true if any header names match the given header
109     *     name using a case-insensitive string comparison. Returns false if
110     *     no matching header name is found in the message.
111     */
112    public function has_header(string $name): bool;
113
114    /**
115     * Retrieves a message header value by the given case-insensitive name.
116     *
117     * This method returns an array of all the header values of the given
118     * case-insensitive header name.
119     *
120     * If the header does not appear in the message, this method MUST return an
121     * empty array.
122     *
123     * @param string $name Case-insensitive header field name.
124     * @return string[] An array of string values as provided for the given
125     *    header. If the header does not appear in the message, this method MUST
126     *    return an empty array.
127     */
128    public function get_header(string $name): array;
129
130    /**
131     * Return an instance with the provided value replacing the specified header.
132     *
133     * This method MUST be implemented in such a way as to retain the
134     * immutability of the message, and MUST return an instance that has the
135     * new and/or updated header and value.
136     *
137     * @param string $name Case-insensitive header field name.
138     * @param string|non-empty-array<string> $value Header value(s).
139     * @return static
140     * @throws \InvalidArgumentException for invalid header names or values.
141     */
142    public function with_header(string $name, $value);
143
144    /**
145     * Retrieves a comma-separated string of the values for a single header.
146     *
147     * This method returns all of the header values of the given
148     * case-insensitive header name as a string concatenated together using
149     * a comma.
150     *
151     * NOTE: Not all header values may be appropriately represented using
152     * comma concatenation. For such headers, use getHeader() instead
153     * and supply your own delimiter when concatenating.
154     *
155     * If the header does not appear in the message, this method MUST return
156     * an empty string.
157     *
158     * @param string $name Case-insensitive header field name.
159     * @return string A string of values as provided for the given header
160     *    concatenated together using a comma. If the header does not appear in
161     *    the message, this method MUST return an empty string.
162     */
163    public function get_header_line(string $name): string;
164
165    /**
166     * get the body as string
167     *
168     * @return string
169     */
170    public function get_body_content(): string;
171}
172