src/Network/HTTPClient/Capability/ICanSendHttpRequests.php

   1 <?php
   2 /**
   3  * @copyright Copyright (C) 2010-2023, the Friendica project
   4  *
   5  * @license GNU AGPL 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\HTTPClient\Capability;
  23
  24 use Friendica\Network\HTTPClient\Client\HttpClientAccept;
  25 use GuzzleHttp\Exception\TransferException;
  26
  27 /**
  28  * Interface for calling HTTP requests and returning their responses
  29  */
  30 interface ICanSendHttpRequests
  31 {
  32         /**
  33          * Fetches the content of an URL
  34          *
  35          * Set the cookiejar argument to a string (e.g. "/tmp/friendica-cookies.txt")
  36          * to preserve cookies from one request to the next.
  37          *
  38          * @param string $url             URL to fetch
  39          * @param string $accept_content  supply Accept: header with 'accept_content' as the value
  40          * @param int    $timeout         Timeout in seconds, default system config value or 60 seconds
  41          * @param string $cookiejar       Path to cookie jar file
  42          *
  43          * @return string The fetched content
  44          */
  45         public function fetch(string $url, string $accept_content = HttpClientAccept::DEFAULT, int $timeout = 0, string $cookiejar = ''): string;
  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 string $accept_content  supply Accept: header with 'accept_content' as the value
  55          * @param int    $timeout         Timeout in seconds, default system config value or 60 seconds
  56          * @param string $cookiejar       Path to cookie jar file
  57          *
  58          * @return ICanHandleHttpResponses With all relevant information, 'body' contains the actual fetched content.
  59          */
  60         public function fetchFull(string $url, string $accept_content = HttpClientAccept::DEFAULT, int $timeout = 0, string $cookiejar = ''): ICanHandleHttpResponses;
  61
  62         /**
  63          * Send a GET to a URL.
  64          *
  65          * @param string $url            URL to get
  66          * @param string $accept_content supply Accept: header with 'accept_content' as the value
  67          * @param array  $opts           (optional parameters) associative array with:
  68          *                                'accept_content' => (string array) supply Accept: header with 'accept_content' as the value (overrides default parameter)
  69          *                                'timeout' => int Timeout in seconds, default system config value or 60 seconds
  70          *                                'cookiejar' => path to cookie jar file
  71          *                                'header' => header array
  72          *
  73          * @return ICanHandleHttpResponses
  74          */
  75         public function get(string $url, string $accept_content = HttpClientAccept::DEFAULT, array $opts = []): ICanHandleHttpResponses;
  76
  77         /**
  78          * Send a HEAD to a URL.
  79          *
  80          * @param string $url            URL to fetch
  81          * @param array  $opts           (optional parameters) associative array with:
  82          *                                'accept_content' => (string array) supply Accept: header with 'accept_content' as the value
  83          *                                'timeout' => int Timeout in seconds, default system config value or 60 seconds
  84          *                                'cookiejar' => path to cookie jar file
  85          *                                'header' => header array
  86          *
  87          * @return ICanHandleHttpResponses
  88          */
  89         public function head(string $url, array $opts = []): ICanHandleHttpResponses;
  90
  91         /**
  92          * Send POST request to an URL
  93          *
  94          * @param string $url            URL to post
  95          * @param mixed  $params         POST variables (if an array is passed, it will automatically set as formular parameters)
  96          * @param array  $headers        HTTP headers
  97          * @param int    $timeout        The timeout in seconds, default system config value or 60 seconds
  98          *
  99          * @return ICanHandleHttpResponses The content
 100          */
 101         public function post(string $url, $params, array $headers = [], int $timeout = 0): ICanHandleHttpResponses;
 102
 103         /**
 104          * Sends an HTTP request to a given url
 105          *
 106          * @param string $method         A HTTP request
 107          * @param string $url            Url to send to
 108          * @param array  $opts           (optional parameters) associative array with:
 109          *                                    'body' => (mixed) setting the body for sending data
 110          *                                    'form_params' => (array) Associative array of form field names to values
 111          *                                'accept_content' => (string array) supply Accept: header with 'accept_content' as the value
 112          *                                'timeout' => int Timeout in seconds, default system config value or 60 seconds
 113          *                                'cookiejar' => path to cookie jar file
 114          *                                'header' => header array
 115          *                                'content_length' => int maximum File content length
 116          *                                'auth' => array authentication settings
 117          *
 118          * @return ICanHandleHttpResponses
 119          */
 120         public function request(string $method, string $url, array $opts = []): ICanHandleHttpResponses;
 121
 122         /**
 123          * Returns the original URL of the provided URL
 124          *
 125          * This function strips tracking query params and follows redirections, either
 126          * through HTTP code or meta refresh tags. Stops after 10 redirections.
 127          *
 128          * @param string $url       A user-submitted URL
 129          *
 130          * @return string A canonical URL
 131          *
 132          * @throws TransferException In case there's an error during the resolving
 133          */
 134         public function finalUrl(string $url): string;
 135 }