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

## Source for file url.php

Documentation is available at url.php

1. <?php
2. /**
3. * File containing the ezcUrl 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 //autogen//
24. * @filesource
25. * @package Url
26. */
28. /**
29. * ezcUrl stores an URL both absolute and relative and contains methods to
30. * retrieve the various parts of the URL and to manipulate them.
31. *
32. * A URL is assumed to be of this form:
33. * scheme://host/basedir/script/ordered_parameters/unordered_parameters
34. *
35. * Example:
36. * http://example.com/mydir/index.php/groups/Games/Adventure/Adult/(game)/Larry/7
37. *
38. * Where:
39. * scheme = "http"
40. * host = "example.com"
41. * basedir = "mydir"
42. * script = "index.php"
43. * ordered parameters = "groups", "Games", "Adventure", "Adult"
44. * unordered parameters = array( "Larry", "7" )
45. *
46. * When creating a configuration with ordered parameters, those parameters are
47. * required to be present in the parsed URL, in the same number as the
48. * configuration states. Having a different number of ordered parameters in the
49. * parsed URL will lead to wrong values assigned to the unordered parameters (if
50. * any follow the ordered parameters).
51. *
52. * See the tutorial for a way to change configurations dynamically based on
53. * the ordered parameters.
54. *
55. * Example of use:
56. * <code>
57. * // create an ezcUrlConfiguration object
58. * $urlCfg = new ezcUrlConfiguration();
59. * // set the basedir and script values
60. * $urlCfg->basedir = 'mydir';
61. * $urlCfg->script = 'index.php';
62. *
63. * // define delimiters for unordered parameter names
64. * $urlCfg->unorderedDelimiters = array( '(', ')' );
65. *
66. * // define ordered parameters
67. * $urlCfg->addOrderedParameter( 'section' );
68. * $urlCfg->addOrderedParameter( 'group' );
69. * $urlCfg->addOrderedParameter( 'category' );
70. * $urlCfg->addOrderedParameter( 'subcategory' );
71. *
72. * // define unordered parameters
73. * $urlCfg->addUnorderedParameter( 'game', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
74. *
75. * // create a new ezcUrl object from a string URL and use the above $urlCfg
76. * $url = new ezcUrl( 'http://www.example.com/mydir/index.php/groups/Games/Adventure/Adult/(game)/Larry/7', $urlCfg );
77. *
78. * // to get the parameter values from the URL use $url->getParam():
79. * $section = $url->getParam( 'section' ); // will be "groups"
80. * $group = $url->getParam( 'group' ); // will be "Games"
81. * $category = $url->getParam( 'category' ); // will be "Adventure"
82. * $subcategory = $url->getParam( 'subcategory' ); // will be "Adult"
83. * $game = $url->getParam( 'game' ); // will be array( "Larry", "7" )
84. * </code>
85. *
86. * Example of aggregating values for unordered parameters:
87. * <code>
88. * $urlCfg = new ezcUrlConfiguration();
89. *
90. * $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
91. * $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
92. *
93. * $param1 = $url->getParam( 'param1' ); // will be array( array( "x" ), array( "y", "z" ) )
94. * </code>
95. *
96. * Unordered parameters can also be fetched as a flat array (useful if the
97. * URL doesn't have delimiters for the unordered parameter names). Example:
98. * <code>
99. * $urlCfg = new ezcUrlConfiguration();
100. * $urlCfg->basedir = '/mydir/shop';
101. * $urlCfg->script = 'index.php';
102. * $urlCfg->addOrderedParameter( 'module' );
103. *
104. * $url = new ezcUrl( 'http://www.example.com/mydir/shop/index.php/order/Software/PHP/Version/5.2/Extension/XDebug/Extension/openssl', $urlCfg );
105. *
106. * $params = $url->getParams(); // will be array( 'Software', 'PHP', 'Version', '5.2', 'Extension', 'XDebug', 'Extension', 'openssl' )
107. * </code>
108. *
109. * @property string $host
110. * Hostname or null
111. * @property array(string) $path
112. * Complete path as an array.
113. * @property string $user
114. * User or null.
115. * @property string $pass
116. * Password or null.
117. * @property string $port
118. * Port or null.
119. * @property string $scheme
120. * Protocol or null.
121. * @property array(string=>mixed) $query
122. * Complete query string as an associative array.
123. * @property string $fragment
124. * Anchor or null.
125. * @property array(string) $basedir
126. * Base directory (the part before the script name) or null.
127. * @property array(string) $script
128. * Script name (eg. 'index.php') or null.
129. * @property array(string) $params
130. * Complete ordered parameters as array.
131. * @property array(string=>mixed) $uparams
132. * Complete unordered parameters as associative array.
133. * @property ezcUrlConfiguration $configuration
134. * The URL configuration defined for this URL, or null.
135. *
136. * @package Url
137. * @version //autogen//
138. * @mainclass
139. */
140. class ezcUrl
141. {
142. /**
143. * Holds the properties of this class.
144. *
145. * @var array(string=>mixed)
146. */
147. private $properties = array();
149. /**
150. * Constructs a new ezcUrl object from the string $url.
151. *
152. * If the $configuration parameter is provided, then it will apply the
153. * configuration to the URL by calling {@link applyConfiguration()}.
154. *
155. * @param string $url A string URL from which to construct the URL object
156. * @param ezcUrlConfiguration $configuration An optional URL configuration used when parsing and building the URL
157. */
158. public function __construct ( $url = null, ezcUrlConfiguration $configuration = null )
159. {
160. $this->parseUrl( $url );
161. $this->configuration = $configuration;
162. if ( $configuration != null )
163. {
164. $this-> applyConfiguration ( $configuration );
165. }
166. }
168. /**
169. * Sets the property $name to $value.
170. *
171. * @throws ezcBasePropertyNotFoundException
172. * if the property $name does not exist
173. * @throws ezcBaseValueException
174. * if $value is not correct for the property $name
175. * @param string $name The name of the property to set
176. * @param mixed $value The new value of the property
177. * @ignore
178. */
179. public function __set( $name, $value )
180. {
181. switch ( $name )
182. {
183. case 'host':
184. case 'path':
185. case 'user':
186. case 'pass':
187. case 'port':
188. case 'scheme':
189. case 'fragment':
190. case 'query':
191. case 'basedir':
192. case 'script':
193. case 'params':
194. case 'uparams':
195. $this->properties[$name] = $value;
196. break;
198. case 'configuration':
199. if ( $value === null || $value instanceof ezcUrlConfiguration )
200. {
201. $this->properties[$name] = $value;
202. }
203. else
204. {
205. throw new ezcBaseValueException ( $name, $value, 'instance of ezcUrlConfiguration' );
206. }
207. break;
209. default:
210. throw new ezcBasePropertyNotFoundException ( $name );
211. break;
212. }
213. }
215. /**
216. * Returns the property $name.
217. *
218. * @throws ezcBasePropertyNotFoundException
219. * if the property $name does not exist
220. * @param string $name The name of the property for which to return the value
221. * @return mixed
222. * @ignore
223. */
224. public function __get( $name )
225. {
226. switch ( $name )
227. {
228. case 'host':
229. case 'path':
230. case 'user':
231. case 'pass':
232. case 'port':
233. case 'scheme':
234. case 'fragment':
235. case 'query':
236. case 'basedir':
237. case 'script':
238. case 'params':
239. case 'uparams':
240. case 'configuration':
241. return $this->properties[$name];
243. default:
244. throw new ezcBasePropertyNotFoundException ( $name );
245. }
246. }
248. /**
249. * Returns true if the property $name is set, otherwise false.
250. *
251. * @param string $name The name of the property to test if it is set
252. * @return bool
253. * @ignore
254. */
255. public function __isset( $name )
256. {
257. switch ( $name )
258. {
259. case 'host':
260. case 'path':
261. case 'user':
262. case 'pass':
263. case 'port':
264. case 'scheme':
265. case 'fragment':
266. case 'query':
267. case 'basedir':
268. case 'script':
269. case 'params':
270. case 'uparams':
271. case 'configuration':
272. return isset( $this->properties[$name] );
274. default:
275. return false;
276. }
277. }
279. /**
280. * Returns this URL as a string by calling {@link buildUrl()}.
281. *
282. * @return string
283. */
284. public function __toString ()
285. {
286. return $this-> buildUrl ();
287. }
289. /**
290. * Parses the string $url and sets the class properties.
291. *
292. * @param string $url A string URL to parse
293. */
294. private function parseUrl( $url = null )
295. {
296. $urlArray = parse_url ( $url );
298. $this->properties['host'] = isset( $urlArray['host'] ) ? $urlArray['host'] : null;
299. $this->properties['user'] = isset( $urlArray['user'] ) ? $urlArray['user'] : null;
300. $this->properties['pass'] = isset( $urlArray['pass'] ) ? $urlArray['pass'] : null;
301. $this->properties['port'] = isset( $urlArray['port'] ) ? $urlArray['port'] : null;
302. $this->properties['scheme'] = isset( $urlArray['scheme'] ) ? $urlArray['scheme'] : null;
303. $this->properties['fragment'] = isset( $urlArray['fragment'] ) ? $urlArray['fragment'] : null;
304. $this->properties['path'] = isset( $urlArray['path'] ) ? explode ( '/', trim ( $urlArray['path'], '/' ) ) : array();
306. $this->properties['basedir'] = array();
307. $this->properties['script'] = array();
308. $this->properties['params'] = array();
309. $this->properties['uparams'] = array();
311. if ( isset( $urlArray['query'] ) )
312. {
313. $this->properties['query'] = ezcUrlTools :: parseQueryString ( $urlArray['query'] );
314. }
315. else
316. {
317. $this->properties['query'] = array();
318. }
319. }
321. /**
322. * Applies the URL configuration $configuration to the current url.
323. *
324. * It fills the arrays $basedir, $script, $params and $uparams with values
325. * from $path.
326. *
327. * It also sets the property configuration to the value of $configuration.
328. *
329. * @param ezcUrlConfiguration $configuration An URL configuration used in parsing
330. */
331. public function applyConfiguration ( ezcUrlConfiguration $configuration )
332. {
333. $this->configuration = $configuration;
334. $this->basedir = $this->parsePathElement( $configuration->basedir, 0 );
335. $this->script = $this->parsePathElement( $configuration->script, count ( $this->basedir ) );
336. $this->params = $this-> parseOrderedParameters ( $configuration->orderedParameters, count ( $this->basedir ) + count ( $this->script ) );
337. $this->uparams = $this-> parseUnorderedParameters ( $configuration->unorderedParameters, count ( $this->basedir ) + count ( $this->script ) + count ( $this->params ) );
338. }
340. /**
341. * Parses $path based on the configuration $config, starting from $index.
342. *
343. * Returns the first few elements of $this->path matching $config,
344. * starting from $index.
345. *
346. * @param string $config A string which will be matched against the path part of the URL
347. * @param int $index The index in the URL path part from where to start the matching of $config
348. * @return array(string=>mixed)
349. */
350. private function parsePathElement( $config, $index )
351. {
352. $config = trim ( $config, '/' );
353. $paramParts = explode ( '/', $config );
354. $pathElement = array();
355. foreach ( $paramParts as $part )
356. {
357. if ( isset( $this->path[$index] ) && $part == $this->path[$index] )
358. {
359. $pathElement[] = $part;
360. }
361. $index++;
362. }
363. return $pathElement;
364. }
366. /**
367. * Returns ordered parameters from the $path array.
368. *
369. * @param array(string) $config An array of ordered parameters names, from the URL configuration used in parsing
370. * @param int $index The index in the URL path part from where to start the matching of $config
371. * @return array(string=>mixed)
372. */
373. public function parseOrderedParameters ( $config, $index )
374. {
375. $result = array();
376. $pathCount = count ( $this->path );
377. for ( $i = 0; $i < count ( $config ); $i++ )
378. {
379. if ( isset( $this->path[$index + $i] ) )
380. {
381. $result[] = $this->path[$index + $i];
382. }
383. else
384. {
385. $result[] = null;
386. }
387. }
388. return $result;
389. }
391. /**
392. * Returns unordered parameters from the $path array.
393. *
394. * The format of the returned array is:
395. * <code>
396. * array( param_name1 => array( 0 => array( value1, value2, ... ),
397. * 1 => array( value1, value2, ... ) ),
398. * param_name2 = array( 0 => array( value1, value2, ... ),
399. * 1 => array( value1, value2, ... ) ), ... )
400. * </code>
401. * where 0, 1, etc are numbers meaning the nth encounter of each param_name
402. * in the url.
403. *
404. * For example, if the URL is 'http://www.example.com/(param1)/a/(param2)/x/(param2)/y/z'
405. * then the result of this function will be:
406. * <code>
407. * array( 'param1' => array( 0 => array( 'a' ) ),
408. * 'param2' => array( 0 => array( 'x' ),
409. * 1 => array( 'y', 'z' ) ) );
410. * </code>
411. *
412. * For the URL 'http://www.example.com/(param1)/x/(param1)/y/z', these
413. * methods can be employed to get the values of param1:
414. * <code>
415. * $urlCfg = new ezcUrlConfiguration();
416. *
417. * // single parameter value
418. * $urlCfg->addUnorderedParameter( 'param1' ); // type is SINGLE_ARGUMENT by default
419. * $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
420. * $param1 = $url->getParam( 'param1' ); // will return "y"
421. *
422. * // multiple parameter values
423. * $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
424. * $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
425. * $param1 = $url->getParam( 'param1' ); // will return array( "y", "z" )
426. *
427. * // multiple parameter values with aggregation
428. * $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
429. * $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
430. * $param1 = $url->getParam( 'param1' ); // will return array( array( "x" ), array( "y", "z" ) )
431. * </code>
432. *
433. * Note: in the examples above, if the URL does not contain the string 'param1',
434. * then all the unordered parameters from and including param1 will be null,
435. * so $url->getParam( 'param1' ) will return null (see issue #12825).
436. *
437. * @param array(string) $config An array of unordered parameters names, from the URL configuration used in parsing
438. * @param int $index The index in the URL path part from where to start the matching of $config
439. * @return array(string=>mixed)
440. */
441. public function parseUnorderedParameters ( $config, $index )
442. {
443. $result = array();
445. // holds how many times a parameter name is encountered in the URL.
446. // for example, for '/(param1)/a/(param2)/x/(param2)/y',
447. // $encounters = array( 'param1' => 1, 'param2' => 2 );
448. $encounters = array();
450. $urlCfg = $this->configuration;
451. $pathCount = count ( $this->path );
452. if ( $pathCount == 0 || ( $pathCount == 1 && trim ( $this->path[0] ) === "" ) )
453. {
454. // special case: a bug? in parse_url() which makes $this->path
455. // be array( "" ) if the provided URL is null or empty
456. return $result;
457. }
458. for ( $i = $index; $i < $pathCount; $i++ )
459. {
460. $param = $this->path[$i];
461. if ( strlen ( $param ) > 1 &&
462. $param{0} == $urlCfg->unorderedDelimiters[0] )
463. {
464. $param = trim ( trim ( $param, $urlCfg->unorderedDelimiters[0] ), $urlCfg->unorderedDelimiters[1] );
465. if ( isset( $encounters[$param] ) )
466. {
467. $encounters[$param]++;
468. }
469. else
470. {
471. $encounters[$param] = 0;
472. }
473. $result[$param][$encounters[$param]] = array();
474. $j = 1;
475. while ( ( $i + $j ) < $pathCount && $this->path[$i + $j]{0} != $urlCfg->unorderedDelimiters[0] )
476. {
477. $result[$param][$encounters[$param]][] = trim ( trim ( $this->path[$i + $j], $urlCfg->unorderedDelimiters[0] ), $urlCfg->unorderedDelimiters[1] );
478. $j++;
479. }
480. }
481. }
482. return $result;
483. }
485. /**
486. * Returns this URL as a string.
487. *
488. * The query part of the URL is build with http_build_query() which
489. * encodes the query in a similar way to urlencode().
490. *
491. * If $includeScriptName is true, then the script name (eg. 'index.php')
492. * will be included in the result. By default the script name is hidden (to
493. * ensure backwards compatibility).
494. *
495. * @apichange The default value for $includeScriptName might be changed to
496. * true in future versions
497. *
498. * @param bool $includeScriptName
499. * @return string
500. */
501. public function buildUrl ( $includeScriptName = false )
502. {
503. $url = '';
505. if ( $this->scheme )
506. {
507. $url .= $this->scheme . '://';
508. }
510. if ( $this->host )
511. {
512. if ( $this->user )
513. {
514. $url .= $this->user;
515. if ( $this->pass )
516. {
517. $url .= ':' . $this->pass;
518. }
519. $url .= '@';
520. }
522. $url .= $this->host;
523. if ( $this->port )
524. {
525. $url .= ':' . $this->port;
526. }
527. }
529. if ( $this->configuration != null )
530. {
531. if ( $this->basedir )
532. {
533. if ( !( count ( $this->basedir ) == 0 || trim ( $this->basedir[0] ) === "" ) )
534. {
535. $url .= '/' . implode ( '/', $this->basedir );
536. }
537. }
539. if ( $includeScriptName && $this->script )
540. {
541. if ( !( count ( $this->script ) == 0 || trim ( $this->script[0] ) === "" ) )
542. {
543. $url .= '/' . implode ( '/', $this->script );
544. }
545. }
547. if ( $this->params && count ( $this->params ) != 0 )
548. {
549. $url .= '/' . implode ( '/', $this->params );
550. }
552. if ( $this->uparams && count ( $this->uparams ) != 0 )
553. {
554. foreach ( $this->properties['uparams'] as $key => $encounters )
555. {
556. foreach ( $encounters as $encounter => $values )
557. {
558. $url .= '/(' . $key . ')/' . implode ( '/', $values );
559. }
560. }
561. }
562. }
563. else
564. {
565. if ( $this->path )
566. {
567. $url .= '/' . implode ( '/', $this->path );
568. }
569. }
571. if ( $this->query )
572. {
573. $url .= '?' . http_build_query ( $this->query );
574. }
576. if ( $this->fragment )
577. {
578. $url .= '#' . $this->fragment;
579. }
581. return $url;
582. }
584. /**
585. * Returns true if this URL is relative and false if the URL is absolute.
586. *
587. * @return bool
588. */
589. public function isRelative ()
590. {
591. if ( $this->host === null || $this->host == '' )
592. {
593. return true;
594. }
595. return false;
596. }
598. /**
599. * Returns the value of the specified parameter from the URL based on the
600. * active URL configuration.
601. *
602. * Ordered parameters must appear before unordered parameters in the parsed
603. * URL, in the same number and order as they are defined in the configuration.
604. *
605. * Unordered parameter examples:
606. * <code>
607. * $urlCfg = new ezcUrlConfiguration();
608. *
609. * // single parameter value
610. * $urlCfg->addUnorderedParameter( 'param1' ); // type is SINGLE_ARGUMENT by default
611. * $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
612. * $param1 = $url->getParam( 'param1' ); // will return "y"
613. *
614. * // multiple parameter values
615. * $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
616. * $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
617. * $param1 = $url->getParam( 'param1' ); // will return array( "y", "z" )
618. *
619. * // multiple parameter values with aggregation
620. * $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
621. * $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
622. * $param1 = $url->getParam( 'param1' ); // will return array( array( "x" ), array( "y", "z" ) )
623. * </code>
624. *
625. * Ordered parameter examples:
626. * <code>
627. * $urlCfg = new ezcUrlConfiguration();
628. *
629. * $urlCfg->addOrderedParameter( 'param1' );
630. * $urlCfg->addOrderedParameter( 'param2' );
631. * $url = new ezcUrl( 'http://www.example.com/x/y', $urlCfg );
632. * $param1 = $url->getParam( 'param1' ); // will return "x"
633. * $param2 = $url->getParam( 'param2' ); // will return "y"
634. * </code>
635. *
636. * @throws ezcUrlNoConfigurationException
637. * if an URL configuration is not defined
638. * @throws ezcUrlInvalidParameterException
639. * if the specified parameter is not defined in the URL configuration
640. * @param string $name The name of the parameter for which to return the value
641. * @return mixed
642. */
643. public function getParam ( $name )
644. {
645. $urlCfg = $this->configuration;
646. if ( $urlCfg != null )
647. {
648. if ( !( isset( $urlCfg->orderedParameters[$name] ) ||
649. isset( $urlCfg->unorderedParameters[$name] ) ) )
650. {
651. throw new ezcUrlInvalidParameterException ( $name );
652. }
654. $params = $this->params;
655. $uparams = $this->uparams;
656. if ( isset( $urlCfg->orderedParameters[$name] ) &&
657. isset( $params[$urlCfg->orderedParameters[$name]] ) )
658. {
659. return $params[$urlCfg->orderedParameters[$name]];
660. }
662. if ( isset( $urlCfg->unorderedParameters[$name] ) &&
663. isset( $uparams[$name][0] ) )
664. {
665. if ( $urlCfg->unorderedParameters[$name] === ezcUrlConfiguration ::SINGLE_ARGUMENT )
666. {
667. if ( count ( $uparams[$name][0] ) > 0 )
668. {
669. return $uparams[$name][ count ( $uparams[$name] ) - 1][0];
670. }
671. else
672. {
673. return null;
674. }
675. }
676. else
677. {
678. if ( $urlCfg->unorderedParameters[$name] === ezcUrlConfiguration ::AGGREGATE_ARGUMENTS )
679. {
680. $result = $uparams[$name];
681. return $result;
682. }
683. else
684. {
685. return $uparams[$name][ count ( $uparams[$name] ) - 1];
686. }
687. }
688. }
689. return null;
690. }
691. else
692. {
693. throw new ezcUrlNoConfigurationException ( $name );
694. }
695. }
697. /**
698. * Sets the specified parameter in the URL based on the URL configuration.
699. *
700. * For ordered parameters, the value cannot be an array, otherwise an
701. * ezcBaseValueException will be thrown.
702. *
703. * For unordered parameters, the value can be one of:
704. * - string
705. * - array(string)
706. * - array(array(string))
707. *
708. * Any of these values can be assigned to an unordered parameter, whatever the
709. * parameter type (SINGLE_ARGUMENT, MULTIPLE_ARGUMENTS, AGGREGATE_ARGUMENTS).
710. *
711. * If there are ordered and unordered parameters with the same name, only the
712. * ordered parameter value will be set.
713. *
714. * Examples:
715. * <code>
716. * $urlCfg = new ezcUrlConfiguration();
717. * $urlCfg->addUnorderedParameter( 'param1' );
718. *
719. * $url = new ezcUrl( 'http://www.example.com' );
720. *
721. * $url->setParam( 'param1', 'x' );
722. * echo $url->buildUrl(); // will output http://www.example.com/(param1)/x
723. *
724. * $url->setParam( 'param1', array( 'x', 'y' ) );
725. * echo $url->buildUrl(); // will output http://www.example.com/(param1)/x/y
726. *
727. * $url->setParam( 'param1', array( array( 'x' ), array( 'y', 'z' ) ) );
728. * echo $url->buildUrl(); // will output http://www.example.com/(param1)/x/(param1)/y/z
729. * </code>
730. *
731. * @throws ezcBaseValueException
732. * if trying to assign an array value to an ordered parameter
733. * @throws ezcUrlNoConfigurationException
734. * if an URL configuration is not defined
735. * @throws ezcUrlInvalidParameterException
736. * if the specified parameter is not defined in the URL configuration
737. * @param string $name The name of the parameter to set
738. * @param string|array(string=>mixed)$value The new value of the parameter
739. */
740. public function setParam ( $name, $value )
741. {
742. $urlCfg = $this->configuration;
743. if ( $urlCfg != null )
744. {
745. if ( !( isset( $urlCfg->orderedParameters[$name] ) ||
746. isset( $urlCfg->unorderedParameters[$name] ) ) )
747. {
748. throw new ezcUrlInvalidParameterException ( $name );
749. }
751. if ( isset( $urlCfg->orderedParameters[$name] ) )
752. {
753. if ( ! is_array ( $value ) )
754. {
755. $this->properties['params'][$urlCfg->orderedParameters[$name]] = $value;
756. }
757. else
758. {
759. throw new ezcBaseValueException ( $name, $value, 'string' );
760. }
761. return;
762. }
764. if ( isset( $urlCfg->unorderedParameters[$name] ) )
765. {
766. if ( !isset( $this->properties['uparams'][$name] ) )
767. {
768. $this->properties['uparams'][$name] = array();
769. }
771. if ( is_array ( $value ) )
772. {
773. $multiple = false;
774. foreach ( $value as $part )
775. {
776. if ( is_array ( $part ) )
777. {
778. $this->properties['uparams'][$name] = $value;
779. $multiple = true;
780. break;
781. }
782. }
783. if ( !$multiple )
784. {
785. $this->properties['uparams'][$name][ count ( $this->properties['uparams'][$name] ) - 1] = $value;
786. }
787. }
788. else
789. {
790. $this->properties['uparams'][$name][ count ( $this->properties['uparams'][$name] ) - 1] = array( $value );
791. }
792. }
793. return;
794. }
795. else
796. {
797. throw new ezcUrlNoConfigurationException ( $name );
798. }
799. }
801. /**
802. * Returns the unordered parameters from the URL as a flat array.
803. *
804. * It takes into account the basedir, script and ordered parameters.
805. *
806. * It can be used for URLs which don't have delimiters for the unordered
807. * parameters.
808. *
809. * Example:
810. * <code>
811. * $urlCfg = new ezcUrlConfiguration();
812. * $urlCfg->basedir = '/mydir/shop';
813. * $urlCfg->script = 'index.php';
814. * $urlCfg->addOrderedParameter( 'module' );
815. *
816. * $url = new ezcUrl( 'http://www.example.com/mydir/shop/index.php/order/Software/PHP/Version/5.2/Extension/XDebug/Extension/openssl', $urlCfg );
817. *
818. * $params = $url->getParams(); // will be array( 'Software', 'PHP', 'Version', '5.2', 'Extension', 'XDebug', 'Extension', 'openssl' )
819. * </code>
820. *
821. * @return array(string)
822. */
823. public function getParams ()
824. {
825. return array_slice ( $this->path, count ( $this->basedir ) + count ( $this->script ) + count ( $this->params ) );
826. }
828. /**
829. * Returns the query elements as an associative array.
830. *
831. * Example:
832. * for 'http://www.example.com/mydir/shop?content=view&products=10'
833. * returns array( 'content' => 'view', 'products' => '10' )
834. *
835. * @return array(string=>mixed)
836. */
837. public function getQuery ()
838. {
839. return $this->query;
840. }
842. /**
843. * Set the query elements using the associative array provided.
844. *
845. * Example:
846. * for 'http://www.example.com/mydir/shop'
847. * and $query = array( 'content' => 'view', 'products' => '10' )
848. * then 'http://www.example.com/mydir/shop?content=view&products=10'
849. *
850. * @param array(string=>mixed) $query The new value of the query part
851. */
852. public function setQuery ( $query )
853. {
854. $this->query = $query;
855. }
856. }
857. ?>

Documentation generated by phpDocumentor 1.4.3