## Apache Zeta Components Manual :: File Source for authentication.php

## Source for file authentication.php

Documentation is available at authentication.php

1. <?php
2. /**
3. * File containing the ezcAuthentication class.
4. *
5. * Licensed to the Apache Software Foundation (ASF) under one
6. * or more contributor license agreements. See the NOTICE file
7. * distributed with this work for additional information
8. * regarding copyright ownership. The ASF licenses this file
9. * to you under the Apache License, Version 2.0 (the
10. * "License"); you may not use this file except in compliance
11. * with the License. You may obtain a copy of the License at
12. *
13. * http://www.apache.org/licenses/LICENSE-2.0
14. *
15. * Unless required by applicable law or agreed to in writing,
16. * software distributed under the License is distributed on an
17. * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18. * KIND, either express or implied. See the License for the
19. * specific language governing permissions and limitations
20. * under the License.
21. *
22. * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
23. * @filesource
24. * @package Authentication
25. * @version //autogen//
26. */
28. /**
29. * Container for authentication filters.
30. *
31. * This is the main class of the authentication component. Filters are added to
32. * an object of this class, which will run the filters in sequence. At the end of
33. * this process, the status property will contain the statuses of the filters, and
34. * the developer can use those statuses to display to the user messages such as
35. * "Password incorrect".
36. *
37. * The session property is optional and it is used to store the authentication
38. * information between requests.
39. *
40. * The credentials property will be passed to all the filters in the queue.
41. *
42. * Example (using the Htpasswd filter):
43. * <code>
44. * $credentials = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'b1b3773a05c0ed0176787a4f1574ff0075f7521e' );
45. * $authentication = new ezcAuthentication( $credentials );
46. * $authentication->session = new ezcAuthenticationSession();
47. * $authentication->addFilter( new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd' ) );
48. * // add other filters if needed
49. * if ( !$authentication->run() )
50. * {
51. * // authentication did not succeed, so inform the user
52. * $status = $authentication->getStatus();
53. * $err = array(
54. * 'ezcAuthenticationHtpasswdFilter' => array(
55. * ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
56. * ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
57. * )
58. * );
59. * foreach ( $status as $line )
60. * {
61. * list( $key, $value ) = each( $line );
62. * echo $err[$key][$value] . "\n";
63. * }
64. * }
65. * else
66. * {
67. * // authentication succeeded, so allow the user to see his content
68. * }
69. * </code>
70. *
71. * @property ezcAuthenticationSession $session
72. * The session object to use during authentication to store the
73. * authentication information between requests.
74. * @property ezcAuthenticationStatus $status
75. * The status object which holds the status of the run filters.
76. * @property ezcAuthenticationCredentials $credentials
77. * The user credentials to pass to the authentication filters.
78. *
79. * @package Authentication
80. * @version //autogen//
81. * @mainclass
82. */
83. class ezcAuthentication
84. {
85. /**
86. * The filter queue of the authentication process.
87. *
88. * @var array(ezcAuthenticationFilter)
89. */
90. protected $filters = array();
92. /**
93. * Options for the Authentication object.
94. *
95. * @var ezcAuthenticationOptions
96. */
97. protected $options ;
99. /**
100. * The properties of this class.
101. *
102. * @var array(string=>mixed)
103. */
104. private $properties = array();
106. /**
107. * Creates a new object of this class.
108. *
109. * @param ezcAuthenticationCredentials $credentials Authentication credentials
110. * @param ezcAuthenticationOptions $options Options for this class
111. */
112. public function __construct ( ezcAuthenticationCredentials $credentials, ezcAuthenticationOptions $options = null )
113. {
114. $this->credentials = $credentials;
115. $this->status = new ezcAuthenticationStatus ();
116. $this-> options = ( $options === null ) ? new ezcAuthenticationOptions () : $options;
117. }
119. /**
120. * Sets the property $name to $value.
121. *
122. * @throws ezcBasePropertyNotFoundException
123. * if the property $name does not exist
124. * @throws ezcBaseValueException
125. * if $value is not correct for the property $name
126. * @param string $name The name of the property to set
127. * @param mixed $value The new value of the property
128. * @ignore
129. */
130. public function __set( $name, $value )
131. {
132. switch ( $name )
133. {
134. case 'session':
135. if ( $value instanceof ezcAuthenticationSession )
136. {
137. $this->properties[$name] = $value;
138. }
139. else
140. {
141. throw new ezcBaseValueException ( $name, $value, 'ezcAuthenticationSession' );
142. }
143. break;
145. case 'status':
146. if ( $value instanceof ezcAuthenticationStatus )
147. {
148. $this->properties[$name] = $value;
149. }
150. else
151. {
152. throw new ezcBaseValueException ( $name, $value, 'ezcAuthenticationStatus' );
153. }
154. break;
156. case 'credentials':
157. if ( $value instanceof ezcAuthenticationCredentials )
158. {
159. $this->properties[$name] = $value;
160. }
161. else
162. {
163. throw new ezcBaseValueException ( $name, $value, 'ezcAuthenticationCredentials' );
164. }
165. break;
167. default:
168. throw new ezcBasePropertyNotFoundException ( $name );
169. }
170. }
172. /**
173. * Returns the value of the property $name.
174. *
175. * @throws ezcBasePropertyNotFoundException
176. * if the property $name does not exist
177. * @param string $name The name of the property for which to return the value
178. * @return mixed
179. * @ignore
180. */
181. public function __get( $name )
182. {
183. switch ( $name )
184. {
185. case 'session':
186. case 'status':
187. case 'credentials':
188. return $this->properties[$name];
190. default:
191. throw new ezcBasePropertyNotFoundException ( $name );
192. }
193. }
195. /**
196. * Returns true if the property $name is set, otherwise false.
197. *
198. * @param string $name The name of the property to test if it is set
199. * @return bool
200. * @ignore
201. */
202. public function __isset( $name )
203. {
204. switch ( $name )
205. {
206. case 'session':
207. case 'status':
208. case 'credentials':
209. return isset( $this->properties[$name] );
211. default:
212. return false;
213. }
214. }
216. /**
217. * Sets the options of this class to $options.
218. *
219. * @param ezcAuthenticationOptions $options Options for this class
220. */
221. public function setOptions ( ezcAuthenticationOptions $options )
222. {
223. $this-> options = $options;
224. }
226. /**
227. * Returns the options of this class.
228. *
229. * @return ezcAuthenticationOptions
230. */
231. public function getOptions ()
232. {
233. return $this-> options ;
234. }
236. /**
237. * Runs through all the filters in the filter list.
238. *
239. * @return bool
240. */
241. public function run ()
242. {
243. $code = ezcAuthenticationFilter ::STATUS_OK;
245. $credentials = $this->credentials;
247. if ( isset( $this->session ) )
248. {
249. $code = $this->session->run( $credentials );
250. $this->status->append( get_class ( $this->session ), $code );
251. }
253. if ( !isset( $this->session ) || $code === ezcAuthenticationSession ::STATUS_EMPTY )
254. {
255. foreach ( $this-> filters as $filter )
256. {
257. $code = $filter[0]->run( $credentials );
258. if ( $filter[0] instanceof ezcAuthenticationGroupFilter )
259. {
260. $statuses = $filter[0]->status->get();
262. // append the statuses from the filters in the group to the
263. // status of the Authentication object
264. foreach ( $statuses as $status )
265. {
266. list( $key, $value ) = each ( $status );
267. $this->status->append( $key, $value );
268. }
269. }
270. else
271. {
272. $this->status->append( get_class ( $filter[0] ), $code );
273. }
275. if ( ( $filter[1] === true && $code !== ezcAuthenticationFilter ::STATUS_OK ) )
276. {
277. return false;
278. }
280. if ( $filter[1] === true && $code === ezcAuthenticationFilter ::STATUS_OK )
281. {
282. break;
283. }
284. }
285. }
286. elseif ( $code === ezcAuthenticationSession ::STATUS_EXPIRED )
287. {
288. return false;
289. }
291. if ( $code !== ezcAuthenticationFilter ::STATUS_OK )
292. {
293. return false;
294. }
296. if ( isset( $this->session ) )
297. {
298. $this->session->save( $credentials->__toString() );
299. }
301. return true;
302. }
304. /**
305. * Adds an authentication filter at the end of the filter list.
306. *
307. * By specifying the second parameter as true, the authentication process
308. * (triggered by calling the run() method) will stop after processing this
309. * filter regardless of its success.
310. *
311. * @param ezcAuthenticationFilter $filter The authentication filter to add
312. * @param bool $stop If authentication should continue past this filter
313. */
314. public function addFilter ( ezcAuthenticationFilter $filter, $stop = false )
315. {
316. $this-> filters [] = array( $filter, $stop );
317. }
319. /**
320. * Returns the status of authentication.
321. *
322. * The format of the returned array is array( array( class => code ) ).
323. *
324. * Example:
325. * <code>
326. * array(
327. * array( 'ezcAuthenticationSession' => ezcAuthenticationSession::STATUS_EMPTY ),
328. * array( 'ezcAuthenticationDatabaseFilter' => ezcAuthenticationDatabaseFilter::STATUS_PASSWORD_INCORRECT )
329. * );
330. * </code>
331. *
332. * @return array(string=>mixed)
333. */
334. public function getStatus ()
335. {
336. return $this->status->get();
337. }
338. }
339. ?>

Documentation generated by phpDocumentor 1.4.3