Bitrix Site Manager

URL Rewriting

What is URL Rewriting?

Using a URL rewrite engine, the website software can be presented with URL's in one form, while actual requests (and URL's seen by the user) are in another form. For example, rewriting can be configured in such a way that a script in /fld/c.php, responding at:

/fld/c.php?id=15

would also be available at:

/catalog/15.php

The address at which the script would be available must not physically exist; otherwise, the existing file will be retrieved instead. In this case, URL rewriting engine would not be activated.

Rewriting rules

The URL rewriting rules are configured for each site individually and stored in urlrewrite.php in the site root. This file contains an array $arUrlRewrite, each entry being a URL rewriting rule. The following code shows an example of urlrewrite.php:

<?
$arUrlRewrite = array(
    array(
        "CONDITION" => "#^/gallery/#",
        "RULE" => "",
        "ID" => "bitrix:photo",
        "PATH" => "/max/images/index.php",
    ),
    array(
        "CONDITION" => "#^/forum/#",
        "ID" => "bitrix:forum",
        "PATH" => "/forum/index.php",
    ),
    array(
        "CONDITION" => "#^/index/([0-9]+)/([0-9]+)/#",
        "RULE" => "mode=read&CID=$1&GID=$2",
        "ID" => "bitrix:catalog.section",
        "PATH" => "/newforum/index.php",
    ),
    array(
        "CONDITION" => "#(.+?)\\.html(.*)#",
        "RULE" => "$1.php$2",
    ),
);
?>

Each rule has a rule application condition that is unique within the site. The condition which is a Perl compatible regular expression is contained in the "CONDITION" key of the array. For example:

"CONDITION" => "#^/index/([0-9]+)/([0-9]+)/#"

specifies that the rule should be applied to all URL's starting with text like:

/index/<number>/<number>/

A rule can include and address of an existing script that will be activated when the condition is true. This address is specified in the "PATH" key. For example, if the following rule is active:

array(
    "CONDITION" => "#^/gallery/#",
    "PATH" => "/max/images/index.php",
)

and a user requests the page that does not exist physically:

/gallery/38.php

the URL rewrite engine will return the script:

/max/images/index.php

Rules can contain replacement options that can be specified in the "RULE" key. If the key exists, the final address is the result of the regular expression replacement operation on the source address. The rewrite engine takes the CONDITION as a search pattern and replaces the matching portion of the address with the concatenation of the PATH and the RULE keys, the latter containing the regular expression replacement switches.

Example 1

For example, the following rule:

array(
    "CONDITION" => "#^/index/([0-9]+)/([0-9]+)/#",
    "RULE" => "mode=read&CID=$1&GID=$2",
    "PATH" => "/newforum/index.php",
)

when applied to the address:

/index/5/48/

will execute the following code:

$url = preg_replace("#^/index/([0-9]+)/([0-9]+)/#",
                    "/newforum/index.php?mode=read&CID=$1&GID=$2",
                    "/index/5/48/");

which will produce the following result:

/newforum/index.php?mode=read&CID=5&GID=48
Example 2

The rule:

array(
    "CONDITION" => "#(.+?)\\.html(.*)#",
    "RULE" => "$1.php$2",
)

in reply to requesting the following page:

/about/company.html?show

will execute the following code to build the real address:

$url = preg_replace("#(.+?)\\.html(.*)#", "$1.php$2", "/about/company.html?show");

and call the script:

/about/company.php?show

A rule can contain the name of a component that created the rule. The component name should be specified in the "ID" key. When the rule definition file (urlrewrite.php) is recreated using the Control Panel tools, only the rules with the valid "ID" key are modified. These rules are recreated by analyzing files in the site directory. The rules whose ID key is empty are not changed.

Activating URL rewrite engine

The URL rewrite engine must be activated before it can be used. The following actions need to be performed to activate the engine:

Components 2.0 Support

When a SEF-enabled component is added to a page and latter is saved using API functions, a corresponding URL rewrite rule is created automatically. However, if a page is created not using API functions (e.g. uploaded via FTP), you will have to re-create rules manually by using tools in the URL rewrite administration form.

In a component, SEF support can be enabled by specifying a special input parameter SEF_MODE. This will set the predefined parameter SEF_FOLDER to the folder in which the component runs. The folder can be virtual (i.e. it may or may not physically exist). When a page with a SEF-enabled component (SEF_MODE is Y) is saved, a URL rewrite rule is created in the following way:

Consider the following example. A "bitrix:catalog" component is added to /fld/c.php. It is activated by the following call:

$APPLICATION->IncludeComponent(
    "bitrix:catalog",
    "",
    Array(
        "SEF_MODE" => "Y",
        "SEF_FOLDER" => "/mycatalog/",
        "IBLOCK_TYPE_ID" => "catalog",
        "BASKET_PAGE_TEMPLATE" => "/personal/basket.php",
    )
);

When a page /fld/c.php is saved, the following record will appear in the URL rewrite rules:

array(
    "CONDITION" => "#^/mycatalog/#",
    "RULE" => "",
    "ID" => "bitrix:catalog",
    "PATH" => "/fld/c.php",
)

Thus, requesting a page starting from /mycatalog/ will return the file /fld/c.php. This script may analyse the requested address and act appropriately.