input filters and link generation. Using both, you are fully enabled to change the URL layout without changes to the application's source code." /> input filters and link generation. Using both, you are fully enabled to change the URL layout without changes to the application's source code."/>

URL rewriting

1. Einleitung

The Adventure PHP Framework supports transparent URL rewriting based on input filters and link generation. Using both, you are fully enabled to change the URL layout without changes to the application's source code.

The APF ships a standard set of input and output filters (ChainedUrlRewritingInputFilter and ChainedUrlRewritingOutputFilter) and link generation (RewriteLinkScheme) that allow you to use a generic rewritten URL format within your application.

Further URL schemes can be implemented very easy based on that. Please find a tutorial within the Wiki (German).

2. URL layout

The components delivered allow to rewrite URLs like

Code
http://www.example.com/?page=start

into

Code
http://www.example.com/page/start

As you can take from the second code block ? and = are replaced with / to create a more folder-style appearance. Calling this page, the page parameter is assigned value start just like in the first case.

The number of parameters is not limited. The URL scheme is as follows:

Code
{scheme}://{host}/{param1}/{value1}/{param2}/{value2}/...

Parameter and value are separated by /; several couples are separated by / as well. URLs including action instructions add to the above scheme and are described under Front controller.

Using rewritten URLs aided by the standard features of the APF you must ensure that the bootstrap file (e.g. index.php) is located within the DOCUMENT_ROOT of your web server or VHOST. This is necessary to correctly assign parameters and their respective values.

3. Configuration

Configuration of the URL mapping of the APF includes several components:

Component Description
Input filter The input filter resolves the URL schema. For this reason, the URL is deconstructed into it's elements and the pieces are stored for further processing. Storage is usually done within the $_REQUEST-, $_GET-, or $_POST arrays in order to provide access to URL information for the application executed subsequently independently from the external representation. Details can be taken from chapter Filter.
Link scheme The LinkScheme implementation is responsible to generate an URL according to the desired scheme. In contrast to input filters it generates an external representation from the internal state. Details on URL generation can be taken from chapter Links.
Output filter If necessary, URLs that are not generated by a LinkScheme can be transcribed into an external representation by an appropriate output filter. Within an output filter you are able to access the whole source code. Hence, you can rewrite form actions, image sources or other resources to adapt them to the desired external representation.
Web server configuration In order to allow rewriting URLs while deliver pages through a single bootstrap file the configuration of your web server or virtual server must be adapted. Without appropriate rules the web server checks on files located within the requested directory that are - of course - not existing and reports an error.

The following chapters describe the configuration for simple and rewritten URLs of the components listed above.

3.1. Standard URLs

Using the APF as-is the standard input filter (ChainedStandardInputFilter) takes care of extracting Front controller action instructions. Besides, the DefaultLinkScheme is registered that allows generation of simple URLs including action instructions.

Handling simple URLs does not require further output filter or web server configuration. For this reason APF/core/bootstrap.php does not include further settings.

In case you intend to work with simple URLs within your project, no changes to the standard setup are necessary.

3.2. Rewritten URLs

Using rewritten URLs requires adaption of the delivery status. Changes can be done within your bootstrap file (e.g. index.php) after inclusion of the central APF bootstrap file (APF/core/bootstrap.php).

Using URL rewriting it is recommended to use only one single bootstrap file to ease configuration of the framework components and the web server.

The following chapters describe the configuration steps necessary to adapt the shipped components in-depth to enable your project to use rewritten URLs.

3.2.1. Input filter

As mentioned in chapter 3 the input filter takes care of the request processing and interpretation of the request. In order to resolve the URL layout described in chapter 2 into an internal representation the ChainedUrlRewritingInputFilter is required.

Please register this input filter within the bootstrap file of your application as follows:

PHP code
include('../APF/core/bootstrap.php'); use APF\core\filter\InputFilterChain; use APF\core\filter\ChainedUrlRewritingInputFilter; InputFilterChain::getInstance()->clear()->prependFilter(new ChainedUrlRewritingInputFilter());

As a second step the LinkScheme implementation is necessary. It generates an external representation according to the schema defined in chapter 2.

Registration of the link scheme matching the ChainedUrlRewritingInputFilter is as follows after registration of the output filter:

PHP code
use APF\tools\link\RewriteLinkScheme; use APF\tools\link\LinkGenerator; LinkGenerator::setLinkScheme(new RewriteLinkScheme());
3.2.3. Web server configuration

In order to pass requests to the virtual folder structure (URL schema see chapter 2) to the bootstrap file of your application an adaption of the web server or VirtualHost configuration is necessary.

Using the following RewriteRule (Apache web server) you can add the required configuration to your .htaccess:

Code
RewriteEngine on RewriteRule !index\.php$ /index.php?apf-rewritten-query=%{REQUEST_URI}&%{QUERY_STRING} [NC,L]

The first line activates the mod_rewrite module of the Apache web server that allows to internally rewrite URLs or direct requests to different resources. Line 2 effectively directs all requests to the index.php file.

Please note, that

Code
/index.php?apf-rewritten-query=%{REQUEST_URI}&%{QUERY_STRING}

is to be defined exactly like that to enable the ChainedUrlRewritingInputFilter to correctly resolve the URL scheme.

Introducing

Code
!index\.php$

ensures that no redirect cycle comes up.

Images, CSS and Java Script files are usually delivered through the web server directly and not by the index.php. In order to enable this work-split please add exception rules as required. You can either extend the RewriteRule or add RewriteCond definitions. Example:

Code
# Exclusion of entire directories RewriteCond %{REQUEST_URI} !^(\/images|\/css|\/js) [NC] # Exclusion of defined files or file extensions RewriteRule !(index\.php|\.css|\.jpe?g|\.png|\.gif|\.ico)$ /index.php?apf-rewritten-query=%{REQUEST_URI}&%{QUERY_STRING} [NC,L]

Both ways can be combined as desired. Details can be taken from the documentation of your web server.

3.2.4. Output filter

If necessary, URLs that are not generated by a LinkScheme can be transcribed into the external representation described in chapter 2 by the ChainedUrlRewritingOutputFilter output filter. This implementation transcribes all a and form tags.

In case dedicated URLs should be excluded from rewriting please add the HTML attribute linkrewrite with value false. The filter uses this information to exclude URLs marked like this and directly removes the marker to not produce invalid source code.

The configuration of the output filter can be done within the bootstrap file as follows:

PHP code
use APF\core\filter\OutputFilterChain; use APF\core\filter\ChainedUrlRewritingOutputFilter; OutputFilterChain::getInstance()->appendFilter(new ChainedUrlRewritingOutputFilter());

Please note that the configuration must happen after inclusion of the APF/core/bootstrap.php file.

mailto: links are automatically excluded from transcription.

4. Notes

While using URL rewriting the following hints should be kept in mind:

  • Ressources like images, css files or java scripts must be addressed absolutely.
  • Components that manually generate URLs must be adapted. It is recommended to switch to URL generation with the LinkGenerator. Details can be taken from Links.
  • If you are using more than one bootstrap file, please add it to the exception list of your web server configuration.

Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.
There are no comments belonging to this article.