1<?php
2
3namespace Sabre\HTTP;
4
5/**
6 * The MessageInterface is the base interface that's used by both
7 * the RequestInterface and ResponseInterface.
8 *
9 * @copyright Copyright (C) fruux GmbH (https://fruux.com/)
10 * @author Evert Pot (http://evertpot.com/)
11 * @license http://sabre.io/license/ Modified BSD License
12 */
13interface MessageInterface {
14
15    /**
16     * Returns the body as a readable stream resource.
17     *
18     * Note that the stream may not be rewindable, and therefore may only be
19     * read once.
20     *
21     * @return resource
22     */
23    function getBodyAsStream();
24
25    /**
26     * Returns the body as a string.
27     *
28     * Note that because the underlying data may be based on a stream, this
29     * method could only work correctly the first time.
30     *
31     * @return string
32     */
33    function getBodyAsString();
34
35    /**
36     * Returns the message body, as it's internal representation.
37     *
38     * This could be either a string or a stream.
39     *
40     * @return resource|string
41     */
42    function getBody();
43
44    /**
45     * Updates the body resource with a new stream.
46     *
47     * @param resource|string $body
48     * @return void
49     */
50    function setBody($body);
51
52    /**
53     * Returns all the HTTP headers as an array.
54     *
55     * Every header is returned as an array, with one or more values.
56     *
57     * @return array
58     */
59    function getHeaders();
60
61    /**
62     * Will return true or false, depending on if a HTTP header exists.
63     *
64     * @param string $name
65     * @return bool
66     */
67    function hasHeader($name);
68
69    /**
70     * Returns a specific HTTP header, based on it's name.
71     *
72     * The name must be treated as case-insensitive.
73     * If the header does not exist, this method must return null.
74     *
75     * If a header appeared more than once in a HTTP request, this method will
76     * concatenate all the values with a comma.
77     *
78     * Note that this not make sense for all headers. Some, such as
79     * `Set-Cookie` cannot be logically combined with a comma. In those cases
80     * you *should* use getHeaderAsArray().
81     *
82     * @param string $name
83     * @return string|null
84     */
85    function getHeader($name);
86
87    /**
88     * Returns a HTTP header as an array.
89     *
90     * For every time the HTTP header appeared in the request or response, an
91     * item will appear in the array.
92     *
93     * If the header did not exists, this method will return an empty array.
94     *
95     * @param string $name
96     * @return string[]
97     */
98    function getHeaderAsArray($name);
99
100    /**
101     * Updates a HTTP header.
102     *
103     * The case-sensitity of the name value must be retained as-is.
104     *
105     * If the header already existed, it will be overwritten.
106     *
107     * @param string $name
108     * @param string|string[] $value
109     * @return void
110     */
111    function setHeader($name, $value);
112
113    /**
114     * Sets a new set of HTTP headers.
115     *
116     * The headers array should contain headernames for keys, and their value
117     * should be specified as either a string or an array.
118     *
119     * Any header that already existed will be overwritten.
120     *
121     * @param array $headers
122     * @return void
123     */
124    function setHeaders(array $headers);
125
126    /**
127     * Adds a HTTP header.
128     *
129     * This method will not overwrite any existing HTTP header, but instead add
130     * another value. Individual values can be retrieved with
131     * getHeadersAsArray.
132     *
133     * @param string $name
134     * @param string $value
135     * @return void
136     */
137    function addHeader($name, $value);
138
139    /**
140     * Adds a new set of HTTP headers.
141     *
142     * Any existing headers will not be overwritten.
143     *
144     * @param array $headers
145     * @return void
146     */
147    function addHeaders(array $headers);
148
149    /**
150     * Removes a HTTP header.
151     *
152     * The specified header name must be treated as case-insenstive.
153     * This method should return true if the header was successfully deleted,
154     * and false if the header did not exist.
155     *
156     * @param string $name
157     * @return bool
158     */
159    function removeHeader($name);
160
161    /**
162     * Sets the HTTP version.
163     *
164     * Should be 1.0 or 1.1.
165     *
166     * @param string $version
167     * @return void
168     */
169    function setHttpVersion($version);
170
171    /**
172     * Returns the HTTP version.
173     *
174     * @return string
175     */
176    function getHttpVersion();
177
178}
179