1:   2:   3:   4:   5:   6:   7:   8:   9:  10:  11:  12:  13:  14:  15:  16:  17:  18:  19:  20:  21:  22:  23:  24:  25:  26:  27:  28:  29:  30:  31:  32:  33:  34:  35:  36:  37:  38:  39:  40:  41:  42:  43:  44:  45:  46:  47:  48:  49:  50:  51:  52:  53:  54:  55:  56:  57:  58:  59:  60:  61:  62:  63:  64:  65:  66:  67:  68:  69:  70:  71:  72:  73:  74:  75:  76:  77:  78:  79:  80:  81:  82:  83:  84:  85:  86:  87:  88:  89:  90:  91:  92:  93:  94:  95:  96:  97:  98:  99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 230: 231: 232: 233: 234: 235: 236: 237: 238: 239: 240: 241: 242: 243: 244: 245: 246: 247: 248: 249: 250: 251: 252: 253: 254: 255: 256: 257: 258: 259: 260: 261: 262: 263: 264: 

<?php

/**
 * MvcCore
 *
 * This source file is subject to the BSD 3 License
 * For the full copyright and license information, please view
 * the LICENSE.md file that are distributed with this source code.
 *
 * @copyright   Copyright (c) 2016 Tom Flidr (https://github.com/mvccore)
 * @license  https://mvccore.github.io/docs/mvccore/5.0.0/LICENCE.md
 */

namespace MvcCore;

/**
 * Responsibility - completing all information for response - headers (cookies) and content.
 * - HTTP response wrapper carrying response headers and response body.
 * - PHP `setcookie` function wrapper to complete default values such domain or http only etc.
 * - Sending response at application terminate process by `\MvcCore\IResponse::Send();`.
 * - Completing MvcCore performance header at response end.
 */
interface IResponse extends \MvcCore\Response\IConstants {

    /**
     * No singleton, get every time new instance of configured HTTP response
     * class in `\MvcCore\Application::GetInstance()->GetResponseClass();`.
     * @param int|NULL  $code
     * @param array     $headers
     * @param string    $body
     * @return \MvcCore\Response
     */
    public static function CreateInstance (
        $code = NULL,
        $headers = [],
        $body = ''
    );


    /**
     * Get response protocol HTTP version by `$_SERVER['SERVER_PROTOCOL']`,
     * `HTTP/1.1` by default.
     * @return string
     */
    public function GetHttpVersion ();

    /**
     * Set response protocol HTTP version - `HTTP/1.1 | HTTP/2.0`...
     * @param string $httpVersion
     * @return \MvcCore\Response
     */
    public function SetHttpVersion ($httpVersion);

    /**
     * Set HTTP response code.
     * @param int $code
     * @param string|NULL $codeMessage
     * @return \MvcCore\Response
     */
    public function SetCode ($code, $codeMessage = NULL);

    /**
     * Get HTTP response code.
     * @return int `200 | 301 | 404`
     */
    public function GetCode ();

    /**
     * Set multiple HTTP response headers as `key => value` array.
     * All given headers are automatically merged with previously setted headers.
     * If you change second argument to true, all previous request object and PHP
     * headers are removed and given headers will be only headers for output.
     * There is automatically set response encoding from value for
     * `Content-Type` header, if contains any `charset=...`.
     * There is automatically set response encoding from value for
     * `Content-Encoding` header.
     * Example: `$request->SetHeader(array('Content-Type' => 'text/plain; charset=utf-8'));`
     * @param array $headers
     * @param bool $cleanAllPrevious `FALSE` by default. If `TRUE`, all previous headers
     *                               set by PHP `header()` or by this object will be removed.
     * @return \MvcCore\Response
     */
    public function SetHeaders (array $headers = []);

    /**
     * Set HTTP response header.
     * There is automatically set response encoding from value for
     * `Content-Type` header, if contains any `charset=...`.
     * There is automatically set response encoding from value for
     * `Content-Encoding` header.
     * Example: `$request->SetHeader('Content-Type', 'text/plain; charset=utf-8');`
     * @param string $name
     * @param string $value
     * @return \MvcCore\Response
     */
    public function SetHeader ($name, $value);

    /**
     * Get HTTP response header by name. If header doesn't exists, null is returned.
     * Example: `$response->GetHeader('Content-Type'); // returns 'text/plain; charset=utf-8'`
     * @param string $name
     * @return string|NULL
     */
    public function GetHeader ($name);

    /**
     * Get if response has any HTTP response header by given `$name`.
     * Example:
     *  `$request->GetHeader('Content-Type'); // returns TRUE if there is header 'Content-Type'
     *  `$request->GetHeader('content-type'); // returns FALSE if there is header 'Content-Type'
     * @param string $name
     * @return bool
     */
    public function HasHeader ($name);

    /**
     * Set HTTP response content encoding.
     * Example: `$response->SetEncoding('utf-8');`
     * @param string $encoding
     * @return \MvcCore\Response
     */
    public function SetEncoding ($encoding = 'utf-8');

    /**
     * Get HTTP response content encoding.
     * Example: `$response->GetEncoding(); // returns 'utf-8'`
     * @return string|NULL
     */
    public function GetEncoding ();

    /**
     * Set HTTP response body.
     * @param string $body
     * @return \MvcCore\Response
     */
    public function SetBody ($body);

    /**
     * Prepend HTTP response body.
     * @param string $body
     * @return \MvcCore\Response
     */
    public function PrependBody ($body);

    /**
     * Append HTTP response body.
     * @param string $body
     * @return \MvcCore\Response
     */
    public function AppendBody ($body);

    /**
     * Get HTTP response body.
     * @return string|NULL
     */
    public function & GetBody ();

    /**
     * Consolidate all headers from PHP response
     * by calling `headers_list()` into local headers list.
     * @return \MvcCore\Response
     */
    public function UpdateHeaders ();

    /**
     * Return if response has any redirect `"Location: ..."` header inside.
     * @return bool
     */
    public function IsRedirect ();

    /**
     * Returns if response has any `text/html` or `application/xhtml+xml`
     * substring in `Content-Type` header.
     * @return bool
     */
    public function IsHtmlOutput ();

    /**
     * Returns if response has any `xml` substring in `Content-Type` header.
     * @return bool
     */
    public function IsXmlOutput ();

    /**
     * `TRUE` if headers and body has been sent.
     * @return bool
     */
    public function IsSent ();

    /**
     * `TRUE` if headers has been sent.
     * @return bool
     */
    public function IsSentHeaders ();

    /**
     * `TRUE` if body has been sent.
     * @return bool
     */
    public function IsSentBody ();

    /**
     * Send all HTTP headers and send response body.
     * @return \MvcCore\Response
     */
    public function Send ();

    /**
     * Send all HTTP headers.
     * @return \MvcCore\Response
     */
    public function SendHeaders ();

    /**
     * Send response body.
     * @return \MvcCore\Response
     */
    public function SendBody ();

    /**
     * Send a cookie.
     * @param string $name      Cookie name. Assuming the name is `cookiename`, this value is retrieved through `$_COOKIE['cookiename']`.
     * @param string $value    The value of the cookie. This value is stored on the clients computer; do not store sensitive information.
     * @param int   $lifetime   Life time in seconds to expire. 0 means "until the browser is closed".
     * @param string $path      The path on the server in which the cookie will be available on. If set to '/', the cookie will be available within the entire domain.
     * @param string $domain      If not set, value is completed by `\MvcCore\Application::GetInstance()->GetRequest()->GetHostName();` .
     * @param bool   $secure      If not set, value is completed by `\MvcCore\Application::GetInstance()->GetRequest()->IsSecure();`.
     * @param bool   $httpOnly  HTTP only cookie, `TRUE` by default.
     * @throws \RuntimeException  If HTTP headers have been sent.
     * @return bool            True if cookie has been set.
     */
    public function SetCookie (
        $name, $value,
        $lifetime = 0, $path = '/',
        $domain = NULL, $secure = NULL, $httpOnly = TRUE
    );

    /**
     * Delete cookie - set value to empty string and set expiration to past time.
     * @param string $name      Cookie name. Assuming the name is `cookiename`, this value is retrieved through `$_COOKIE['cookiename']`.
     * @param string $path      The path on the server in which the cookie will be available on. If set to '/', the cookie will be available within the entire domain.
     * @param string $domain      If not set, value is completed by `\MvcCore\Application::GetInstance()->GetRequest()->GetHostName();` .
     * @param bool   $secure      If not set, value is completed by `\MvcCore\Application::GetInstance()->GetRequest()->IsSecure();`.
     * @throws \RuntimeException  If HTTP headers have been sent.
     * @return bool            True if cookie has been set.
     */
    public function DeleteCookie ($name, $path = '/', $domain = NULL, $secure = NULL);

    /**
     * Set disabled headers, never sent except if there is
     * rendered exception in development environment.
     * @param \string[] $disabledHeaders,...
     * @return \MvcCore\Response
     */
    public function SetDisabledHeaders ($disabledHeaders);

    /**
     * Get disabled headers, never sent except if there is
     * rendered exception in development environment.
     * @return \string[]
     */
    public function GetDisabledHeaders ();
}