CAS/CAS/Request/AbstractRequest.php

   1 <?php
   2
   3 /**
   4  * Licensed to Jasig under one or more contributor license
   5  * agreements. See the NOTICE file distributed with this work for
   6  * additional information regarding copyright ownership.
   7  *
   8  * Jasig licenses this file to you under the Apache License,
   9  * Version 2.0 (the "License"); you may not use this file except in
  10  * compliance with the License. You may obtain a copy of the License at:
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  * PHP Version 5
  21  *
  22  * @file     CAS/Request/AbstractRequest.php
  23  * @category Authentication
  24  * @package  PhpCAS
  25  * @author   Adam Franco <afranco@middlebury.edu>
  26  * @license  http://www.apache.org/licenses/LICENSE-2.0  Apache License 2.0
  27  * @link     https://wiki.jasig.org/display/CASC/phpCAS
  28  */
  29
  30 /**
  31  * Provides support for performing web-requests via curl
  32  *
  33  * @class    CAS_Request_AbstractRequest
  34  * @category Authentication
  35  * @package  PhpCAS
  36  * @author   Adam Franco <afranco@middlebury.edu>
  37  * @license  http://www.apache.org/licenses/LICENSE-2.0  Apache License 2.0
  38  * @link     https://wiki.jasig.org/display/CASC/phpCAS
  39  */
  40 abstract class CAS_Request_AbstractRequest
  41 implements CAS_Request_RequestInterface
  42 {
  43
  44     protected $url = null;
  45     protected $cookies = array();
  46     protected $headers = array();
  47     protected $isPost = false;
  48     protected $postBody = null;
  49     protected $caCertPath = null;
  50     protected $validateCN = true;
  51     private $_sent = false;
  52     private $_responseHeaders = array();
  53     private $_responseBody = null;
  54     private $_errorMessage = '';
  55
  56     /*********************************************************
  57      * Configure the Request
  58     *********************************************************/
  59
  60     /**
  61      * Set the URL of the Request
  62      *
  63      * @param string $url Url to set
  64      *
  65      * @return void
  66      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
  67      */
  68     public function setUrl ($url)
  69     {
  70         if ($this->_sent) {
  71             throw new CAS_OutOfSequenceException('Request has already been sent cannot '.__METHOD__);
  72         }
  73
  74         $this->url = $url;
  75     }
  76
  77     /**
  78      * Add a cookie to the request.
  79      *
  80      * @param string $name  Name of entry
  81      * @param string $value value of entry
  82      *
  83      * @return void
  84      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
  85      */
  86     public function addCookie ($name, $value)
  87     {
  88         if ($this->_sent) {
  89             throw new CAS_OutOfSequenceException('Request has already been sent cannot '.__METHOD__);
  90         }
  91
  92         $this->cookies[$name] = $value;
  93     }
  94
  95     /**
  96      * Add an array of cookies to the request.
  97      * The cookie array is of the form
  98      *     array('cookie_name' => 'cookie_value', 'cookie_name2' => cookie_value2')
  99      *
 100      * @param array $cookies cookies to add
 101      *
 102      * @return void
 103      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
 104      */
 105     public function addCookies (array $cookies)
 106     {
 107         if ($this->_sent) {
 108             throw new CAS_OutOfSequenceException('Request has already been sent cannot '.__METHOD__);
 109         }
 110
 111         $this->cookies = array_merge($this->cookies, $cookies);
 112     }
 113
 114     /**
 115      * Add a header string to the request.
 116      *
 117      * @param string $header Header to add
 118      *
 119      * @return void
 120      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
 121      */
 122     public function addHeader ($header)
 123     {
 124         if ($this->_sent) {
 125             throw new CAS_OutOfSequenceException('Request has already been sent cannot '.__METHOD__);
 126         }
 127
 128         $this->headers[] = $header;
 129     }
 130
 131     /**
 132      * Add an array of header strings to the request.
 133      *
 134      * @param array $headers headers to add
 135      *
 136      * @return void
 137      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
 138      */
 139     public function addHeaders (array $headers)
 140     {
 141         if ($this->_sent) {
 142             throw new CAS_OutOfSequenceException('Request has already been sent cannot '.__METHOD__);
 143         }
 144
 145         $this->headers = array_merge($this->headers, $headers);
 146     }
 147
 148     /**
 149      * Make the request a POST request rather than the default GET request.
 150      *
 151      * @return void
 152      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
 153      */
 154     public function makePost ()
 155     {
 156         if ($this->_sent) {
 157             throw new CAS_OutOfSequenceException('Request has already been sent cannot '.__METHOD__);
 158         }
 159
 160         $this->isPost = true;
 161     }
 162
 163     /**
 164      * Add a POST body to the request
 165      *
 166      * @param string $body body to add
 167      *
 168      * @return void
 169      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
 170      */
 171     public function setPostBody ($body)
 172     {
 173         if ($this->_sent) {
 174             throw new CAS_OutOfSequenceException('Request has already been sent cannot '.__METHOD__);
 175         }
 176         if (!$this->isPost) {
 177             throw new CAS_OutOfSequenceException('Cannot add a POST body to a GET request, use makePost() first.');
 178         }
 179
 180         $this->postBody = $body;
 181     }
 182
 183     /**
 184      * Specify the path to an SSL CA certificate to validate the server with.
 185      *
 186      * @param string $caCertPath  path to cert
 187      * @param bool   $validate_cn valdiate CN of certificate
 188      *
 189      * @return void
 190      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
 191      */
 192     public function setSslCaCert ($caCertPath,$validate_cn=true)
 193     {
 194         if ($this->_sent) {
 195             throw new CAS_OutOfSequenceException('Request has already been sent cannot '.__METHOD__);
 196         }
 197         $this->caCertPath = $caCertPath;
 198         $this->validateCN = $validate_cn;
 199     }
 200
 201     /*********************************************************
 202      * 2. Send the Request
 203     *********************************************************/
 204
 205     /**
 206      * Perform the request.
 207      *
 208      * @return bool TRUE on success, FALSE on failure.
 209      * @throws CAS_OutOfSequenceException If called multiple times.
 210      */
 211     public function send ()
 212     {
 213         if ($this->_sent) {
 214             throw new CAS_OutOfSequenceException('Request has already been sent cannot send again.');
 215         }
 216         if (is_null($this->url) || !$this->url) {
 217             throw new CAS_OutOfSequenceException('A url must be specified via setUrl() before the request can be sent.');
 218         }
 219         $this->_sent = true;
 220         return $this->sendRequest();
 221     }
 222
 223     /**
 224      * Send the request and store the results.
 225      *
 226      * @return bool TRUE on success, FALSE on failure.
 227      */
 228     abstract protected function sendRequest ();
 229
 230     /**
 231      * Store the response headers.
 232      *
 233      * @param array $headers headers to store
 234      *
 235      * @return void
 236      */
 237     protected function storeResponseHeaders (array $headers)
 238     {
 239         $this->_responseHeaders = array_merge($this->_responseHeaders, $headers);
 240     }
 241
 242     /**
 243      * Store a single response header to our array.
 244      *
 245      * @param string $header header to store
 246      *
 247      * @return void
 248      */
 249     protected function storeResponseHeader ($header)
 250     {
 251         $this->_responseHeaders[] = $header;
 252     }
 253
 254     /**
 255      * Store the response body.
 256      *
 257      * @param string $body body to store
 258      *
 259      * @return void
 260      */
 261     protected function storeResponseBody ($body)
 262     {
 263         $this->_responseBody = $body;
 264     }
 265
 266     /**
 267      * Add a string to our error message.
 268      *
 269      * @param string $message message to add
 270      *
 271      * @return void
 272      */
 273     protected function storeErrorMessage ($message)
 274     {
 275         $this->_errorMessage .= $message;
 276     }
 277
 278     /*********************************************************
 279      * 3. Access the response
 280     *********************************************************/
 281
 282     /**
 283      * Answer the headers of the response.
 284      *
 285      * @return array An array of header strings.
 286      * @throws CAS_OutOfSequenceException If called before the Request has been sent.
 287      */
 288     public function getResponseHeaders ()
 289     {
 290         if (!$this->_sent) {
 291             throw new CAS_OutOfSequenceException('Request has not been sent yet. Cannot '.__METHOD__);
 292         }
 293         return $this->_responseHeaders;
 294     }
 295
 296     /**
 297      * Answer HTTP status code of the response
 298      *
 299      * @return int
 300      * @throws CAS_OutOfSequenceException If called before the Request has been sent.
 301      */
 302     public function getResponseStatusCode ()
 303     {
 304         if (!$this->_sent) {
 305             throw new CAS_OutOfSequenceException('Request has not been sent yet. Cannot '.__METHOD__);
 306         }
 307
 308         if (!preg_match('/HTTP\/[0-9.]+\s+([0-9]+)\s*(.*)/', $this->_responseHeaders[0], $matches)) {
 309             throw new CAS_Request_Exception("Bad response, no status code was found in the first line.");
 310         }
 311
 312         return intval($matches[1]);
 313     }
 314
 315     /**
 316      * Answer the body of response.
 317      *
 318      * @return string
 319      * @throws CAS_OutOfSequenceException If called before the Request has been sent.
 320      */
 321     public function getResponseBody ()
 322     {
 323         if (!$this->_sent) {
 324             throw new CAS_OutOfSequenceException('Request has not been sent yet. Cannot '.__METHOD__);
 325         }
 326
 327         return $this->_responseBody;
 328     }
 329
 330     /**
 331      * Answer a message describing any errors if the request failed.
 332      *
 333      * @return string
 334      * @throws CAS_OutOfSequenceException If called before the Request has been sent.
 335      */
 336     public function getErrorMessage ()
 337     {
 338         if (!$this->_sent) {
 339             throw new CAS_OutOfSequenceException('Request has not been sent yet. Cannot '.__METHOD__);
 340         }
 341         return $this->_errorMessage;
 342     }
 343 }