nextcloud / server

lib/public/IRequest.php

Indentation +259 added lines, -259 removed lines

@@ -62,263 +62,263 @@
  * @since 6.0.0
  */
 interface IRequest {
-	/**
-	 * @since 9.1.0
-	 */
-	public const USER_AGENT_CLIENT_ANDROID = '/^Mozilla\/5\.0 \(Android\) (ownCloud|Nextcloud)\-android.*$/';
-
-	/**
-	 * @since 13.0.0
-	 */
-	public const USER_AGENT_TALK_ANDROID = '/^Mozilla\/5\.0 \(Android\) Nextcloud\-Talk v.*$/';
-
-	/**
-	 * @since 9.1.0
-	 */
-	public const USER_AGENT_CLIENT_DESKTOP = '/^Mozilla\/5\.0 \([A-Za-z ]+\) (mirall|csyncoC)\/.*$/';
-
-	/**
-	 * @since 26.0.0
-	 */
-	public const USER_AGENT_TALK_DESKTOP = '/^Mozilla\/5\.0 \((?!Android|iOS)[A-Za-z ]+\) Nextcloud\-Talk v.*$/';
-
-	/**
-	 * @since 9.1.0
-	 */
-	public const USER_AGENT_CLIENT_IOS = '/^Mozilla\/5\.0 \(iOS\) (ownCloud|Nextcloud)\-iOS.*$/';
-
-	/**
-	 * @since 13.0.0
-	 */
-	public const USER_AGENT_TALK_IOS = '/^Mozilla\/5\.0 \(iOS\) Nextcloud\-Talk v.*$/';
-
-	/**
-	 * @since 13.0.1
-	 */
-	public const USER_AGENT_OUTLOOK_ADDON = '/^Mozilla\/5\.0 \([A-Za-z ]+\) Nextcloud\-Outlook v.*$/';
-
-	/**
-	 * @since 13.0.1
-	 */
-	public const USER_AGENT_THUNDERBIRD_ADDON = '/^Mozilla\/5\.0 \([A-Za-z ]+\) Nextcloud\-Thunderbird v.*$/';
-
-	/**
-	 * @since 26.0.0
-	 */
-	public const JSON_CONTENT_TYPE_REGEX = '/^application\/(?:[a-z0-9.-]+\+)?json\b/';
-
-	/**
-	 * @param string $name
-	 *
-	 * @psalm-taint-source input
-	 *
-	 * @return string
-	 * @since 6.0.0
-	 */
-	public function getHeader(string $name): string;
-
-	/**
-	 * Lets you access post and get parameters by the index
-	 * In case of json requests the encoded json body is accessed
-	 *
-	 * @psalm-taint-source input
-	 *
-	 * @param string $key the key which you want to access in the URL Parameter
-	 *                     placeholder, $_POST or $_GET array.
-	 *                     The priority how they're returned is the following:
-	 *                     1. URL parameters
-	 *                     2. POST parameters
-	 *                     3. GET parameters
-	 * @param mixed $default If the key is not found, this value will be returned
-	 * @return mixed the content of the array
-	 * @since 6.0.0
-	 */
-	public function getParam(string $key, $default = null);
-
-
-	/**
-	 * Returns all params that were received, be it from the request
-	 *
-	 * (as GET or POST) or through the URL by the route
-	 *
-	 * @psalm-taint-source input
-	 *
-	 * @return array the array with all parameters
-	 * @since 6.0.0
-	 */
-	public function getParams(): array;
-
-	/**
-	 * Returns the method of the request
-	 *
-	 * @return string the method of the request (POST, GET, etc)
-	 * @since 6.0.0
-	 */
-	public function getMethod(): string;
-
-	/**
-	 * Shortcut for accessing an uploaded file through the $_FILES array
-	 *
-	 * @param string $key the key that will be taken from the $_FILES array
-	 * @return array the file in the $_FILES element
-	 * @since 6.0.0
-	 */
-	public function getUploadedFile(string $key);
-
-
-	/**
-	 * Shortcut for getting env variables
-	 *
-	 * @param string $key the key that will be taken from the $_ENV array
-	 * @return array the value in the $_ENV element
-	 * @since 6.0.0
-	 */
-	public function getEnv(string $key);
-
-
-	/**
-	 * Shortcut for getting cookie variables
-	 *
-	 * @psalm-taint-source input
-	 *
-	 * @param string $key the key that will be taken from the $_COOKIE array
-	 * @return string|null the value in the $_COOKIE element
-	 * @since 6.0.0
-	 */
-	public function getCookie(string $key);
-
-
-	/**
-	 * Checks if the CSRF check was correct
-	 *
-	 * @return bool true if CSRF check passed
-	 * @since 6.0.0
-	 */
-	public function passesCSRFCheck(): bool;
-
-	/**
-	 * Checks if the strict cookie has been sent with the request if the request
-	 * is including any cookies.
-	 *
-	 * @return bool
-	 * @since 9.0.0
-	 */
-	public function passesStrictCookieCheck(): bool;
-
-	/**
-	 * Checks if the lax cookie has been sent with the request if the request
-	 * is including any cookies.
-	 *
-	 * @return bool
-	 * @since 9.0.0
-	 */
-	public function passesLaxCookieCheck(): bool;
-
-	/**
-	 * Returns an ID for the request, value is not guaranteed to be unique and is mostly meant for logging
-	 * If `mod_unique_id` is installed this value will be taken.
-	 *
-	 * @return string
-	 * @since 8.1.0
-	 */
-	public function getId(): string;
-
-	/**
-	 * Returns the remote address, if the connection came from a trusted proxy
-	 * and `forwarded_for_headers` has been configured then the IP address
-	 * specified in this header will be returned instead.
-	 * Do always use this instead of $_SERVER['REMOTE_ADDR']
-	 *
-	 * @return string IP address
-	 * @since 8.1.0
-	 */
-	public function getRemoteAddress(): string;
-
-	/**
-	 * Returns the server protocol. It respects reverse proxy servers and load
-	 * balancers.
-	 *
-	 * @return string Server protocol (http or https)
-	 * @since 8.1.0
-	 */
-	public function getServerProtocol(): string;
-
-	/**
-	 * Returns the used HTTP protocol.
-	 *
-	 * @return string HTTP protocol. HTTP/2, HTTP/1.1 or HTTP/1.0.
-	 * @since 8.2.0
-	 */
-	public function getHttpProtocol(): string;
-
-	/**
-	 * Returns the request uri, even if the website uses one or more
-	 * reverse proxies
-	 *
-	 * @psalm-taint-source input
-	 *
-	 * @return string
-	 * @since 8.1.0
-	 */
-	public function getRequestUri(): string;
-
-	/**
-	 * Get raw PathInfo from request (not urldecoded)
-	 *
-	 * @psalm-taint-source input
-	 *
-	 * @throws \Exception
-	 * @return string Path info
-	 * @since 8.1.0
-	 */
-	public function getRawPathInfo(): string;
-
-	/**
-	 * Get PathInfo from request
-	 *
-	 * @psalm-taint-source input
-	 *
-	 * @throws \Exception
-	 * @return string|false Path info or false when not found
-	 * @since 8.1.0
-	 */
-	public function getPathInfo();
-
-	/**
-	 * Returns the script name, even if the website uses one or more
-	 * reverse proxies
-	 *
-	 * @return string the script name
-	 * @since 8.1.0
-	 */
-	public function getScriptName(): string;
-
-	/**
-	 * Checks whether the user agent matches a given regex
-	 *
-	 * @param array $agent array of agent names
-	 * @return bool true if at least one of the given agent matches, false otherwise
-	 * @since 8.1.0
-	 */
-	public function isUserAgent(array $agent): bool;
-
-	/**
-	 * Returns the unverified server host from the headers without checking
-	 * whether it is a trusted domain
-	 *
-	 * @psalm-taint-source input
-	 *
-	 * @return string Server host
-	 * @since 8.1.0
-	 */
-	public function getInsecureServerHost(): string;
-
-	/**
-	 * Returns the server host from the headers, or the first configured
-	 * trusted domain if the host isn't in the trusted list
-	 *
-	 * @return string Server host
-	 * @since 8.1.0
-	 */
-	public function getServerHost(): string;
+    /**
+     * @since 9.1.0
+     */
+    public const USER_AGENT_CLIENT_ANDROID = '/^Mozilla\/5\.0 \(Android\) (ownCloud|Nextcloud)\-android.*$/';
+
+    /**
+     * @since 13.0.0
+     */
+    public const USER_AGENT_TALK_ANDROID = '/^Mozilla\/5\.0 \(Android\) Nextcloud\-Talk v.*$/';
+
+    /**
+     * @since 9.1.0
+     */
+    public const USER_AGENT_CLIENT_DESKTOP = '/^Mozilla\/5\.0 \([A-Za-z ]+\) (mirall|csyncoC)\/.*$/';
+
+    /**
+     * @since 26.0.0
+     */
+    public const USER_AGENT_TALK_DESKTOP = '/^Mozilla\/5\.0 \((?!Android|iOS)[A-Za-z ]+\) Nextcloud\-Talk v.*$/';
+
+    /**
+     * @since 9.1.0
+     */
+    public const USER_AGENT_CLIENT_IOS = '/^Mozilla\/5\.0 \(iOS\) (ownCloud|Nextcloud)\-iOS.*$/';
+
+    /**
+     * @since 13.0.0
+     */
+    public const USER_AGENT_TALK_IOS = '/^Mozilla\/5\.0 \(iOS\) Nextcloud\-Talk v.*$/';
+
+    /**
+     * @since 13.0.1
+     */
+    public const USER_AGENT_OUTLOOK_ADDON = '/^Mozilla\/5\.0 \([A-Za-z ]+\) Nextcloud\-Outlook v.*$/';
+
+    /**
+     * @since 13.0.1
+     */
+    public const USER_AGENT_THUNDERBIRD_ADDON = '/^Mozilla\/5\.0 \([A-Za-z ]+\) Nextcloud\-Thunderbird v.*$/';
+
+    /**
+     * @since 26.0.0
+     */
+    public const JSON_CONTENT_TYPE_REGEX = '/^application\/(?:[a-z0-9.-]+\+)?json\b/';
+
+    /**
+     * @param string $name
+     *
+     * @psalm-taint-source input
+     *
+     * @return string
+     * @since 6.0.0
+     */
+    public function getHeader(string $name): string;
+
+    /**
+     * Lets you access post and get parameters by the index
+     * In case of json requests the encoded json body is accessed
+     *
+     * @psalm-taint-source input
+     *
+     * @param string $key the key which you want to access in the URL Parameter
+     *                     placeholder, $_POST or $_GET array.
+     *                     The priority how they're returned is the following:
+     *                     1. URL parameters
+     *                     2. POST parameters
+     *                     3. GET parameters
+     * @param mixed $default If the key is not found, this value will be returned
+     * @return mixed the content of the array
+     * @since 6.0.0
+     */
+    public function getParam(string $key, $default = null);
+
+
+    /**
+     * Returns all params that were received, be it from the request
+     *
+     * (as GET or POST) or through the URL by the route
+     *
+     * @psalm-taint-source input
+     *
+     * @return array the array with all parameters
+     * @since 6.0.0
+     */
+    public function getParams(): array;
+
+    /**
+     * Returns the method of the request
+     *
+     * @return string the method of the request (POST, GET, etc)
+     * @since 6.0.0
+     */
+    public function getMethod(): string;
+
+    /**
+     * Shortcut for accessing an uploaded file through the $_FILES array
+     *
+     * @param string $key the key that will be taken from the $_FILES array
+     * @return array the file in the $_FILES element
+     * @since 6.0.0
+     */
+    public function getUploadedFile(string $key);
+
+
+    /**
+     * Shortcut for getting env variables
+     *
+     * @param string $key the key that will be taken from the $_ENV array
+     * @return array the value in the $_ENV element
+     * @since 6.0.0
+     */
+    public function getEnv(string $key);
+
+
+    /**
+     * Shortcut for getting cookie variables
+     *
+     * @psalm-taint-source input
+     *
+     * @param string $key the key that will be taken from the $_COOKIE array
+     * @return string|null the value in the $_COOKIE element
+     * @since 6.0.0
+     */
+    public function getCookie(string $key);
+
+
+    /**
+     * Checks if the CSRF check was correct
+     *
+     * @return bool true if CSRF check passed
+     * @since 6.0.0
+     */
+    public function passesCSRFCheck(): bool;
+
+    /**
+     * Checks if the strict cookie has been sent with the request if the request
+     * is including any cookies.
+     *
+     * @return bool
+     * @since 9.0.0
+     */
+    public function passesStrictCookieCheck(): bool;
+
+    /**
+     * Checks if the lax cookie has been sent with the request if the request
+     * is including any cookies.
+     *
+     * @return bool
+     * @since 9.0.0
+     */
+    public function passesLaxCookieCheck(): bool;
+
+    /**
+     * Returns an ID for the request, value is not guaranteed to be unique and is mostly meant for logging
+     * If `mod_unique_id` is installed this value will be taken.
+     *
+     * @return string
+     * @since 8.1.0
+     */
+    public function getId(): string;
+
+    /**
+     * Returns the remote address, if the connection came from a trusted proxy
+     * and `forwarded_for_headers` has been configured then the IP address
+     * specified in this header will be returned instead.
+     * Do always use this instead of $_SERVER['REMOTE_ADDR']
+     *
+     * @return string IP address
+     * @since 8.1.0
+     */
+    public function getRemoteAddress(): string;
+
+    /**
+     * Returns the server protocol. It respects reverse proxy servers and load
+     * balancers.
+     *
+     * @return string Server protocol (http or https)
+     * @since 8.1.0
+     */
+    public function getServerProtocol(): string;
+
+    /**
+     * Returns the used HTTP protocol.
+     *
+     * @return string HTTP protocol. HTTP/2, HTTP/1.1 or HTTP/1.0.
+     * @since 8.2.0
+     */
+    public function getHttpProtocol(): string;
+
+    /**
+     * Returns the request uri, even if the website uses one or more
+     * reverse proxies
+     *
+     * @psalm-taint-source input
+     *
+     * @return string
+     * @since 8.1.0
+     */
+    public function getRequestUri(): string;
+
+    /**
+     * Get raw PathInfo from request (not urldecoded)
+     *
+     * @psalm-taint-source input
+     *
+     * @throws \Exception
+     * @return string Path info
+     * @since 8.1.0
+     */
+    public function getRawPathInfo(): string;
+
+    /**
+     * Get PathInfo from request
+     *
+     * @psalm-taint-source input
+     *
+     * @throws \Exception
+     * @return string|false Path info or false when not found
+     * @since 8.1.0
+     */
+    public function getPathInfo();
+
+    /**
+     * Returns the script name, even if the website uses one or more
+     * reverse proxies
+     *
+     * @return string the script name
+     * @since 8.1.0
+     */
+    public function getScriptName(): string;
+
+    /**
+     * Checks whether the user agent matches a given regex
+     *
+     * @param array $agent array of agent names
+     * @return bool true if at least one of the given agent matches, false otherwise
+     * @since 8.1.0
+     */
+    public function isUserAgent(array $agent): bool;
+
+    /**
+     * Returns the unverified server host from the headers without checking
+     * whether it is a trusted domain
+     *
+     * @psalm-taint-source input
+     *
+     * @return string Server host
+     * @since 8.1.0
+     */
+    public function getInsecureServerHost(): string;
+
+    /**
+     * Returns the server host from the headers, or the first configured
+     * trusted domain if the host isn't in the trusted list
+     *
+     * @return string Server host
+     * @since 8.1.0
+     */
+    public function getServerHost(): string;
 }