Class Controller_Routing_Builder

Description
Description | Vars (details) | Methods (details)

Controller_Routing_Builder is used as a convenient way to add routes to the system.

Building Routes

There are three primary methods the builder exposes for adding routes: match, regex, and root. Most routes can be added using the match method. As a simple example, take the default routes (assuming $route is an instance of Controller_Routing_Builder):

  1.    $route->match("/:controller/:action/:id"); // matches URLs like "/user/edit/5"
  2.    $route->match("/:controller/:action");     // matches URLs without an id component
  3.    $route->match("/:controller", array('action'=>'index'));
  4.                                               // uses 'index' for URLs without an action value

The regex method allows an entire regular expression to be evaluated against the URL:

  1.    // sends any URL with the words "i don't know" to the slime action of
  2.    // the error controller:
  3.  
  4.    $route->regex("/\\bi don't know\\b/i",
  5.      array('controller'=>'error', 'action'=>'slime'));

Lastly, root allows you to connect a route to the root URL (/):

  1.    $route->root(array('controller'=>'home'));

Parameters

There are two ways to set parameters as part of a route. With the match method, any parameter name may be prefixed with a colon (:) within the URL to indicate it is to be pulled from that location:

  1.    $route->match('/password_reset/:token', array('controller'=>'session',
  2.      'action'=>'password_reset'));
  3.  
  4.    // the URL "/password_reset/68656c6c6f20776f726c64" would produce the parameters:
  5.    // array('controller'=>'session', 'action'=>'password_reset', 'token'=>'68656c6c6f20776f726c64')

Additionally, all of the builder methods accept an array of default parameter values as the first argument following any path matching information:

  1.    $route->match('/article/:id', array('controller'=>'articles',
  2.      'action'=>'show', 'category'=>'all'));
  3.  
  4.    // the URL "/article/20110824.3" would produce the parameters:
  5.    // array('controller'=>'articles', 'action'=>'show', 'id'=>'20110824.3', 'category'=>'all')

Constraints

All of the builder methods also accept a second array argument which can be used to impose further matching conditions. One type of matching constraint is to limit the HTTP method used to access the route:

  1.    $route->match('/articles', array('controller'=>'articles',
  2.      'action'=>'create'), array('method'=>'put'));
  3.    // PUT /articles would match the route
  4.    // GET /articles would not
  5.  
  6.    $route->match('/article/:id', array('controller'=>'articles',
  7.      'action'=>'edit'), array('method'=>array('get', 'post')));
  8.    // GET /article/497 would match the route
  9.    // POST /article/497 would match the route
  10.    // PUT /article/497 would not match

The second type of constraint requires a string or regular expression to match a parameter value (the parameter name is provided as the key):

  1.   $route->match('/article/:id', array('controller'=>'articles',
  2.     'action'=>'show'), array('method'=>'get', id=>"/\\A[H|S]R\\d+\\z/"));
  3.   // GET /article/HR1842 would match the route
  4.   // GET /article/1842 would not
  5.   // POST /article/HR1842 would also not match
  6.  
  7.   $route->match('/article/:id', array('controller'=>'articles',
  8.     'action'=>'show'), array('format'=>'html'));
  9.   // GET /article/1842?format=html would match
  10.   // GET /article/1842?format=pdf would not match
  11.   // GET /article/1842 would not match

Located in /controller/lib/Controller/Routing/Builder.php (line 97) 


	
			






	
	

		
Variable Summary

		

			Description |
						Vars (details)
							| 
									Methods (details)
							
								

		

			

																								

					 
					mixed
					$routing
				

											

		

	


	
	

		
Method Summary

		

			Description |
																		Vars (details)
				 
				|
						Methods (details)
		

		
			
			

																																																

					 
											Controller_Routing_Builder
										__construct
											(Controller_Routing $routing)
									

																

					 
											void
										match
											(string $path, [array $defaults = null], [array $constraints = null])
									

																

					 
											void
										regex
											(string $regex, [array $defaults = null], [array $constraints = null])
									

																

					 
											void
										root
											([array $defaults = null], [array $constraints = null])
									

											

		

	
		

	
	

		
Variables

		

			Description |
										Vars (details)
						
			
										| 
									Methods (details)
							
					

		

			




	

		
		
			mixed
			$routing
						(line 99)
		
	


	
	
    
				
  • access: protected
    • 
			

	
	
		
		



						
		

	

	
	
	

		
Methods

		

			Description |
															Vars (details)
														Methods (details)
						
		

		

			



	
	

		
		Constructor __construct (line 106)
	
 
	
	

Constructor

	
    
				
  • access: public
    • 
			

	
	

		Controller_Routing_Builder
		
			__construct
		
					(Controller_Routing $routing)
			

	
			
		
			
	




	
	

		
		match (line 120)
	
 
	
	

The match method adds a route based on matching a URL string with  optional embedded parameters.


See the class documentation for more details and examples.

	
    
				
  • access: public
    • 
			

	
	

		void
		
			match
		
					(string $path, [array $defaults = null], [array $constraints = null])
			

	
			
    
					
  • 
				string
				$path: The URL string to match			
    • 
					
  • 
				array
				$defaults: Any default parameter values to include as part of the route			
    • 
					
  • 
				array
				$constraints: Any constraints to include as part of the route			
    • 
				

		
			
	




	
	

		
		regex (line 159)
	
 
	
	

The regex method adds a route based on regular expression to be  evaluated against the complete URL.


See the class documentation for more details and examples.

	
    
				
  • access: public
    • 
			

	
	

		void
		
			regex
		
					(string $regex, [array $defaults = null], [array $constraints = null])
			

	
			
    
					
  • 
				string
				$regex: The regular expression to use			
    • 
					
  • 
				array
				$defaults: Any default parameter values to include as part of the route			
    • 
					
  • 
				array
				$constraints: Any constraints to include as part of the route			
    • 
				

		
			
	




	
	

		
		root (line 178)
	
 
	
	

The root method adds a route that matches the site root URL.


See the class documentation for more details and examples.

	
    
				
  • access: public
    • 
			

	
	

		void
		
			root
		
					([array $defaults = null], [array $constraints = null])
			

	
			
    
					
  • 
				array
				$defaults: Any default parameter values to include as part of the route			
    • 
					
  • 
				array
				$constraints: Any constraints to include as part of the route			
    • 
				

		
			
	

						
		

	


	
	

		Documentation generated on Wed, 25 Apr 2012 09:46:41 -0700 by phpDocumentor 1.4.3