- Add test folder

[xhtml-compiler.git] / functions.php

<?php

/**
 * Convenience function that outputs an error and halts execution
 * @param $code integer HTTP error code
 * @param $text Error name string, leave as false to use default
 * @param $details Optional details string explaining error
 * @todo Valid markup, user-defined custom error-pages
 */
function display_error_and_quit($code, $text = false, $details = false) {
    $xc = XHTMLCompiler::getInstance();
    $default = set_response_code($code);
    if (!$text) $text = $default;
    $out = "<h1>Error: $text</h1>";
    if ($details) $out .= $details;
    $xc->paint($out);
    $xc->quit(); // essential, will exit
}

/**
 * Convenience function that outputs an HTTP status code
 * @param $code integer HTTP status code
 * @return string HTTP status code's name
 */
function set_response_code($code) {
    $xc = XHTMLCompiler::getInstance();
    $code_descriptions = array( // could be factored out
        200 => 'Okay',
        304 => 'Not Modified',
        401 => 'Unauthorized',
        403 => 'Forbidden',
        404 => 'Not Found',
        503 => 'Service Unavailable',
    );
    $code = (int) $code; // enforce integer
    $text = (string) $code;
    if (isset($code_descriptions[$code])) {
        $text .= ' ' . $code_descriptions[$code];
    }
    $xc->header($_SERVER['SERVER_PROTOCOL'] . ' ' . $text, true, $code);
    $xc->header('Status: ' . $text);
    return $text;
}

/**
 * Determines the requested page from server environment files
 * @return string page name
 */
function get_page_from_server() {
    $xc = XHTMLCompiler::getInstance();
    // load up page from environment variables, if using ErrorDocument impl.
    $page = $xc->getRequestURI();
    $self = dirname($xc->getPHPSelf());
    $root = strlen(substr($self, 0, strrpos($self, '/')));
    $page = substr($page, $root + 1); // remove leading slash and root
    return $page;
}

/**
 * Determines the requested page from get parameter
 * @return string page name
 */
function get_page_from_get() {
    $page == false;
    if (isset($_GET['f'])) $page = $_GET['f'];
    return $page;
}

/**
 * Takes a page name and appends index filename if necessary
 * @param $page string page name
 * @param $directory_index string name of file to use as directory index
 */
function normalize_index($page, $directory_index) {
    if ($page == '') $page = $directory_index;
    if (is_dir($page)) {
        if ($page[strlen($page)-1] !== '/') $page .= '/';
        $page .= $directory_index;
    }
    return $page;
}

/**
 * Determines page and page source based on a filename
 * @param $page_or_src filename of actual page or source file
 * @return array(page filename, source filename)
 */
function calculate_page_and_src($page_or_src) {
    $root = substr($page_or_src, 0, strrpos($page_or_src, '.'));
    return array($root . '.html', $root . '.xhtml');
}

/**
 * Validates a page name, making sure that is allowed and in proper format;
 * halts page execution if invalid
 * @param $page string page name to validate
 * @param $allowed_dirs lookup array of allowed directories, see config.default.php
 * @param $filename_chars PCRE style string of characters, see config.default.php
 */
function validate_page($page, $allowed_dirs, $filename_chars) {
    // validate the path, perhaps syntax could be more permissive
    $regex = "#(((?:[$filename_chars]+/)*)[$filename_chars]+).html#";
    $status = preg_match($regex, $page, $matches);
    if (!$status) display_error_and_quit(403);
    
    // validate directory
    if (!isset($allowed_dirs[$matches[2]])) {
        // maybe one of its parent directories had a recursive declaration
        $dir = $matches[2];
        $dirs = explode('/', $dir);
        $test_dir = '';
        $ok = false;
        foreach ($dirs as $name) {
            if ($name === '') break;
            if (
                isset($allowed_dirs[$test_dir]) &&
                $allowed_dirs[$test_dir] === 1
            ) {
                $ok = true;
                break;
            } else {
                $test_dir .= $name . '/';
            }
        }
        if (!$ok) display_error_and_quit(403);
    }
    
    return $matches[1] . '.xhtml';
}

/**
 * Validates the source XHTML, quits if non-existent
 * @param $page_src filename of page source from validate_page()
 */
function validate_page_source($page_src) {
    if (!is_file($page_src) || !is_readable($page_src)) {
        // Apache may have redirected to an ErrorDocument which got directed
        // via mod_rewrite to us, in that case, output the corresponding
        // status code.  Otherwise, we can give the regular 404.
        $code = (int) getenv("REDIRECT_STATUS");
        if (!$code || $code == 200) $code = 404;
        display_error_and_quit($code);
    }
}

/**
 * Attempts to use cached version of HTML as output, halts execution
 * if successful.
 * @param $page filename of page, already validated
 * @param $page filename of page source, already validated
 */
function try_cache($page, $page_src) {
    if (
        !isset($_GET['purge']) &&
        is_file($page) &&
        !is_cache_stale($page, $page_src)
    ) {
        // cached version is fresh, serve it. This shouldn't happen normally
        set_response_code(200); // if we used ErrorDocument, override
        readfile($page);
        exit;
    }
}

/**
 * Using filemtime, determines whether or not cache is old.
 * @warning Cache file must exist! Check for it with is_file($page)
 * @param $page filename of page
 * @param $page filename of page source
 */
function is_cache_stale($page, $page_src) {
    $mtime_page = filemtime($page);
    $mtime_page_src = filemtime($page_src);
    return $mtime_page_src > $mtime_page;
}

/**
 * Determines whether or not an .html file was generated by us
 * @param $page filename of page, must exist
 */
function is_created_by_us($page) {
    $contents = file_get_contents($page);
    return (strpos($contents, '<!-- generated by HTML Compiler -->') !== false);
}

/**
 * Generates a page from the source file
 * @param $page Filename of output page
 * @param $page_src Filename of source page
 * @return Output page text
 */
function generate_page($page, $page_src) {
    $source = file_get_contents($page_src);
    $contents = $source . '<!-- generated by HTML Compiler -->'; // do processing
    file_put_contents($page, $contents);
    return $contents;
}

/**
 * Traverses a directory looking for pages with a particular extension.
 * @param $ext Extension we're looking for, needs period
 * @param $dir Directory we're looking in
 * @param $recursive Whether or not to go recursively
 */
function scan_for_pages($ext, $dir, $recursive) {
    $scandir = ($dir === '') ? './' : $dir; // scandir barfs on ''
    $files = array();
    if (is_array($ext)) {
        foreach ($ext as $i => $e) $files[$i] = array();
    }
    $contents = scandir($scandir);
    foreach ($contents as $file) {
        if (empty($file) || $file[0] == '.') continue;
        if (is_dir($dir . $file) && $recursive) {
            $files = array_merge($files, scan_for_pages($ext, $dir . $file . '/', 1));
            continue;
        }
        $fileext = strrchr($file, ".");
        if (is_array($ext)) {
            foreach ($ext as $i => $ext_single) {
                if ($fileext === $ext_single) {
                    $files[$i][] = $dir . $file;
                }
            }
        } else {
            if ($fileext === $ext) {
                $files[] = $dir . $file;
            }
        }
    }
    return $files;
}

/**
 * Traverses an array of directories for files with extension
 * @param $ext Extension we're looking for, needs period
 * @param $dir Directories that are allowed, see hc-config.default.php
 */
function scan_dirs_for_pages($ext, $allowed_dirs) {
    $files = array();
    if (is_array($ext)) {
        foreach ($ext as $i => $e) $files[$i] = array();
    }
    foreach ($allowed_dirs as $dir => $recursive) {
        $pages = scan_for_pages($ext, $dir, $recursive);
        if (is_array($ext)) {
            foreach ($ext as $i => $e) {
                $files[$i] = array_merge($pages[$i], $files[$i]);
            }
        } else {
            $files = array_merge($pages, $files);
        }
    }
    return $files;
}

?>