3 * @copyright Copyright (C) 2010-2021, the Friendica project
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;
24 use GuzzleHttp\Exception\TransferException;
27 * Interface for calling HTTP requests and returning their responses
32 * Fetches the content of an URL
34 * Set the cookiejar argument to a string (e.g. "/tmp/friendica-cookies.txt")
35 * to preserve cookies from one request to the next.
37 * @param string $url URL to fetch
38 * @param int $timeout Timeout in seconds, default system config value or 60 seconds
39 * @param string $accept_content supply Accept: header with 'accept_content' as the value
40 * @param string $cookiejar Path to cookie jar file
42 * @return string The fetched content
44 public function fetch(string $url, int $timeout = 0, string $accept_content = '', string $cookiejar = '');
47 * Fetches the whole response of an URL.
49 * Inner workings and parameters are the same as @ref fetchUrl but returns an array with
50 * all the information collected during the fetch.
52 * @param string $url URL to fetch
53 * @param int $timeout Timeout in seconds, default system config value or 60 seconds
54 * @param string $accept_content supply Accept: header with 'accept_content' as the value
55 * @param string $cookiejar Path to cookie jar file
57 * @return IHTTPResult With all relevant information, 'body' contains the actual fetched content.
59 public function fetchFull(string $url, int $timeout = 0, string $accept_content = '', string $cookiejar = '');
62 * Send a HEAD to an URL.
64 * @param string $url URL to fetch
65 * @param array $opts (optional parameters) associative array with:
66 * 'accept_content' => (string array) supply Accept: header with 'accept_content' as the value
67 * 'timeout' => int Timeout in seconds, default system config value or 60 seconds
68 * 'cookiejar' => path to cookie jar file
69 * 'header' => header array
73 public function head(string $url, array $opts = []);
76 * Send a GET to an URL.
78 * @param string $url URL to fetch
79 * @param array $opts (optional parameters) associative array with:
80 * 'accept_content' => (string array) supply Accept: header with 'accept_content' as the value
81 * 'timeout' => int Timeout in seconds, default system config value or 60 seconds
82 * 'cookiejar' => path to cookie jar file
83 * 'header' => header array
84 * 'content_length' => int maximum File content length
88 public function get(string $url, array $opts = []);
91 * Sends a HTTP request to a given url
93 * @param string $method A HTTP request
94 * @param string $url Url to send to
95 * @param array $opts (optional parameters) associative array with:
96 * 'body' => (mixed) setting the body for sending data
97 * 'accept_content' => (string array) supply Accept: header with 'accept_content' as the value
98 * 'timeout' => int Timeout in seconds, default system config value or 60 seconds
99 * 'cookiejar' => path to cookie jar file
100 * 'header' => header array
101 * 'content_length' => int maximum File content length
102 * 'auth' => array authentication settings
104 * @return IHTTPResult
106 public function request(string $method, string $url, array $opts = []);
109 * Send POST request to an URL
111 * @param string $url URL to post
112 * @param mixed $params array of POST variables
113 * @param array $headers HTTP headers
114 * @param int $timeout The timeout in seconds, default system config value or 60 seconds
116 * @return IHTTPResult The content
118 public function post(string $url, $params, array $headers = [], int $timeout = 0);
121 * Returns the original URL of the provided URL
123 * This function strips tracking query params and follows redirections, either
124 * through HTTP code or meta refresh tags. Stops after 10 redirections.
126 * @param string $url A user-submitted URL
128 * @return string A canonical URL
130 * @throws TransferException In case there's an error during the resolving
132 public function finalUrl(string $url);