]> git.mxchange.org Git - friendica.git/blob - src/Network/IHTTPRequest.php
Fix Notice: "Undefined variable: r"
[friendica.git] / src / Network / IHTTPRequest.php
1 <?php
2 /**
3  * @copyright Copyright (C) 2020, Friendica
4  *
5  * @license GNU APGL version 3 or any later version
6  *
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.
11  *
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.
16  *
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/>.
19  *
20  */
21
22 namespace Friendica\Network;
23
24 /**
25  * Interface for calling HTTP requests and returning their responses
26  */
27 interface IHTTPRequest
28 {
29         /**
30          * Fetches the content of an URL
31          *
32          * If binary flag is true, return binary results.
33          * Set the cookiejar argument to a string (e.g. "/tmp/friendica-cookies.txt")
34          * to preserve cookies from one request to the next.
35          *
36          * @param string $url             URL to fetch
37          * @param bool   $binary          default false
38          *                                TRUE if asked to return binary results (file download)
39          * @param int    $timeout         Timeout in seconds, default system config value or 60 seconds
40          * @param string $accept_content  supply Accept: header with 'accept_content' as the value
41          * @param string $cookiejar       Path to cookie jar file
42          *
43          * @return string The fetched content
44          */
45         public function fetch(string $url, bool $binary = false, int $timeout = 0, string $accept_content = '', string $cookiejar = '');
46
47         /**
48          * Fetches the whole response of an URL.
49          *
50          * Inner workings and parameters are the same as @ref fetchUrl but returns an array with
51          * all the information collected during the fetch.
52          *
53          * @param string $url             URL to fetch
54          * @param bool   $binary          default false
55          *                                TRUE if asked to return binary results (file download)
56          * @param int    $timeout         Timeout in seconds, default system config value or 60 seconds
57          * @param string $accept_content  supply Accept: header with 'accept_content' as the value
58          * @param string $cookiejar       Path to cookie jar file
59          *
60          * @return CurlResult With all relevant information, 'body' contains the actual fetched content.
61          */
62         public function fetchFull(string $url, bool $binary = false, int $timeout = 0, string $accept_content = '', string $cookiejar = '');
63
64         /**
65          * Send a GET to an URL.
66          *
67          * @param string $url        URL to fetch
68          * @param bool   $binary     default false
69          *                           TRUE if asked to return binary results (file download)
70          * @param array  $opts       (optional parameters) assoziative array with:
71          *                           'accept_content' => supply Accept: header with 'accept_content' as the value
72          *                           'timeout' => int Timeout in seconds, default system config value or 60 seconds
73          *                           'http_auth' => username:password
74          *                           'novalidate' => do not validate SSL certs, default is to validate using our CA list
75          *                           'nobody' => only return the header
76          *                           'cookiejar' => path to cookie jar file
77          *                           'header' => header array
78          *
79          * @return CurlResult
80          */
81         public function get(string $url, bool $binary = false, array $opts = []);
82
83         /**
84          * Send POST request to an URL
85          *
86          * @param string $url     URL to post
87          * @param mixed  $params  array of POST variables
88          * @param array  $headers HTTP headers
89          * @param int    $timeout The timeout in seconds, default system config value or 60 seconds
90          *
91          * @return CurlResult The content
92          */
93         public function post(string $url, $params, array $headers = [], int $timeout = 0);
94
95         /**
96          * Returns the original URL of the provided URL
97          *
98          * This function strips tracking query params and follows redirections, either
99          * through HTTP code or meta refresh tags. Stops after 10 redirections.
100          *
101          * @param string $url       A user-submitted URL
102          * @param int    $depth     The current redirection recursion level (internal)
103          * @param bool   $fetchbody Wether to fetch the body or not after the HEAD requests
104          *
105          * @return string A canonical URL
106          * @throws \Friendica\Network\HTTPException\InternalServerErrorException
107          * @see   ParseUrl::getSiteinfo
108          *
109          * @todo  Remove the $fetchbody parameter that generates an extraneous HEAD request
110          */
111         public function finalUrl(string $url, int $depth = 1, bool $fetchbody = false);
112
113         /**
114          * Returns the current UserAgent as a String
115          *
116          * @return string the UserAgent as a String
117          */
118         public function getUserAgent();
119 }