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.  */
  27.  
  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. {
  130.     /**
  131.      * Flag for specifying single arguments for unordered parameters.
  132.      */
  133.     const SINGLE_ARGUMENT 1;
  134.  
  135.     /**
  136.      * Flag for specifying multiple arguments for unordered parameters.
  137.      */
  138.     const MULTIPLE_ARGUMENTS 2;
  139.  
  140.     /**
  141.      * Flag for specifying aggregation for unordered parameter values if the
  142.      * parameter name appears more than once in the URL.
  143.      *
  144.      * For example, if the URL is 'http://www.example.com/(param1)/x/(param1)/y/z',
  145.      * then all values will be considered for the parameter param1. So
  146.      * $url->getParam( 'param1' ) will return array( array( "x" ), array( "y", "z" ) ),
  147.      * if $url is an ezcUrl object created from the above URL.
  148.      */
  149.     const AGGREGATE_ARGUMENTS 4;
  150.  
  151.     /**
  152.      * Holds the properties of this class.
  153.      *
  154.      * @var array(string=>mixed) 
  155.      */
  156.     private $properties array();
  157.  
  158.     /**
  159.      * Stores the instance of this class.
  160.      *
  161.      * @var ezcUrlConfiguration 
  162.      */
  163.     private static $instance null;
  164.  
  165.     /**
  166.      * Constructs a new ezcUrlConfiguration object.
  167.      *
  168.      * The properties of the object get default values, which can be changed by
  169.      * setting the properties directly, like:
  170.      * <code>
  171.      *   $urlCfg = new ezcUrlConfiguration();
  172.      *   $urlCfg->basedir = 'mydir';
  173.      *   $urlCfg->script = 'index.php';
  174.      * </code>
  175.      */
  176.     public function __construct()
  177.     {
  178.         $this->basedir null;
  179.         $this->script null;
  180.         $this->unorderedDelimiters array'('')' );
  181.         $this->orderedParameters array();
  182.         $this->unorderedParameters array();
  183.     }
  184.  
  185.     /**
  186.      * Returns the instance of the class.
  187.      *
  188.      * @return ezcUrlConfiguration 
  189.      */
  190.     public static function getInstance()
  191.     {
  192.         if is_nullself::$instance ) )
  193.         {
  194.             self::$instance new ezcUrlConfiguration();
  195.             ezcBaseInit::fetchConfig'ezcUrlConfiguration'self::$instance );
  196.         }
  197.         return self::$instance;
  198.     }
  199.  
  200.     /**
  201.      * Sets the property $name to $value.
  202.      *
  203.      * @throws ezcBasePropertyNotFoundException
  204.      *          if the property does not exist.
  205.      * @param string $name The name of the property to set
  206.      * @param mixed $value The new value of the property
  207.      * @ignore
  208.      */
  209.     public function __set$name$value )
  210.     {
  211.         switch $name )
  212.         {
  213.             case 'basedir':
  214.             case 'script':
  215.             case 'unorderedDelimiters':
  216.             case 'orderedParameters':
  217.             case 'unorderedParameters':
  218.                 $this->properties[$name$value;
  219.                 break;
  220.  
  221.             default:
  222.                 throw new ezcBasePropertyNotFoundException$name );
  223.         }
  224.     }
  225.  
  226.     /**
  227.      * Returns the property $name.
  228.      *
  229.      * @throws ezcBasePropertyNotFoundException
  230.      *          if the property does not exist.
  231.      * @param string $name The name of the property for which to return the value
  232.      * @return mixed 
  233.      * @ignore
  234.      */
  235.     public function __get$name )
  236.     {
  237.         switch $name )
  238.         {
  239.             case 'basedir':
  240.             case 'script':
  241.             case 'unorderedDelimiters':
  242.             case 'orderedParameters':
  243.             case 'unorderedParameters':
  244.                 return $this->properties[$name];
  245.  
  246.             default:
  247.                 throw new ezcBasePropertyNotFoundException$name );
  248.         }
  249.     }
  250.  
  251.     /**
  252.      * Returns true if the property $name is set, otherwise false.
  253.      *
  254.      * @param string $name The name of the property to test if it is set
  255.      * @return bool 
  256.      * @ignore
  257.      */
  258.     public function __isset$name )
  259.     {
  260.         switch $name )
  261.         {
  262.             case 'basedir':
  263.             case 'script':
  264.             case 'unorderedDelimiters':
  265.             case 'orderedParameters':
  266.             case 'unorderedParameters':
  267.                 return isset$this->properties[$name);
  268.  
  269.             default:
  270.                 return false;
  271.         }
  272.     }
  273.  
  274.     /**
  275.      * Adds an ordered parameter to the URL configuration.
  276.      *
  277.      * Ordered parameters must be added before unordered parameters, and
  278.      * they must appear in the parsed URL in the same number and order
  279.      * as they are defined in the configuration.
  280.      *
  281.      * @param string $name The name of the ordered parameter to add to the configuration
  282.      */
  283.     public function addOrderedParameter$name )
  284.     {
  285.         $this->properties['orderedParameters'][$namecount$this->properties['orderedParameters');
  286.     }
  287.  
  288.     /**
  289.      * Removes an ordered parameter from the URL configuration.
  290.      *
  291.      * @param string $name The name of the ordered parameter to remove from the configuration
  292.      */
  293.     public function removeOrderedParameter$name )
  294.     {
  295.         if isset$this->properties['orderedParameters'][$name) )
  296.         {
  297.             unset$this->properties['orderedParameters'][$name);
  298.         }
  299.     }
  300.  
  301.     /**
  302.      * Adds an unordered parameter to the URL configuration.
  303.      *
  304.      * The possible values for the $type parameter are:
  305.      *  - {@link ezcUrlConfiguration::SINGLE_ARGUMENT} (default): the getParam()
  306.      *    method in ezcUrl will return a string containing the value of the
  307.      *    parameter $name
  308.      *  - {@link ezcUrlConfiguration::MULTIPLE_ARGUMENTS}: the getParam() method
  309.      *    will return an array containing the last encountered values of the
  310.      *    parameter $name
  311.      *  - {@link ezcUrlConfiguration::AGGREGATE_ARGUMENTS}: the getParam() method
  312.      *    will return an array with all encountered values for the parameter $name
  313.      *
  314.      * Examples:
  315.      * <code>
  316.      * $urlCfg = new ezcUrlConfiguration();
  317.      *
  318.      * // single parameter value
  319.      * $urlCfg->addUnorderedParameter( 'param1' ); // type is SINGLE_ARGUMENT by default
  320.      * $url = new ezcUrl( 'http://www.example.com/(param1)/x', $urlCfg );
  321.      * $param1 = $url->getParam( 'param1' ); // will return "x"
  322.      *
  323.      * // multiple parameter values
  324.      * $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::MULTIPLE_ARGUMENTS );
  325.      * $url = new ezcUrl( 'http://www.example.com/(param1)/x/y', $urlCfg );
  326.      * $param1 = $url->getParam( 'param1' ); // will return array( "x", "y" )
  327.      *
  328.      * // multiple parameter values with aggregation
  329.      * $urlCfg->addUnorderedParameter( 'param1', ezcUrlConfiguration::AGGREGATE_ARGUMENTS );
  330.      * $url = new ezcUrl( 'http://www.example.com/(param1)/x/(param1)/y/z', $urlCfg );
  331.      * $param1 = $url->getParam( 'param1' ); // will return array( array( "x" ), array( "y", "z" ) )
  332.      * </code>
  333.      *
  334.      * Ordered parameters must be added before unordered parameters, and
  335.      * they must appear in the parsed URL in the same number and order
  336.      * as they are defined in the configuration.
  337.      *
  338.      * @param string $name The name of the unordered parameter to add to the configuration
  339.      * @param int $type The type of the unordered parameter
  340.      */
  341.     public function addUnorderedParameter$name$type null )
  342.     {
  343.         if $type == null )
  344.         {
  345.             $type self::SINGLE_ARGUMENT;
  346.         }
  347.         $this->properties['unorderedParameters'][$name$type;
  348.     }
  349.  
  350.     /**
  351.      * Removes an unordered parameter from the URL configuration.
  352.      *
  353.      * @param string $name The name of the unordered parameter to remove from the configuration
  354.      */
  355.     public function removeUnorderedParameter$name )
  356.     {
  357.         if isset$this->properties['unorderedParameters'][$name) )
  358.         {
  359.             unset$this->properties['unorderedParameters'][$name);
  360.         }
  361.     }
  362. }
  363. ?>
Documentation generated by phpDocumentor 1.4.3