[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Virtual HTTP service client
   4   *
   5   * This program is free software; you can redistribute it and/or modify
   6   * it under the terms of the GNU General Public License as published by
   7   * the Free Software Foundation; either version 2 of the License, or
   8   * (at your option) any later version.
   9   *
  10   * This program is distributed in the hope that it will be useful,
  11   * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13   * GNU General Public License for more details.
  14   *
  15   * You should have received a copy of the GNU General Public License along
  16   * with this program; if not, write to the Free Software Foundation, Inc.,
  17   * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18   * http://www.gnu.org/copyleft/gpl.html
  19   *
  20   * @file
  21   */
  22  
  23  /**
  24   * Virtual HTTP service instance that can be mounted on to a VirtualRESTService
  25   *
  26   * Sub-classes manage the logic of either:
  27   *   - a) Munging virtual HTTP request arrays to have qualified URLs and auth headers
  28   *   - b) Emulating the execution of virtual HTTP requests (e.g. brokering)
  29   *
  30   * Authentication information can be cached in instances of the class for performance.
  31   * Such information should also be cached locally on the server and auth requests should
  32   * have reasonable timeouts.
  33   *
  34   * @since 1.23
  35   */
  36  abstract class VirtualRESTService {
  37      /** @var array Key/value map */
  38      protected $params = array();
  39  
  40      /**
  41       * @param array $params Key/value map
  42       */
  43  	public function __construct( array $params ) {
  44          $this->params = $params;
  45      }
  46  
  47      /**
  48       * Prepare virtual HTTP(S) requests (for this service) for execution
  49       *
  50       * This method should mangle any of the $reqs entry fields as needed:
  51       *   - url      : munge the URL to have an absolute URL with a protocol
  52       *                and encode path components as needed by the backend [required]
  53       *   - query    : include any authentication signatures/parameters [as needed]
  54       *   - headers  : include any authentication tokens/headers [as needed]
  55       *
  56       * The incoming URL parameter will be relative to the service mount point.
  57       *
  58       * This method can also remove some of the requests as well as add new ones
  59       * (using $idGenerator to set each of the entries' array keys). For any existing
  60       * or added request, the 'response' array can be filled in, which will prevent the
  61       * client from executing it. If an original request is removed, at some point it
  62       * must be added back (with the same key) in onRequests() or onResponses();
  63       * it's reponse may be filled in as with other requests.
  64       *
  65       * @param array $reqs Map of Virtual HTTP request arrays
  66       * @param Closure $idGeneratorFunc Method to generate unique keys for new requests
  67       * @return array Modified HTTP request array map
  68       */
  69  	public function onRequests( array $reqs, Closure $idGeneratorFunc ) {
  70          $result = array();
  71          foreach ( $reqs as $key => $req ) {
  72              // The default encoding treats the URL as a REST style path that uses
  73              // forward slash as a hierarchical delimiter (and never otherwise).
  74              // Subclasses can override this, and should be documented in any case.
  75              $parts = array_map( 'rawurlencode', explode( '/', $req['url'] ) );
  76              $req['url'] = $this->params['baseUrl'] . '/' . implode( '/', $parts );
  77              $result[$key] = $req;
  78          }
  79          return $result;
  80      }
  81  
  82      /**
  83       * Mangle or replace virtual HTTP(S) requests which have been responded to
  84       *
  85       * This method may mangle any of the $reqs entry 'response' fields as needed:
  86       *   - code    : perform any code normalization [as needed]
  87        *   - reason  : perform any reason normalization [as needed]
  88        *   - headers : perform any header normalization [as needed]
  89       *
  90       * This method can also remove some of the requests as well as add new ones
  91       * (using $idGenerator to set each of the entries' array keys). For any existing
  92       * or added request, the 'response' array can be filled in, which will prevent the
  93       * client from executing it. If an original request is removed, at some point it
  94       * must be added back (with the same key) in onRequests() or onResponses();
  95       * it's reponse may be filled in as with other requests. All requests added to $reqs
  96       * will be passed through onRequests() to handle any munging required as normal.
  97       *
  98       * The incoming URL parameter will be relative to the service mount point.
  99       *
 100       * @param array $reqs Map of Virtual HTTP request arrays with 'response' set
 101       * @param Closure $idGeneratorFunc Method to generate unique keys for new requests
 102       * @return array Modified HTTP request array map
 103       */
 104  	public function onResponses( array $reqs, Closure $idGeneratorFunc ) {
 105          return $reqs;
 106      }
 107  }