3 * @copyright Copyright (C) 2020, Friendica
5 * @license GNU APGL version 3 or any later version
7 * This program is free software: you can redistribute it and/or modify
8 * it under the terms of the GNU Affero General Public License as
9 * published by the Free Software Foundation, either version 3 of the
10 * License, or (at your option) any later version.
12 * This program is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU Affero General Public License for more details.
17 * You should have received a copy of the GNU Affero General Public License
18 * along with this program. If not, see <https://www.gnu.org/licenses/>.
22 namespace Friendica\Network;
25 * Interface for calling HTTP requests and returning their responses
27 interface IHTTPRequest
30 * Fetches the content of an URL
32 * Set the cookiejar argument to a string (e.g. "/tmp/friendica-cookies.txt")
33 * to preserve cookies from one request to the next.
35 * @param string $url URL to fetch
36 * @param int $timeout Timeout in seconds, default system config value or 60 seconds
37 * @param string $accept_content supply Accept: header with 'accept_content' as the value
38 * @param string $cookiejar Path to cookie jar file
40 * @return string The fetched content
42 public function fetch(string $url, int $timeout = 0, string $accept_content = '', string $cookiejar = '');
45 * Fetches the whole response of an URL.
47 * Inner workings and parameters are the same as @ref fetchUrl but returns an array with
48 * all the information collected during the fetch.
50 * @param string $url URL to fetch
51 * @param int $timeout Timeout in seconds, default system config value or 60 seconds
52 * @param string $accept_content supply Accept: header with 'accept_content' as the value
53 * @param string $cookiejar Path to cookie jar file
55 * @return CurlResult With all relevant information, 'body' contains the actual fetched content.
57 public function fetchFull(string $url, int $timeout = 0, string $accept_content = '', string $cookiejar = '');
60 * Send a HEAD to an URL.
62 * @param string $url URL to fetch
63 * @param array $opts (optional parameters) assoziative array with:
64 * 'accept_content' => supply Accept: header with 'accept_content' as the value
65 * 'timeout' => int Timeout in seconds, default system config value or 60 seconds
66 * 'novalidate' => do not validate SSL certs, default is to validate using our CA list
67 * 'cookiejar' => path to cookie jar file
68 * 'header' => header array
72 public function head(string $url, array $opts = []);
75 * Send a GET to an URL.
77 * @param string $url URL to fetch
78 * @param array $opts (optional parameters) assoziative array with:
79 * 'accept_content' => supply Accept: header with 'accept_content' as the value
80 * 'timeout' => int Timeout in seconds, default system config value or 60 seconds
81 * 'novalidate' => do not validate SSL certs, default is to validate using our CA list
82 * 'cookiejar' => path to cookie jar file
83 * 'header' => header array
87 public function get(string $url, array $opts = []);
90 * Send POST request to an URL
92 * @param string $url URL to post
93 * @param mixed $params array of POST variables
94 * @param array $headers HTTP headers
95 * @param int $timeout The timeout in seconds, default system config value or 60 seconds
97 * @return CurlResult The content
99 public function post(string $url, $params, array $headers = [], int $timeout = 0);
102 * Returns the original URL of the provided URL
104 * This function strips tracking query params and follows redirections, either
105 * through HTTP code or meta refresh tags. Stops after 10 redirections.
107 * @param string $url A user-submitted URL
108 * @param int $depth The current redirection recursion level (internal)
109 * @param bool $fetchbody Wether to fetch the body or not after the HEAD requests
111 * @return string A canonical URL
112 * @throws \Friendica\Network\HTTPException\InternalServerErrorException
113 * @see ParseUrl::getSiteinfo
115 * @todo Remove the $fetchbody parameter that generates an extraneous HEAD request
117 public function finalUrl(string $url, int $depth = 1, bool $fetchbody = false);
120 * Returns the current UserAgent as a String
122 * @return string the UserAgent as a String
124 public function getUserAgent();