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

## Source for file group_filter.php

Documentation is available at group_filter.php

1. <?php
2. /**
3. * File containing the ezcAuthenticationGroupFilter 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. * Group authentication filters together.
30. *
31. * If there are no filters in the group, then the run() method will return
32. * STATUS_OK.
33. *
34. * The way of grouping the filters is specified with the mode option:
35. * - ezcAuthenticationGroupFilter::MODE_OR (default): at least one filter
36. * in the group needs to succeed in order for the group to succeed.
37. * - ezcAuthenticationGroupFilter::MODE_AND: all filters in the group
38. * need to succeed in order for the group to succeed.
39. *
40. * Example of using the mode option:
41. * <code>
42. * $options = new ezcAuthenticationGroupOptions();
43. * $options->mode = ezcAuthenticationGroupFilter::MODE_AND;
44. *
45. * // $filter1 and $filter2 are authentication filters which all need to succeed
46. * // in order for the group to succeed
47. * $filter = new ezcAuthenticationGroupFilter( array( $filter1, $filter2 ), $options );
48. * </code>
49. *
50. * Example of using the group filter with LDAP and Database filters:
51. * <code>
52. * $credentials = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'qwerty' );
53. *
54. * // create a database filter
55. * $database = new ezcAuthenticationDatabaseInfo( ezcDbInstance::get(), 'users', array( 'user', 'password' ) );
56. * $databaseFilter = new ezcAuthenticationDatabaseFilter( $database );
57. *
58. * // create an LDAP filter
59. * $ldap = new ezcAuthenticationLdapInfo( 'localhost', 'uid=%id%', 'dc=example,dc=com', 389 );
60. * $ldapFilter = new ezcAuthenticationLdapFilter( $ldap );
61. * $authentication = new ezcAuthentication( $credentials );
62. *
63. * // use the database and LDAP filters in paralel (at least one needs to succeed in
64. * // order for the user to be authenticated)
65. * $authentication->addFilter( new ezcAuthenticationGroupFilter( array( $databaseFilter, $ldapFilter ) ) );
66. * // add more filters if needed
67. * if ( !$authentication->run() )
68. * {
69. * // authentication did not succeed, so inform the user
70. * $status = $authentication->getStatus();
71. * $err = array(
72. * array( 'ezcAuthenticationLdapFilter' => array(
73. * ezcAuthenticationLdapFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
74. * ezcAuthenticationLdapFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
75. * ) ),
76. * array( 'ezcAuthenticationDatabaseFilter' => array(
77. * ezcAuthenticationDatabaseFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username',
78. * ezcAuthenticationDatabaseFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password'
79. * ) )
80. * );
81. * foreach ( $status as $line => $error )
82. * {
83. * list( $key, $value ) = each( $error );
84. * echo $err[$line][$key][$value] . "\n";
85. * }
86. * }
87. * else
88. * {
89. * // authentication succeeded, so allow the user to see his content
90. * }
91. * </code>
92. *
93. * It is possible to use multiple credentials when grouping filters together, by
94. * enabling the option multipleCredentials for the Group filter object. When this
95. * option is enabled, each filter added to the group must have a credentials
96. * object passed along with it.
97. *
98. * Example of using the Group filter to handle multiple credentials:
99. * <code>
100. * $credentials1 = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'b1b3773a05c0ed0176787a4f1574ff0075f7521e' ); // incorrect password
101. * $credentials2 = new ezcAuthenticationPasswordCredentials( 'john.doe', 'wpeE20wyWHnLE' ); // correct username + password
102. *
103. * $options = new ezcAuthenticationGroupOptions();
104. * $options->multipleCredentials = true;
105. * $options->mode = ezcAuthenticationGroupFilter::MODE_AND;
106. * $group = new ezcAuthenticationGroupFilter( array(), $options );
107. *
108. * $group->addFilter( new ezcAuthenticationHtpasswdFilter( '../../tests/filters/htpasswd/data/htpasswd' ), $credentials1 );
109. * $group->addFilter( new ezcAuthenticationHtpasswdFilter( '../../tests/filters/htpasswd/data/htpasswd' ), $credentials2 );
110. *
111. * $authentication = new ezcAuthentication( $credentials1 );
112. * $authentication->addFilter( $group );
113. * // add more filters if needed
114. *
115. * if ( !$authentication->run() )
116. * {
117. * // authentication did not succeed, so inform the user
118. * $status = $authentication->getStatus();
119. *
120. * $err = array(
121. * array( 'ezcAuthenticationHtpasswdFilter' => array(
122. * ezcAuthenticationHtpasswdFilter::STATUS_OK => '',
123. * ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username ' . $credentials1->id,
124. * ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password for ' . $credentials1->id
125. * ) ),
126. *
127. * array( 'ezcAuthenticationHtpasswdFilter' => array(
128. * ezcAuthenticationHtpasswdFilter::STATUS_OK => '',
129. * ezcAuthenticationHtpasswdFilter::STATUS_USERNAME_INCORRECT => 'Incorrect username ' . $credentials2->id,
130. * ezcAuthenticationHtpasswdFilter::STATUS_PASSWORD_INCORRECT => 'Incorrect password for ' . $credentials2->id
131. * ) )
132. * );
133. *
134. * foreach ( $status as $line => $error )
135. * {
136. * list( $key, $value ) = each( $error );
137. * echo $err[$line][$key][$value] . "\n";
138. * }
139. * }
140. * else
141. * {
142. * // authentication succeeded, so allow the user to see his content
143. * }
144. * </code>
145. *
146. * @property ezcAuthenticationStatus $status
147. * The status object which holds the status of the run filters.
148. *
149. * @package Authentication
150. * @version //autogen//
151. * @mainclass
152. */
153. class ezcAuthenticationGroupFilter extends ezcAuthenticationFilter
154. {
155. /**
156. * All or some of the filters in the group failed (depeding on the mode
157. * option).
158. */
159. const STATUS_GROUP_FAILED = 1;
161. /**
162. * At least one filter needs to succeed in order for the group to succeed.
163. */
164. const MODE_OR = 1;
166. /**
167. * All the filters need to succeed in order for the group to succeed.
168. */
169. const MODE_AND = 2;
171. /**
172. * Authentication filters.
173. *
174. * @var array(ezcAuthenticationFilter)
175. */
176. protected $filters = array();
178. /**
179. * The properties of this class.
180. *
181. * @var array(string=>mixed)
182. */
183. private $properties = array();
185. /**
186. * Creates a new object of this class.
187. *
188. * The filters can be specified as an array of filter objects, or as an
189. * array of array(fiter,credentials) when the multipleCredentials option is
190. * enabled.
191. *
192. * Example of using multipleCredentials:
193. * <code>
194. * $credentials1 = new ezcAuthenticationPasswordCredentials( 'john.doe', '1234' );
195. * $credentials1 = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'qwerty' );
196. *
197. * $filter1 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd1' );
198. * $filter2 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd2' );
199. *
200. * // enable multiple credentials
201. * $options = new ezcAuthenticationGroupOptions();
202. * $options->multipleCredentials = true;
203. *
204. * // add the filters to the group with the constructor
205. * $group = new ezcAuthenticationGroupFilter( array(
206. * array( $filter1, $credentials1 ),
207. * array( $filter2, $credentials2 ) ), $options );
208. *
209. * // the filters can also be added to the group with addFilter()
210. * </code>
211. *
212. * @throws ezcAuthenticationException
213. * if the multipleCredentials option is enabled and a credentials
214. * object was not specified
215. * @param array(ezcAuthenticationFilter|mixed)$filters Authentication filters
216. * @param ezcAuthenticationGroupOptions $options Options for this class
217. */
218. public function __construct ( array $filters, ezcAuthenticationGroupOptions $options = null )
219. {
220. $this->options = ( $options === null ) ? new ezcAuthenticationGroupOptions() : $options;
222. foreach ( $filters as $filter )
223. {
224. if ( is_array( $filter ) )
225. {
226. if ( count( $filter ) > 1 )
227. {
228. $this-> addFilter ( $filter[0], $filter[1] );
229. }
230. else
231. {
232. $this-> addFilter ( $filter[0] );
233. }
234. }
235. else
236. {
237. $this-> addFilter ( $filter );
238. }
239. }
241. $this->status = new ezcAuthenticationStatus ();
242. }
244. /**
245. * Sets the property $name to $value.
246. *
247. * @throws ezcBasePropertyNotFoundException
248. * if the property $name does not exist
249. * @throws ezcBaseValueException
250. * if $value is not correct for the property $name
251. * @param string $name The name of the property to set
252. * @param mixed $value The new value of the property
253. * @ignore
254. */
255. public function __set( $name, $value )
256. {
257. switch ( $name )
258. {
259. case 'status':
260. if ( $value instanceof ezcAuthenticationStatus )
261. {
262. $this->properties[$name] = $value;
263. }
264. else
265. {
266. throw new ezcBaseValueException ( $name, $value, 'ezcAuthenticationStatus' );
267. }
268. break;
270. default:
271. throw new ezcBasePropertyNotFoundException ( $name );
272. }
273. }
275. /**
276. * Returns the value of the property $name.
277. *
278. * @throws ezcBasePropertyNotFoundException
279. * if the property $name does not exist
280. * @param string $name The name of the property for which to return the value
281. * @return mixed
282. * @ignore
283. */
284. public function __get( $name )
285. {
286. switch ( $name )
287. {
288. case 'status':
289. return $this->properties[$name];
291. default:
292. throw new ezcBasePropertyNotFoundException ( $name );
293. }
294. }
296. /**
297. * Returns true if the property $name is set, otherwise false.
298. *
299. * @param string $name The name of the property to test if it is set
300. * @return bool
301. * @ignore
302. */
303. public function __isset( $name )
304. {
305. switch ( $name )
306. {
307. case 'status':
308. return isset( $this->properties[$name] );
310. default:
311. return false;
312. }
313. }
315. /**
316. * Runs the filter and returns a status code when finished.
317. *
318. * @param ezcAuthenticationCredentials $credentials Authentication credentials
319. * @return int
320. */
321. public function run ( $credentials )
322. {
323. if ( count ( $this-> filters ) === 0 )
324. {
325. return self::STATUS_OK;
326. }
328. $success = false;
330. if ( $this-> options ->mode === self::MODE_OR )
331. {
332. $success = false;
333. foreach ( $this-> filters as $filter )
334. {
335. $credentials = ( $this-> options ->multipleCredentials === true ) ? $filter[1] :
336. $credentials;
338. $code = $filter[0]-> run ( $credentials );
339. $this->status->append( get_class ( $filter[0] ), $code );
340. if ( $code === self::STATUS_OK )
341. {
342. $success = true;
343. }
344. }
345. }
347. if ( $this-> options ->mode === self::MODE_AND )
348. {
349. $success = true;
350. foreach ( $this-> filters as $filter )
351. {
352. $credentials = ( $this-> options ->multipleCredentials === true ) ? $filter[1] :
353. $credentials;
355. $code = $filter[0]-> run ( $credentials );
356. $this->status->append( get_class ( $filter[0] ), $code );
357. if ( $code !== self::STATUS_OK )
358. {
359. $success = false;
360. }
361. }
362. }
364. // other modes are not possible due to the way mode is set in __set()
365. // in the options class
367. return ( $success === true ) ? self::STATUS_OK :
368. self::STATUS_GROUP_FAILED;
369. }
371. /**
372. * Adds an authentication filter at the end of the filter list.
373. *
374. * Example of using multipleCredentials:
375. * <code>
376. * $credentials1 = new ezcAuthenticationPasswordCredentials( 'john.doe', '1234' );
377. * $credentials1 = new ezcAuthenticationPasswordCredentials( 'jan.modaal', 'qwerty' );
378. *
379. * $filter1 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd1' );
380. * $filter2 = new ezcAuthenticationHtpasswdFilter( '/etc/htpasswd2' );
381. *
382. * // enable multiple credentials
383. * $options = new ezcAuthenticationGroupOptions();
384. * $options->multipleCredentials = true;
385. *
386. * // add the filters to the group with addFilter()
387. * $group = new ezcAuthenticationGroupFilter( array(), $options );
388. * $group->addFilter( $filter1, $credentials1 );
389. * $group->addFilter( $filter2, $credentials2 );
390. *
391. * // the filters can also be added to the group with the constructor
392. * </code>
393. *
394. * @throws ezcAuthenticationGroupException
395. * if the multipleCredentials option is enabled and a credentials
396. * object was not specified
397. * @param ezcAuthenticationFilter $filter The authentication filter to add
398. * @param ezcAuthenticationCredentials $credentials Credentials object associated
399. * with $filter if the multipleCredentials
400. * option is enabled
401. */
402. public function addFilter ( ezcAuthenticationFilter $filter, ezcAuthenticationCredentials $credentials = null )
403. {
404. if ( $this-> options ->multipleCredentials === true )
405. {
406. if ( $credentials === null )
407. {
408. throw new ezcAuthenticationGroupException ( 'A credentials object must be specified for each filter when the multipleCredentials option is enabled.' );
409. }
411. $this-> filters [] = array( $filter, $credentials );
412. }
413. else
414. {
415. $this-> filters [] = array( $filter );
416. }
417. }
418. }
419. ?>

Documentation generated by phpDocumentor 1.4.3