src/Network/IHTTPClient.php

   1 <?php
   2 /**
   3  * @copyright Copyright (C) 2010-2021, the Friendica project
   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 use GuzzleHttp\Exception\TransferException;
  25
  26 /**
  27  * Interface for calling HTTP requests and returning their responses
  28  */
  29 interface IHTTPClient
  30 {
  31         /**
  32          * Fetches the content of an URL
  33          *
  34          * Set the cookiejar argument to a string (e.g. "/tmp/friendica-cookies.txt")
  35          * to preserve cookies from one request to the next.
  36          *
  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
  41          *
  42          * @return string The fetched content
  43          */
  44         public function fetch(string $url, int $timeout = 0, string $accept_content = '', string $cookiejar = '');
  45
  46         /**
  47          * Fetches the whole response of an URL.
  48          *
  49          * Inner workings and parameters are the same as @ref fetchUrl but returns an array with
  50          * all the information collected during the fetch.
  51          *
  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
  56          *
  57          * @return IHTTPResult With all relevant information, 'body' contains the actual fetched content.
  58          */
  59         public function fetchFull(string $url, int $timeout = 0, string $accept_content = '', string $cookiejar = '');
  60
  61         /**
  62          * Send a HEAD to an URL.
  63          *
  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
  70          *
  71          * @return CurlResult
  72          */
  73         public function head(string $url, array $opts = []);
  74
  75         /**
  76          * Send a GET to an URL.
  77          *
  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
  85          *
  86          * @return IHTTPResult
  87          */
  88         public function get(string $url, array $opts = []);
  89
  90         /**
  91          * Sends a HTTP request to a given url
  92          *
  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
 103          *
 104          * @return IHTTPResult
 105          */
 106         public function request(string $method, string $url, array $opts = []);
 107
 108         /**
 109          * Send POST request to an URL
 110          *
 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
 115          *
 116          * @return IHTTPResult The content
 117          */
 118         public function post(string $url, $params, array $headers = [], int $timeout = 0);
 119
 120         /**
 121          * Returns the original URL of the provided URL
 122          *
 123          * This function strips tracking query params and follows redirections, either
 124          * through HTTP code or meta refresh tags. Stops after 10 redirections.
 125          *
 126          * @param string $url       A user-submitted URL
 127          *
 128          * @return string A canonical URL
 129          *
 130          * @throws TransferException In case there's an error during the resolving
 131          */
 132         public function finalUrl(string $url);
 133 }