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          * Set the cookiejar argument to a string (e.g. "/tmp/friendica-cookies.txt")
  33          * to preserve cookies from one request to the next.
  34          *
  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
  39          *
  40          * @return string The fetched content
  41          */
  42         public function fetch(string $url, int $timeout = 0, string $accept_content = '', string $cookiejar = '');
  43
  44         /**
  45          * Fetches the whole response of an URL.
  46          *
  47          * Inner workings and parameters are the same as @ref fetchUrl but returns an array with
  48          * all the information collected during the fetch.
  49          *
  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
  54          *
  55          * @return CurlResult With all relevant information, 'body' contains the actual fetched content.
  56          */
  57         public function fetchFull(string $url, int $timeout = 0, string $accept_content = '', string $cookiejar = '');
  58
  59         /**
  60          * Send a HEAD to an URL.
  61          *
  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
  69          *
  70          * @return CurlResult
  71          */
  72         public function head(string $url, array $opts = []);
  73
  74         /**
  75          * Send a GET to an URL.
  76          *
  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
  84          *
  85          * @return CurlResult
  86          */
  87         public function get(string $url, array $opts = []);
  88
  89         /**
  90          * Send POST request to an URL
  91          *
  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
  96          *
  97          * @return CurlResult The content
  98          */
  99         public function post(string $url, $params, array $headers = [], int $timeout = 0);
 100
 101         /**
 102          * Returns the original URL of the provided URL
 103          *
 104          * This function strips tracking query params and follows redirections, either
 105          * through HTTP code or meta refresh tags. Stops after 10 redirections.
 106          *
 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
 110          *
 111          * @return string A canonical URL
 112          * @throws \Friendica\Network\HTTPException\InternalServerErrorException
 113          * @see   ParseUrl::getSiteinfo
 114          *
 115          * @todo  Remove the $fetchbody parameter that generates an extraneous HEAD request
 116          */
 117         public function finalUrl(string $url, int $depth = 1, bool $fetchbody = false);
 118
 119         /**
 120          * Returns the current UserAgent as a String
 121          *
 122          * @return string the UserAgent as a String
 123          */
 124         public function getUserAgent();
 125 }