Phork Installation

The default Phork installation comes with 2 basic sites to use as a starting point for your application - standard and lite, or you can download the Phork/it package. It's recommended that you choose one of these sites and make a recursive copy of its site directory which can be found at phork/sites/[sitetype]/. You can name your directory copy anything that you'd like, for example public, admin, phorkit, myproject, etc. You can even have multiple sites all built off the same Phork core. For example you may want both a public site and an admin site, or even several completely unrelated sites.

If you would like a lite site with the aforementioned hooks or conversely, a standard site without them they can be added to or removed from phork/sites/[sitetype]/bootstraps/SiteBootstrap.class.php. The site timer can be added to or removed from the front controller

The document root for each site is phork/sites/[sitetype]/htdocs/ where [sitetype] is public, admin, phorkit, myproject or any other site you've created.

Front Controller (index.php)

Each site contains a front controller at phork/sites/[sitetype]/htdocs/index.php. Your Phork application should be routed through this file. You may need to make some changes to this file.

First you may want to change the error_reporting() level. You must leave E_USER_NOTICE errors on because Phork relies heavily on trigger_error().

error_reporting(E_ALL | E_STRICT);

Next you may need to change the following directory variables: $strSiteDir, $strConfigDir, $strInstallDir. By default these are determined from the location of index.php. If you've moved any directories to non-standard locations these values will need changing accordingly. Likewise, the bootstrap include may need a new path. All the directory paths should be absolute paths that end with a slash.

//the path to the directory containing the site files (eg. /path/to/phork/sites/lite/)
if (empty($strSiteDir)) {
    $strSiteDir = dirname(dirname(__FILE__)) . '/';
}

//the path to the directory containing the site config files (eg. /path/to/phork/sites/lite/config/live/)
if (empty($strConfigDir)) {
    if (empty($strConfigType)) {
        $strConfigType = 'live';
    }
    $strConfigDir = "{$strSiteDir}config/{$strConfigType}/";
}

//the path to the directory containing the phork package (eg. /path/to/phork/)
if (empty($strInstallDir)) {
    $strInstallDir = dirname(dirname($strSiteDir)) . '/';
}

There are 2 ways to change these values. The first is to edit the front controller and replace the auto-detection with hardcoded values. The second (and recommended) way is to create an auto-prepend file with the directory definitions in it. Typically this file is named paths.php and goes in the same directory as the front controller. If you can't automatically prepend the paths file then you can put an include at the top of the front controller.

An example prepended paths.php file could look something like this:

<?php    
    //determine the config file directory based on the host name
    if (strpos($_SERVER['HTTP_HOST'], 'dev') !== false) {
        $strConfigType = 'dev';
    } else if (strpos($_SERVER['HTTP_HOST'], 'stage') !== false) { 
        $strConfigType = 'stage';
    } else {
        $strConfigType = 'live';
    }
    
    //use the global phork package
    $strInstallDir = '/www/phork/';
?>

Configuration

Phork comes with a directory of example configuration files. Each site type (eg. dev, stage, live) should have its own set of configuration files. The configuration directories can be found at phork/sites/[sitetype]/config/.

By default the config directory is set to live. If your preferred configuration is different from the default then you will need to edit how $strConfigType is determined. Again, this can be set in either the front controller or an auto-prepend file. Usually the config type is determined by the host name.

//determine the config file directory based on the host name
if (strpos($_SERVER['HTTP_HOST'], 'dev') !== false) {
    $strConfigType = 'dev';
} else {
    $strConfigType = 'live';
}

Next you should copy all the files from the phork/sites/[sitetype]/config/example/ directory to your configuration directory. If, for example, $strConfigType is set to live then your config directory will be phork/sites/[sitetype]/config/live/.

You should go through the configuration files and set them up for your particular application.

Mod Rewrite and .htaccess

Each site's document root has an .htaccess file in it that turns on Apache's Mod Rewrite for cleaner URLs like http://www.example.org/path/to/page. If you're not using Apache you should read your server's documentation on URL rewriting. If URL rewriting is unavailable then Phork will rely on $_SERVER['PATH_INFO']. In that case your URLs will look like http://www.example.org/index.php/path/to/page or http://www.example.org/index/path/to/page.

The preferred rewrite rule does not use a query string, however if your server doesn't allow this then it's possible to use a query by making some small adjustments to how CoreUrl is called. RewriteEngine on

RewriteRule ^(robots\.txt|favicon\.ico)$ - [L]

RewriteCond     %{REQUEST_FILENAME} !-d
RewriteCond     %{REQUEST_FILENAME} !-f
RewriteCond     %{REQUEST_FILENAME} !-l

#This is the preferred rewrite rule
RewriteRule  .*  ./index.php/$0 [L,NC,QSA]

#This is the alternative rewrite rule that uses the query string
#RewriteRule .* ./index.php?$0 [L,NC,QSA]

The default Phork installation comes with the assumption that you do not have mod rewrite. If you would like to set up your application to use mod rewrite then you should edit the site.config.php file and change the following line from this:

$arrConfig['BaseUrl'] = '/index.php';

to this:

$arrConfig['BaseUrl'] = '';

If you would prefer your URL to be in the format http://www.example.org/index/path/to/page instead of http://www.example.org/index.php/path/to/page then you should change the aforementioned line to this:

$arrConfig['BaseUrl'] = '/index';

Alternately if you'd prefer index to be replaced with something else entirely then please see the section on renaming index.php.

When linking to different pages throughout your application if you prepend each link with the base URL then you can easily switch between using mod rewrite and not using it.

//this assumes that $arrConfig['BaseUrl'] has been passed into this template as $strBaseUrl
<a href="<?php echo($strBaseUrl); ?>/foo/bar/">Foo Bar</a>

Document Roots

If you only have one site per Phork installation you can ignore the subdomain and subdirectory installation sections and just set up your server's document root to be your site's htdocs directory. The standard document root for each site is phork/sites/[sitetype]/htdocs/.

If you have multiple sites running off the same Phork installation, this can be done in two different ways. The first and recommended way puts the each site type as a domain or subdomain. For example, http://admin.example.org. The second way designates one site as the main site (eg. public) and puts the other sites as subdirectories. For example, http://www.example.org/admin/.

Non-Standard Document Roots

If your document root can't be changed to phork/sites/[sitetype]/htdocs/ then you can either move the full site directory to another location, or you can move just the contents of the site's htdocs directory. The rest of the directory structure should remain in tact however. If you do move things around you will need to edit the directory variables in the front controller. The following site.config.php snippet can be used for a Phork that's not at the document root.

//the site urls should always contain the domain; the css and js urls can omit it
$arrConfig['SiteUrl'] = 'http://example.org';
$arrConfig['SecureUrl'] = 'https://example.org';
$arrConfig['CssUrl'] = '/phorkit/htdocs';
$arrConfig['JsUrl'] = '/phorkit/htdocs';

//the url of the front controller excluding the filename if using mod rewrite
$arrConfig['BaseUrl'] = '/phorkit/htdocs';

If you're using Phork/it then you'll also have to change the image paths in the CSS files.

Domain and Subdomain Installation

Phork already comes set up for domain/subdomain installation, however your server must also be set up to handle this. Server set up is beyond the scope of this document, but your server manual should have detailed instructions. You will need to set up a virtual domain to point to each site's document root.

Subdirectory Installation

For the purpose of this documentation we will pretend that you are creating an admin site off the public site, in which case you would have already created phork/sites/admin/ and phork/sites/public/. And we will also assume that you are using the live config directory.

In order for the different sites to work within subdirectories you'll first need to create a symbolic link (also known as a symlink) in the main site's document root to the sub-sites' document roots. In this case there would be a symlink to phork/sites/admin/htdocs/ from phork/sites/public/htdocs/admin.

$ cd /path/to/phork/sites/public/htdocs/
$ ln -s ../../admin/htdocs admin

If your server doesn't support symlinks then you should move the sub-site's htdocs directory into the parent site's htdocs directory and follow the non-standard document root instructions for the sub-site. In this case you will want to move phork/sites/admin/htdocs/ to phork/sites/public/htdocs/ and rename it to admin. The path to your admin front controller would be phork/sites/public/htdocs/admin/index.php.

You'll have to alter each sub-site's config file to point to the new root directory as well as the new asset paths. The configuration will be covered in more detail later on, but for now you should open up phork/sites/admin/config/live/site.config.php.

If you want the admin to live at http://www.example.org/admin/, go to the URLs section and change the following lines:

//the url of the front controller excluding the filename if using mod rewrite
$arrConfig['BaseUrl'] = '/index.php';

to one of these:

//include the filename if you don't have mod-rewrite
$arrConfig['BaseUrl'] = '/admin/index.php';

//don't include the filename if you have mod-rewrite
$arrConfig['BaseUrl'] = '/admin';

If you wanted your admin to live at a different URL, say for example private then your symlink should be to phork/sites/admin/htdocs/ from phork/sites/public/htdocs/private and the above config lines should use private in place of admin.

Renaming index.php

If you need to rename index.php you'll need to either change the rewrite rule in .htaccess if you're using mod rewrite, or you'll need to change the $arrConfig['BaseUrl') definition in the site configuration file to end with the new filename.

Directory Permissions

In general the phork/sites/[sitetype]/files/ directory is where all web-writable and uploaded files go, and so that directory and all subdirectories should have the appropriate permissions.

There are 3 predefined subdirectories: app, private and public. The general idea is that app is used for application files such as error logs, debug logs and file caches; private is used for files that are private and need to be run through a script that verifies permissions before outputting the file; and public is for files than anyone can access, and it can be symlinked to from the sites' htdocs directory.

If you wish to use Phork's error logging and debug logging the default files that need to be writable are defined in the global configuration. They are usually phork/sites/[sitetype]/files/app/logs/error.[date].log and phork/sites/[sitetype]/files/app/logs/debug.[date].log.