<?php
/**
 * Part of the Joomla Framework Application Package
 *
 * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
 * @license    GNU General Public License version 2 or later; see LICENSE
 */

namespace Joomla\Application;

use Joomla\Input\Input;
use Psr\Http\Message\ResponseInterface;

/**
 * Application sub-interface defining a web application class
 *
 * @since  2.0.0
 */
interface WebApplicationInterface extends ApplicationInterface
{
	/**
	 * Method to get the application input object.
	 *
	 * @return  Input
	 *
	 * @since   2.0.0
	 */
	public function getInput(): Input;

	/**
	 * Redirect to another URL.
	 *
	 * If the headers have not been sent the redirect will be accomplished using a "301 Moved Permanently" or "303 See Other" code in the header
	 * pointing to the new location. If the headers have already been sent this will be accomplished using a JavaScript statement.
	 *
	 * @param   string           $url     The URL to redirect to. Can only be http/https URL
	 * @param   integer|boolean  $status  The HTTP status code to be provided. 303 is assumed by default.
	 *
	 * @return  void
	 *
	 * @since   2.0.0
	 * @throws  \InvalidArgumentException
	 */
	public function redirect($url, $status = 303);

	/**
	 * Set/get cachable state for the response.
	 *
	 * If $allow is set, sets the cachable state of the response.  Always returns the current state.
	 *
	 * @param   boolean  $allow  True to allow browser caching.
	 *
	 * @return  boolean
	 *
	 * @since   2.0.0
	 */
	public function allowCache($allow = null);

	/**
	 * Method to set a response header.
	 *
	 * If the replace flag is set then all headers with the given name will be replaced by the new one.
	 * The headers are stored in an internal array to be sent when the site is sent to the browser.
	 *
	 * @param   string   $name     The name of the header to set.
	 * @param   string   $value    The value of the header to set.
	 * @param   boolean  $replace  True to replace any headers with the same name.
	 *
	 * @return  $this
	 *
	 * @since   2.0.0
	 */
	public function setHeader($name, $value, $replace = false);

	/**
	 * Method to get the array of response headers to be sent when the response is sent to the client.
	 *
	 * @return  array
	 *
	 * @since   2.0.0
	 */
	public function getHeaders();

	/**
	 * Method to clear any set response headers.
	 *
	 * @return  $this
	 *
	 * @since   2.0.0
	 */
	public function clearHeaders();

	/**
	 * Send the response headers.
	 *
	 * @return  $this
	 *
	 * @since   2.0.0
	 */
	public function sendHeaders();

	/**
	 * Set body content.  If body content already defined, this will replace it.
	 *
	 * @param   string  $content  The content to set as the response body.
	 *
	 * @return  $this
	 *
	 * @since   2.0.0
	 */
	public function setBody($content);

	/**
	 * Prepend content to the body content
	 *
	 * @param   string  $content  The content to prepend to the response body.
	 *
	 * @return  $this
	 *
	 * @since   2.0.0
	 */
	public function prependBody($content);

	/**
	 * Append content to the body content
	 *
	 * @param   string  $content  The content to append to the response body.
	 *
	 * @return  $this
	 *
	 * @since   2.0.0
	 */
	public function appendBody($content);

	/**
	 * Return the body content
	 *
	 * @return  mixed  The response body as a string.
	 *
	 * @since   2.0.0
	 */
	public function getBody();

	/**
	 * Get the PSR-7 Response Object.
	 *
	 * @return  ResponseInterface
	 *
	 * @since   2.0.0
	 */
	public function getResponse(): ResponseInterface;

	/**
	 * Check if the value is a valid HTTP status code
	 *
	 * @param   integer  $code  The potential status code
	 *
	 * @return  boolean
	 *
	 * @since   2.0.0
	 */
	public function isValidHttpStatus($code);

	/**
	 * Set the PSR-7 Response Object.
	 *
	 * @param   ResponseInterface  $response  The response object
	 *
	 * @return  void
	 *
	 * @since   2.0.0
	 */
	public function setResponse(ResponseInterface $response): void;

	/**
	 * Determine if we are using a secure (SSL) connection.
	 *
	 * @return  boolean  True if using SSL, false if not.
	 *
	 * @since   2.0.0
	 */
	public function isSslConnection();
}