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 7
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 */
40interface 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}
180