How Inbound Requests are Handled in Mercury
On a Mercury site all requests transformed by Apache's mod_rewrite module so that they are processed by the mercury.php file in the site root.
Excluding Folders
By default this will apply to every file on the site but certain files don't have any reason to go through Mercury: images, javascript files, css files, pdf files. It is possible to exclude specific folders from being processed by Mercury and by default this will be the case with the following folders off of your document root: images, css, scripts, content. The file called .htaccess contains a directive that turns off url rewriting and files in these folders are served normally. If you have specific subfolders that you want to serve normally you can copy the .htaccess file from one of those folders to your new folder.
What Actually Happens in Mercury's URL Rewriting
Let's assume an inbound path like http://yourdomain.com/somepath/filename. Apache's modrewrite will translate this inbound URL into:
http://yourdomain.com/mercury.php?path=somepath/filename
If the inbound URL has variables like http://yourdomain.com/somepath/filename?variable1=abc&variable2=def then the URL rewriting will transform the incoming request into:
http://yourdomain.com/mercury.php?path=somepath/filename&variable1=abc&variable2=def
This means that you will NOT be able to use an incoming variable called path in your Mercury applications as this variable will be used by Mercury in every single page request.
Back to the Processing Process
Mercury will then look at the incoming path variable and also the same variable chopped into an array. Mercury will search through a series of paths until if finds the file it is looking for. It will then either include or execute the file and pull it into a layout file. The default layout file (and the one that I recommend you use for the majority of the pages on your site) is in html/layout.php. More on layouts later, for now we're going to look at the content of the page.
Let's consider the same http://yourdomain.com/somepath/filename. Here is the order that Mercury will process this request:
- Does this file actually exist on the server with the specified path?
- Does this file exist on the server with index.html added to the path?
- Is there an SEO translation file (more on this later) with that path?
- Is there an SEO translation file with index.html added to the path?
- Treating the first 'directory' as a module, is there a router.php file in the per-site Mercury somepath module folder?
- Treating the first 'directory' as a module, is there a router.php file in the global Mercury somepath module folder?
- If there is only one 'directory' specified is there an index.php file in the per-site Mercury somepath module folder?
- If there is only one 'directory' specified is there an index.php file in the per-site global somepath module folder?
- In the example above is there a file called filename.php in the per-site Mercury somepath module folder?
- In the example above is there a file called filename.php in the global Mercury somepath module folder?
- Error, the path was not found.
The first two are obvious, the second two are the subject of another document in this section. Let's skip the 'router' lines and discuss the rest.
Some Examples
A file with the url /about-me.html will probably match a file that has been created in /html/about-me.html. This file may be uploaded by you manually or it may have been created by a content management tool.
A file with the url /users/login-form (note the lack of file extension) will probably not match an actual file on the system. It will look for a file called login-form.php in the users module. First it will look to see if your site has it specified in the html/mercury/users/ folder and then it will look in the global Mercury files. If Mercury finds the file in your own html/mercury/users folder then it will use it and ignore the global version.
A file with the url /mymodule/dosomething will almost certainly be part of a custom module. It will look for a file called dosomething.php in the html/mercury/mymodule/ folder.
A file with the url /images/logo.jpg will look in html/images folder for a file called logo.jpg. This folder is immune from url rewriting and the file will be served as-is.