<commit_before><sect1 id="zend.controller.rewriterouter.introduction">
    <title>Introduction</title>
	<para>
		Zend_Controller_RewriteRouter is a new version of the framework router. Routing is the process of taking a URI
		endpoint and decomposing it to determine which controller and action of that controller, should receive the
		request. This definition of controller, action and optional parameters is packaged into a value object called
		Zend_Controller_Dispatcher_Token which is then processed by Zend_Controller_Dispatcher. Routing occurs only once:
		when the request is initially received and before the first controller is dispatched.
	</para>
	<para>
		Zend_Controller_RewriteRouter is designed to allow for mod_rewrite like functionality using pure php
		structures. It is very loosely based on Ruby on Rails routing and does not require any prior knowledge of
		webserver URL rewriting. It is designed to work with a single mod_rewrite rule (one of):
	</para>
	<programlisting role="php"><![CDATA[
RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css)$ index.php]]></programlisting>
	<programlisting role="php"><![CDATA[
RewriteEngine on
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteCond %{SCRIPT_FILENAME} !-d
RewriteRule ^(.*)$ index.php/$1	]]></programlisting>
</sect1>

<sect1 id="zend.controller.rewriterouter.usage">
	<title>Using a router</title>

	<para>
		To properly use the RewriteRouter you have to instantiate it, add some user defined routes and inject it into the
		controller. The following code illustrates the procedure:
	</para>

	<programlisting role="php"><![CDATA[
/* -- create a router -- */

$router = new Zend_Controller_RewriteRouter();
$router->addRoute('user', 'user/:username', array('controller' => 'user', 'action' => 'info'));

/* -- set it in a controller -- */

$ctrl = Zend_Controller_Front::getInstance();
$ctrl->setRouter($router);]]></programlisting>
</sect1>

<sect1 id="zend.controller.rewriterouter.basic">
	<title>Basic Routes</title>

	<para>
		The heart of the RewriteRouter is the definition of user defined routes. Routes are created by calling the addRoute method of
		RewriteRouter:
	</para>

	<programlisting role="php"><![CDATA[
$router->addRoute('user', 'user/:username');]]></programlisting>

	<para>
		The first parameter is the name of the route. It is redundant at the moment of writing but will be used in the future in
		a URL view helper to allow for easy URL generation in your views. Should you need to make use of a previously
		configured named route, you can retrieve it with the getRoute method of the RewriteRouter.
	</para>

	<para>
		The second parameter is a route that will be matched to a URL - for example, the above route will match
		<code>http://example.com/user/martel</code>. The colon in a route marks a URL variable which will be accessible
		through a Zend_Controller_Action::_getParam method. In our example a parameter named username will be set to a value of
		'martel'.
	</para>

	<note>
		Routes are matched in reverse order so make sure your most generic routes are defined first.
	</note>

	<note>
		For now the current implementation allows for use of any characters except a slash (/) as a variable identifier but
		it is strongly recommended that one uses only php variable friendly characters. In future the implementation will probably be
		altered and this may introduce bugs to your code.
	</note>

	<para>
		There are two special variables which can be used in your routes - 'controller' and 'action'. These special
		variables will be used to find a controller and/or an action chosen in the URL.
	</para>

	<programlisting role="php"><![CDATA[
$router->addRoute('user', ':controller/:action');]]></programlisting>

	<para>
		If you point your browser to 'http://example.com/news/latest' with this route defined the
		Zend_Controller_Dispatcher will invoke the latestAction of your NewsController.
	</para>

</sect1>

<sect1 id="zend.controller.rewriterouter.variable-defaults">
	<title>Variable defaults</title>

	<para>
		Every variable in the route can have a default. To provide it you have to add a third parameter to the addRoute
		method. This third parameter is an array with keys as variable names and values as desired defaults.
	</para>

	<programlisting role="php"><![CDATA[
$router->addRoute('archive', 'archive/:year', array('year' => 2006));]]></programlisting>
	<para>
		What may not be clearly visible is that the above route will match URLs like 'http://example.com/archive/2005' and
		'http://example.com/archive'. In the latter case the variable year will have a value of 2006.
	</para>

	<para>
		In the above example we haven't set a controller so it will always result in a noRoute action of an
		IndexController. To make it usable you have to provide a valid controller and a valid action as a default:
	</para>

	<programlisting role="php"><![CDATA[
$router->addRoute('archive', 'archive/:year', array('year' => 2006, 'controller' => 'archive', 'action' => 'show'));]]></programlisting>

</sect1>

<sect1 id="zend.controller.rewriterouter.variable-requirements">
	<title>Variable requirements</title>

	<para>
		One can add a fourth parameter where variable requirements can be set. These are defined as regular
		expressions:
	</para>

	<programlisting role="php"><![CDATA[
$router->addRoute('archive', 'archive/:year', array('year' => 2006), array('year' => '\d+'));]]></programlisting>

	<note>
		Unlike Ruby on Rails, ZF RewriteRouter will match a route and use a default when a fourth parameter variable requirement is not met. So the
		URL of 'http://example.com/archive/test' will match the above route and set the year to 2006. This functionality
		may be altered in the future as it is being discussed at the moment of writing of this documentation.
	</note>

</sect1>

<sect1 id="zend.controller.rewriterouter.rewritebase">
	<title>Base URL and subdirectories</title>

	<para>
		Unlike the original Router, RewriteRouter can be used in subdirectories - it automatically detects your base URL and
		sets it accordingly. For example: if you keep your <code>index.php</code> in a webserver subdirectory named
		<code>/projects/myapp/index.php</code> rewrite base (base URL) will be set to <code>/projects/myapp</code>. This string will then be 
		stripped from the beginning of the path before calculating any route matches. This frees one from the necessity of prepending it to
		any of your routes. The route of <code>'user/:username'</code> will match URIs like
		<code>http://localhost/projects/myapp/user/martel</code> and <code>http://example.com/user/martel</code>.
	</para>

	<note>
		Automatic rewrite base is case sensitive, so make sure your URL will match a subdirectory name in a filesystem
		(even on Windows machines). If it doesn't you will get to noRoute action.
	</note>

	<para>
		Should rewrite base be detected incorrectly you can override it with your own base path with the help of the
		setRewriteBase method of the RewriteRouter class:
	</para>

	<programlisting role="php"><![CDATA[
$router->setRewriteBase('/projects/myapp');]]></programlisting>

	<note>
		This step won't be necessary in most cases and is strongly discouraged as it introduces another configuration variable
		which would have to be altered when one moves code to another directory configuration.
	</note>

</sect1>

<sect1 id="zend.controller.rewriterouter.default-routes">
	<title>Default routes</title>

	<para>
		Zend_Controller_RewriteRouter is preconfigured with two default routes. The first handles  your root URL and is
		mapped to indexAction of IndexController: so you have to provide them as outlined in the  Getting Started chapter (paragraph
		2.2.5). The second default route is included to provide compatibility with the first version of the router. It will match URIs in
		the shape of <code>'controller/action'</code>.
	</para>

	<para>
		Default rules are configured as:
	</para>

	<programlisting role="php"><![CDATA[
// Default route for root URL
$this->addRoute('default', '', array('controller' => 'index', 'action' => 'index'));

// Route for Router v1 compatibility
$this->addRoute('compat', ':controller/:action', array('controller' => 'index', 'action' => 'index'));]]></programlisting>

	<note>
		Though Zend_Controller_RewriteRouter is configured for backwards compatibility it will not match
		<code>controller/action</code> URIs with additional parameters just yet.
	</note>

</sect1>
<commit_msg>More detailed information about controller and action variables (<NAME>)<commit_after><sect1 id="zend.controller.rewriterouter.introduction">
    <title>Introduction</title>
	<para>
		Zend_Controller_RewriteRouter is a new version of the framework router. Routing is the process of taking a URI
		endpoint and decomposing it to determine which controller and action of that controller, should receive the
		request. This definition of controller, action and optional parameters is packaged into a value object called
		Zend_Controller_Dispatcher_Token which is then processed by Zend_Controller_Dispatcher. Routing occurs only once:
		when the request is initially received and before the first controller is dispatched.
	</para>
	<para>
		Zend_Controller_RewriteRouter is designed to allow for mod_rewrite like functionality using pure php
		structures. It is very loosely based on Ruby on Rails routing and does not require any prior knowledge of
		webserver URL rewriting. It is designed to work with a single mod_rewrite rule (one of):
	</para>
	<programlisting role="php"><![CDATA[
RewriteEngine on
RewriteRule !\.(js|ico|gif|jpg|png|css)$ index.php]]></programlisting>
	<programlisting role="php"><![CDATA[
RewriteEngine on
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteCond %{SCRIPT_FILENAME} !-d
RewriteRule ^(.*)$ index.php/$1	]]></programlisting>
</sect1>

<sect1 id="zend.controller.rewriterouter.usage">
	<title>Using a router</title>

	<para>
		To properly use the RewriteRouter you have to instantiate it, add some user defined routes and inject it into the
		controller. The following code illustrates the procedure:
	</para>

	<programlisting role="php"><![CDATA[
/* -- create a router -- */

$router = new Zend_Controller_RewriteRouter();
$router->addRoute('user', 'user/:username', array('controller' => 'user', 'action' => 'info'));

/* -- set it in a controller -- */

$ctrl = Zend_Controller_Front::getInstance();
$ctrl->setRouter($router);]]></programlisting>
</sect1>

<sect1 id="zend.controller.rewriterouter.basic">
	<title>Basic Routes</title>

	<para>
		The heart of the RewriteRouter is the definition of user defined routes. Routes are created by calling the addRoute method of
		RewriteRouter:
	</para>

	<programlisting role="php"><![CDATA[
$router->addRoute('user', 'user/:username');]]></programlisting>

	<para>
		The first parameter is the name of the route. It is redundant at the moment of writing but will be used in the future in
		a URL view helper to allow for easy URL generation in your views. Should you need to make use of a previously
		configured named route, you can retrieve it with the getRoute method of the RewriteRouter.
	</para>

	<para>
		The second parameter is a route that will be matched to a URL - for example, the above route will match
		<code>http://example.com/user/martel</code>. The colon in a route marks a URL variable which will be accessible
		through a Zend_Controller_Action::_getParam method. In our example a parameter named username will be set to a value of
		'martel'.
	</para>

	<note>
		Routes are matched in reverse order so make sure your most generic routes are defined first.
	</note>

	<note>
		For now the current implementation allows for use of any characters except a slash (/) as a variable identifier but
		it is strongly recommended that one uses only php variable friendly characters. In future the implementation will probably be
		altered and this may introduce bugs to your code.
	</note>

	<para>
		There are two special variables which can be used in your routes - 'controller' and 'action'. These special
		variables will be used to find a controller and/or an action chosen in the URL. The 'action' variable 
		must always be defined either in the route or as a default parameter. The 'controller' variable will default 
		to the IndexController if it is not defined.
	</para>

	<programlisting role="php"><![CDATA[
$router->addRoute('user', ':controller/:action');]]></programlisting>

	<para>
		If you point your browser to 'http://example.com/news/latest' with this route defined the
		Zend_Controller_Dispatcher will invoke the latestAction of your NewsController.
	</para>

</sect1>

<sect1 id="zend.controller.rewriterouter.variable-defaults">
	<title>Variable defaults</title>

	<para>
		Every variable in the route can have a default. To provide it you have to add a third parameter to the addRoute
		method. This third parameter is an array with keys as variable names and values as desired defaults.
	</para>

	<programlisting role="php"><![CDATA[
$router->addRoute('archive', 'archive/:year', array('year' => 2006));]]></programlisting>
	<para>
		What may not be clearly visible is that the above route will match URLs like 'http://example.com/archive/2005' and
		'http://example.com/archive'. In the latter case the variable year will have a value of 2006.
	</para>

	<para>
		In the above example we haven't set a controller so it will always result in a noRoute action of an
		IndexController. To make it usable you have to provide a valid controller and a valid action as a default:
	</para>

	<programlisting role="php"><![CDATA[
$router->addRoute('archive', 'archive/:year', array('year' => 2006, 'controller' => 'archive', 'action' => 'show'));]]></programlisting>

</sect1>

<sect1 id="zend.controller.rewriterouter.variable-requirements">
	<title>Variable requirements</title>

	<para>
		One can add a fourth parameter where variable requirements can be set. These are defined as regular
		expressions:
	</para>

	<programlisting role="php"><![CDATA[
$router->addRoute('archive', 'archive/:year', array('year' => 2006), array('year' => '\d+'));]]></programlisting>

	<note>
		Unlike Ruby on Rails, ZF RewriteRouter will match a route and use a default when a fourth parameter variable requirement is not met. So the
		URL of 'http://example.com/archive/test' will match the above route and set the year to 2006. This functionality
		may be altered in the future as it is being discussed at the moment of writing of this documentation.
	</note>

</sect1>

<sect1 id="zend.controller.rewriterouter.rewritebase">
	<title>Base URL and subdirectories</title>

	<para>
		Unlike the original Router, RewriteRouter can be used in subdirectories - it automatically detects your base URL and
		sets it accordingly. For example: if you keep your <code>index.php</code> in a webserver subdirectory named
		<code>/projects/myapp/index.php</code> rewrite base (base URL) will be set to <code>/projects/myapp</code>. This string will then be 
		stripped from the beginning of the path before calculating any route matches. This frees one from the necessity of prepending it to
		any of your routes. The route of <code>'user/:username'</code> will match URIs like
		<code>http://localhost/projects/myapp/user/martel</code> and <code>http://example.com/user/martel</code>.
	</para>

	<note>
		Automatic rewrite base is case sensitive, so make sure your URL will match a subdirectory name in a filesystem
		(even on Windows machines). If it doesn't you will get to noRoute action.
	</note>

	<para>
		Should rewrite base be detected incorrectly you can override it with your own base path with the help of the
		setRewriteBase method of the RewriteRouter class:
	</para>

	<programlisting role="php"><![CDATA[
$router->setRewriteBase('/projects/myapp');]]></programlisting>

	<note>
		This step won't be necessary in most cases and is strongly discouraged as it introduces another configuration variable
		which would have to be altered when one moves code to another directory configuration.
	</note>

</sect1>

<sect1 id="zend.controller.rewriterouter.default-routes">
	<title>Default routes</title>

	<para>
		Zend_Controller_RewriteRouter is preconfigured with two default routes. The first handles  your root URL and is
		mapped to indexAction of IndexController: so you have to provide them as outlined in the  Getting Started chapter (paragraph
		2.2.5). The second default route is included to provide compatibility with the first version of the router. It will match URIs in
		the shape of <code>'controller/action'</code>.
	</para>

	<para>
		Default rules are configured as:
	</para>

	<programlisting role="php"><![CDATA[
// Default route for root URL
$this->addRoute('default', '', array('controller' => 'index', 'action' => 'index'));

// Route for Router v1 compatibility
$this->addRoute('compat', ':controller/:action', array('controller' => 'index', 'action' => 'index'));]]></programlisting>

	<note>
		Though Zend_Controller_RewriteRouter is configured for backwards compatibility it will not match
		<code>controller/action</code> URIs with additional parameters just yet.
	</note>

</sect1>

{'fraction_non_alphanumeric': 0.10013389998253479, 'fraction_numerical': 0.00500669499912674, 'mean_word_length': 4.665567282321899, 'pattern_counts': {'":': 0, '<': 244, '<?xml version=': 0, '>': 288, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7253090', 'n_tokens_mistral': 5066, 'n_tokens_neox': 4630, 'n_words': 2081}