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

## Source for file url_configuration.php

Documentation is available at url_configuration.php

1. <?php
2. /**
3. * File containing the ezcUrlConfiguration 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. * @version //autogentag//
24. * @filesource
25. * @package Url
26. */
28. /**
29. * ezcUrlConfiguration makes it possible to use a custom URL form in your application.
30. *
31. * A URL is assumed to be of this form:
32. * scheme://host/basedir/script/ordered_parameters/unordered_parameters
33. *
34. * Example:
35. * http://example.com/mydir/index.php/groups/Games/Adventure/Adult/(game)/Larry/7
36. *
37. * Where:
38. * scheme = "http"
39. * host = "example.com"
40. * basedir = "mydir"
41. * script = "index.php"
42. * ordered parameters = "groups", "Games", "Adventure", "Adult"
43. * unordered parameters = array( "Larry", "7" )
44. *
45. * When creating a configuration with ordered parameters, those parameters are
46. * required to be present in the parsed URL, in the same number as the
47. * configuration states. Having a different number of ordered parameters in the
48. * parsed URL will lead to wrong values assigned to the unordered parameters (if
49. * any follow the ordered parameters).
50. *
51. * See the tutorial for a way to change configurations dynamically based on
52. * the ordered parameters.
53. *
54. * Example of use:
55. * <code>
56. * // create an ezcUrlConfiguration object
57. * $urlCfg = new ezcUrlConfiguration();
58. * // set the basedir and script values
59. * $urlCfg->basedir = 'mydir';
60. * $urlCfg->script = 'index.php';
61. *
62. * // define delimiters for unordered parameter names
63. * $urlCfg->unorderedDelimiters = array( '(', ')' );
64. *
65. * // define ordered parameters
66. * $urlCfg->addOrderedParameter( 'section' );
67. * $urlCfg->addOrderedParameter( 'group' );
68. * $urlCfg->addOrderedParameter( 'category' );
69. * $urlCfg->addOrderedParameter( 'subcategory' );
70. *
71. * // define unordered parameters
72. * $urlCfg->addUnorderedParameter( 'game', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
73. *
74. * // create a new ezcUrl object from a string URL and use the above $urlCfg
75. * $url = new ezcUrl( 'http://www.example.com/mydir/index.php/groups/Games/Adventure/Adult/(game)/Larry/7', $urlCfg );
76. *
77. * // to get the parameter values from the URL use $url->getParam():
78. * $section = $url->getParam( 'section' ); // will be "groups"
79. * $group = $url->getParam( 'group' ); // will be "Games"
80. * $category = $url->getParam( 'category' ); // will be "Adventure"
81. * $subcategory = $url->getParam( 'subcategory' ); // will be "Adult"
82. * $game = $url->getParam( 'game' ); // will be array( "Larry", "7" )
83. *
84. * // to remove parameters from the URL configuration $urlCfg
85. * $urlCfg->removeOrderedParameter( 'subcategory' );
86. * $urlCfg->removeUnorderedParameter( 'game' );
87. *
88. * // to remove parameters from the URL configuration stored in the URL
89. * $url->configuration->removeOrderedParameter( 'subcategory' );
90. * $url->configuration->removeUnorderedParameter( 'game' );
91. * </code>
92. *
93. * Example of aggregating values for unordered parameters:
94. * <code>
95. * $urlCfg = new ezcUrlConfiguration();
96. *
97. * $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
98. * $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
99. *
100. * $param1 = $url->getParam( 'param1' ); // will be array( array( "x" ), array( "y", "z" ) )
101. * </code>
102. *
103. * @property string $basedir
104. * The part of the URL after the first slash. It can be null.
105. * Example: $basedir = shop in http://www.example.com/shop
106. * @property string $script
107. * The default php script, which comes after the basedir. Can be null
108. * if the web server configuration is set to hide it.
109. * Example: $script = index.php in http://www.example.com/shop/index.php
110. * @property array(string) $unorderedDelimiters
111. * The delimiters for the unordered parameters names.
112. * Example: $unorderedDelimiters = array( '(', ')' ) for
113. * url = http://www.example.com/doc/(file)/classtrees_Base.html
114. * @property array(string=>int) $orderedParameters
115. * The ordered parameters of the URL.
116. * Example: $orderedParameters = array( 'section' => 0, 'module' => 1, 'view' => 2, 'content' => 3 );
117. * url = http://www.example.com/doc/components/view/trunk
118. * The numbers in the array represent the indices for each parameter.
119. * @property array(string=>int) $unorderedParameters
120. * The unordered parameters of the URL.
121. * Example: $unorderedParameters = array( 'file' => SINGLE_ARGUMENT );
122. * url = http://www.example.com/doc/(file)/classtrees_Base.html
123. * The keys of the array represent the parameter names, and the values
124. * in the array represent the types of the parameters.
125. *
126. * @package Url
127. * @version //autogen//
128. */
129. class ezcUrlConfiguration
130. {
131. /**
132. * Flag for specifying single arguments for unordered parameters.
133. */
134. const SINGLE_ARGUMENT = 1;
136. /**
137. * Flag for specifying multiple arguments for unordered parameters.
138. */
139. const MULTIPLE_ARGUMENTS = 2;
141. /**
142. * Flag for specifying aggregation for unordered parameter values if the
143. * parameter name appears more than once in the URL.
144. *
145. * For example, if the URL is 'http://www.example.com/(param1)/x/(param1)/y/z',
146. * then all values will be considered for the parameter param1. So
147. * $url->getParam( 'param1' ) will return array( array( "x" ), array( "y", "z" ) ),
148. * if $url is an ezcUrl object created from the above URL.
149. */
150. const AGGREGATE_ARGUMENTS = 4;
152. /**
153. * Holds the properties of this class.
154. *
155. * @var array(string=>mixed)
156. */
157. private $properties = array();
159. /**
160. * Stores the instance of this class.
161. *
162. * @var ezcUrlConfiguration
163. */
164. private static $instance = null;
166. /**
167. * Constructs a new ezcUrlConfiguration object.
168. *
169. * The properties of the object get default values, which can be changed by
170. * setting the properties directly, like:
171. * <code>
172. * $urlCfg = new ezcUrlConfiguration();
173. * $urlCfg->basedir = 'mydir';
174. * $urlCfg->script = 'index.php';
175. * </code>
176. */
177. public function __construct ()
178. {
179. $this->basedir = null;
180. $this->script = null;
181. $this->unorderedDelimiters = array( '(', ')' );
182. $this->orderedParameters = array();
183. $this->unorderedParameters = array();
184. }
186. /**
187. * Returns the instance of the class.
188. *
189. * @return ezcUrlConfiguration
190. */
191. public static function getInstance ()
192. {
193. if ( is_null ( self::$instance ) )
194. {
195. self::$instance = new ezcUrlConfiguration();
196. ezcBaseInit :: fetchConfig ( 'ezcUrlConfiguration', self::$instance );
197. }
198. return self::$instance;
199. }
201. /**
202. * Sets the property $name to $value.
203. *
204. * @throws ezcBasePropertyNotFoundException
205. * if the property does not exist.
206. * @param string $name The name of the property to set
207. * @param mixed $value The new value of the property
208. * @ignore
209. */
210. public function __set( $name, $value )
211. {
212. switch ( $name )
213. {
214. case 'basedir':
215. case 'script':
216. case 'unorderedDelimiters':
217. case 'orderedParameters':
218. case 'unorderedParameters':
219. $this->properties[$name] = $value;
220. break;
222. default:
223. throw new ezcBasePropertyNotFoundException( $name );
224. }
225. }
227. /**
228. * Returns the property $name.
229. *
230. * @throws ezcBasePropertyNotFoundException
231. * if the property does not exist.
232. * @param string $name The name of the property for which to return the value
233. * @return mixed
234. * @ignore
235. */
236. public function __get( $name )
237. {
238. switch ( $name )
239. {
240. case 'basedir':
241. case 'script':
242. case 'unorderedDelimiters':
243. case 'orderedParameters':
244. case 'unorderedParameters':
245. return $this->properties[$name];
247. default:
248. throw new ezcBasePropertyNotFoundException ( $name );
249. }
250. }
252. /**
253. * Returns true if the property $name is set, otherwise false.
254. *
255. * @param string $name The name of the property to test if it is set
256. * @return bool
257. * @ignore
258. */
259. public function __isset( $name )
260. {
261. switch ( $name )
262. {
263. case 'basedir':
264. case 'script':
265. case 'unorderedDelimiters':
266. case 'orderedParameters':
267. case 'unorderedParameters':
268. return isset( $this->properties[$name] );
270. default:
271. return false;
272. }
273. }
275. /**
276. * Adds an ordered parameter to the URL configuration.
277. *
278. * Ordered parameters must be added before unordered parameters, and
279. * they must appear in the parsed URL in the same number and order
280. * as they are defined in the configuration.
281. *
282. * @param string $name The name of the ordered parameter to add to the configuration
283. */
284. public function addOrderedParameter ( $name )
285. {
286. $this->properties['orderedParameters'][$name] = count ( $this->properties['orderedParameters'] );
287. }
289. /**
290. * Removes an ordered parameter from the URL configuration.
291. *
292. * @param string $name The name of the ordered parameter to remove from the configuration
293. */
294. public function removeOrderedParameter ( $name )
295. {
296. if ( isset( $this->properties['orderedParameters'][$name] ) )
297. {
298. unset( $this->properties['orderedParameters'][$name] );
299. }
300. }
302. /**
303. * Adds an unordered parameter to the URL configuration.
304. *
305. * The possible values for the $type parameter are:
306. * - {@link ezcUrlConfiguration::SINGLE_ARGUMENT} (default): the getParam()
307. * method in ezcUrl will return a string containing the value of the
308. * parameter $name
309. * - {@link ezcUrlConfiguration::MULTIPLE_ARGUMENTS}: the getParam() method
310. * will return an array containing the last encountered values of the
311. * parameter $name
312. * - {@link ezcUrlConfiguration::AGGREGATE_ARGUMENTS}: the getParam() method
313. * will return an array with all encountered values for the parameter $name
314. *
315. * Examples:
316. * <code>
317. * $urlCfg = new ezcUrlConfiguration();
318. *
319. * // single parameter value
320. * $urlCfg->addUnorderedParameter( 'param1' ); // type is SINGLE_ARGUMENT by default
321. * $url = new ezcUrl( 'http://www.example.com/(param1)/x', $urlCfg );
322. * $param1 = $url->getParam( 'param1' ); // will return "x"
323. *
324. * // multiple parameter values
325. * $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
326. * $url = new ezcUrl( 'http://www.example.com/(param1)/x/y', $urlCfg );
327. * $param1 = $url->getParam( 'param1' ); // will return array( "x", "y" )
328. *
329. * // multiple parameter values with aggregation
330. * $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
331. * $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
332. * $param1 = $url->getParam( 'param1' ); // will return array( array( "x" ), array( "y", "z" ) )
333. * </code>
334. *
335. * Ordered parameters must be added before unordered parameters, and
336. * they must appear in the parsed URL in the same number and order
337. * as they are defined in the configuration.
338. *
339. * @param string $name The name of the unordered parameter to add to the configuration
340. * @param int $type The type of the unordered parameter
341. */
342. public function addUnorderedParameter ( $name, $type = null )
343. {
344. if ( $type == null )
345. {
346. $type = self::SINGLE_ARGUMENT;
347. }
348. $this->properties['unorderedParameters'][$name] = $type;
349. }
351. /**
352. * Removes an unordered parameter from the URL configuration.
353. *
354. * @param string $name The name of the unordered parameter to remove from the configuration
355. */
356. public function removeUnorderedParameter ( $name )
357. {
358. if ( isset( $this->properties['unorderedParameters'][$name] ) )
359. {
360. unset( $this->properties['unorderedParameters'][$name] );
361. }
362. }
363. }
364. ?>

Documentation generated by phpDocumentor 1.4.3