CAS/CAS/Request/RequestInterface.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/RequestInterface.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  * This interface defines a class library for performing web requests.
  32  *
  33  * @class    CAS_Request_RequestInterface
  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 interface CAS_Request_RequestInterface
  41 {
  42
  43     /*********************************************************
  44      * Configure the Request
  45     *********************************************************/
  46
  47     /**
  48      * Set the URL of the Request
  49      *
  50      * @param string $url url to set
  51      *
  52      * @return void
  53      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
  54      */
  55     public function setUrl ($url);
  56
  57     /**
  58      * Add a cookie to the request.
  59      *
  60      * @param string $name  name of cookie
  61      * @param string $value value of cookie
  62      *
  63      * @return void
  64      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
  65      */
  66     public function addCookie ($name, $value);
  67
  68     /**
  69      * Add an array of cookies to the request.
  70      * The cookie array is of the form
  71      *     array('cookie_name' => 'cookie_value', 'cookie_name2' => cookie_value2')
  72      *
  73      * @param array $cookies cookies to add
  74      *
  75      * @return void
  76      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
  77      */
  78     public function addCookies (array $cookies);
  79
  80     /**
  81      * Add a header string to the request.
  82      *
  83      * @param string $header header to add
  84      *
  85      * @return void
  86      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
  87      */
  88     public function addHeader ($header);
  89
  90     /**
  91      * Add an array of header strings to the request.
  92      *
  93      * @param array $headers headers to add
  94      *
  95      * @return void
  96      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
  97      */
  98     public function addHeaders (array $headers);
  99
 100     /**
 101      * Make the request a POST request rather than the default GET request.
 102      *
 103      * @return void
 104      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
 105      */
 106     public function makePost ();
 107
 108     /**
 109      * Add a POST body to the request
 110      *
 111      * @param string $body body to add
 112      *
 113      * @return void
 114      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
 115      */
 116     public function setPostBody ($body);
 117
 118
 119     /**
 120      * Specify the path to an SSL CA certificate to validate the server with.
 121      *
 122      * @param string  $caCertPath  path to cert file
 123      * @param boolean $validate_cn validate CN of SSL certificate
 124      *
 125      * @return void
 126      * @throws CAS_OutOfSequenceException If called after the Request has been sent.
 127      */
 128     public function setSslCaCert ($caCertPath, $validate_cn = true);
 129
 130
 131
 132     /*********************************************************
 133      * 2. Send the Request
 134     *********************************************************/
 135
 136     /**
 137      * Perform the request.
 138      *
 139      * @return bool TRUE on success, FALSE on failure.
 140      * @throws CAS_OutOfSequenceException If called multiple times.
 141      */
 142     public function send ();
 143
 144     /*********************************************************
 145      * 3. Access the response
 146     *********************************************************/
 147
 148     /**
 149      * Answer the headers of the response.
 150      *
 151      * @return array An array of header strings.
 152      * @throws CAS_OutOfSequenceException If called before the Request has been sent.
 153      */
 154     public function getResponseHeaders ();
 155
 156     /**
 157      * Answer HTTP status code of the response
 158      *
 159      * @return int
 160      * @throws CAS_OutOfSequenceException If called before the Request has been sent.
 161      */
 162     public function getResponseStatusCode ();
 163
 164     /**
 165      * Answer the body of response.
 166      *
 167      * @return string
 168      * @throws CAS_OutOfSequenceException If called before the Request has been sent.
 169      */
 170     public function getResponseBody ();
 171
 172     /**
 173      * Answer a message describing any errors if the request failed.
 174      *
 175      * @return string
 176      * @throws CAS_OutOfSequenceException If called before the Request has been sent.
 177      */
 178     public function getErrorMessage ();
 179 }