The basic installation assumes that all webpages are in the root level of the Mara site, and that any new pages are created using the online tools. This arrangement has been chosen in v4 because it allows for an installation which in most cases will 'just work' straight from the unzipped fileset, without the need for any adjustment of settings.
Note that when we say 'root of the site structure' that refers to this Mara instance, and does not restrict the website to being in the domain root.
In order to achieve this, it relies upon a 'shebang' or reflex loader command being present in the first line of each webpage. For site-root pages this will be <?php include_once 'codebase/reflex.php' ?> -and this must literally be the very first statement in the file, before any doctype or head tags.
If you need to import existing webpages into a Mara site, then the simple option for a small number of pages is to manually add the shebang to each page.
When importing large numbers of pages or when building a multilevel site, it may be more convenient to activate automatic reflex loading. In that case, the shebang in each page is unnecessary -saving a great deal of donkey work- and any ordinary html file should then act as a Mara page.
The reason automatic reflex loading isn't activated by default is the myriad of differing webserver configurations found on hosting space, and the fact that an unsuitable setting may crash your website, leaving only a cryptic '500 Error' message in the browser. Thus, you may need to do a few relatively simple tests (or check the host company documentation) to find out what setting will work in your case.
These are the more traditional form of php-capable In their case, the setting which controls reflex loading is in the .htaccess file, and has the form of
php_value auto_prepend_file codebase/reflex.php
This line is present already in the supplied .htaccess, and only needs the # removing to activate it. Doing so will basically have two possible outcomes; pages will load into Mara without the shebang, or else you see a '500 Error' and absolutely nothing works. If the latter you are not on a module based server and should re-comment the line. Don't be too worried about testing this, as the '500 Error' will not do any permanent harm.
The more modern way to run php is in CGI mode, and most sites prefer this since it offers better security. On all such sites you cannot use the .htaccess approach to reflex loading. If you try that, you will see a 500 Error.
A further complication with CGI sites, in that there are two distinct ways in which a reflex loader command might have to be added. That is, via php.ini file, or via a .user.ini file. These two use the typical ini-file syntax for commands:
auto_prepend_file = 'codebase/reflex.php'
On any given site it's your best guess as to which will work, and which won't. Occasionally, either is allowed. Two important behavioural differences exist between php.ini and .user.ini.
A php.ini file overrides ALL settings in higher directories, including those in the server's configuration itself. Thus in some cases, having a blank or one-line php.ini might cause things to misbehave. This is rare, though, as the defaults are usually OK anyway. A php.ini file only affects the webpages in its own directory/folder Therefore on a larger, multilevel website you may need a php.ini at each level with webpages.
A .user.ini file does not pre-empt settings made at higher levels on the server, so there is no issue with loss of the defaults set by the hosting company. Settings in .user.ini propagate down through site levels, so in principle only one is needed, in the Mara site root. Though, if you need to countermand the settings in any given .user.ini at a lower level of the site, this may require further .user.ini files at each level. To allow for this situation, system locations in Mara come presupplied with a .user.ini countermanding the reflex loader. Just to ensure it doesn't trigger on system pages.
In general there is no harm in leaving php.ini and .user.ini files in the site if they do nothing on that particular server.
By the way, note that .htaccess and .user.ini start with a dot, whilst php.ini has no leading dot.
For larger sites it may be preferable to use a fully-qualified path (from the server's filesystem root) to reflex.php instead of a relative one. Done this way, you only need one .htaccess or .user.ini to cover reflex loading throughout a multilevel site. The issue to watch here is that typical webserver's path structure is not the same as the path you see in the browser's URL bar. To find the filesystem path, you should either check your host's online documentation, or run a phpinifo() command on the server. An .user.ini example might be
auto_prepend_file = '/home/user/htdocs/codebase/reflex.php'
-but remember this is only an example and almost certainly will not apply in your case.
The above may sound a little daunting but in most cases it is the work of a few minutes to find the right setting, and once done, pages can be uploaded as-is to any site level. we've been looking at an automated installler to handle this aspect, but the sheer number of combinations, plus the fact that some will lock the installer itself out with a 500 error, make it a hard thing to automate any tests. Basically, this is an area where webservers need to achieve a better level of standardisation.
A change in v4 and above is the use of .php as the default file extension. As we'd like to ensure that Mara works in most situations out-of-zip, this is to avoid any possible issues with the relatively few webservers around these days which cannot run php from within htm or .html files.
In practice though, for live sites it is often better to use .htm or .html as the document extension. For one thing, this makes the import of existing pages easier. Plus, if you allow extensions to be seen (see extensionless working) then most people prefer to see a familiar htm(l) extension. To allow the editor to create .htm(l) files by default, change the default_extension setting in siteini.php.
See the supplied .htaccess file for advice on configuring your webserver to run php from within html files, if it does not already do so.