Creates the $enrober singleton object.
Automatically called when enrober.php is included. The created object is assigned to the $enrober variable. Because Enrober is a singleton, further calls to singleton() will result in a reference to the original object instead of a new instance.
static object
singleton
()
Adds a cache modifier.
Cache modifiers are used to differentiate between different versions of a page. This can be useful if you want to cache pages show different information when they have certain query string parameters, if you want to create different versions of the page based on the user agent, etc.
void
add_cache_modifier
(string $modifier)
-
string
$modifier: A string that identifies this version of the page. Can contain letters, numbers and underscores.
<?php
// In this example we'll build a store finder that takes a zipcode and
// returns information for fictional stores in our database
// Get the zipcode the user entered
$zip = $_REQUEST['zip'];
// Strip out any non-numeric characters
// Call a function that does some extra validiation
if (is_valid_zip($zip)) {
// According to our rules it's a valid zipcode,
// instruct Enrober to cache a different version of
// the page for this zipcode
}
// Start buffering the page with Enrober
$enrober->go("Stores in the $zip zipcode");
// Everything below here is for the sake of making the example complete
// and has nothing to do with the use of add_cache_modifier()
if (is_valid_zip($zip)) {
echo "<h1>Stores in the $zip zipcode</h1>";
// Flush the h1 before the database query
// Connect to our database
$mysqli = new mysqli('localhost', 'db_user', 'db_password', 'db_name');
// create a prepared statement to get the information from the database
if ($stmt = $mysqli->prepare('SELECT name, address, phone,' .
'hours FROM stores WHERE zip=?')) {
$stmt->bind_param('s', $zip);
$stmt->execute();
$stmt->bind_result($store_name, $store_address, $store_phone);
// Loop through the results and display them
while ($stmt->fetch()) {
echo '<div class="store">';
echo '<ul>';
echo
'<li>Address: ' .
htmlentities($store_address) .
'</li>';
echo '</ul>';
echo '</div>';
}
$stmt->close();
}
$mysqli->close();
} else {
echo '<p>Sorry, no stores found in your area</p>';
}
?>
Adds a CSS file to be inserted at the %css% tag.
If a stylesheet is added a second time it is ignored.
<?php
// Linked as a regular stylesheet
// Linked as a print-only stylesheet
$enrober->add_css('print.css', array('media' =>
'print');
// Linked as an alternative stylesheet
$enrober->add_css('alternate.css', array('rel' =>
'alt', 'title' =>
'Alternate layout');
// Not added because it is a duplicate
?>
void
add_css
(string $filepath, [array $config = null])
-
string
$filepath: The url to the css file to be included. If the css file is in the same directory as the calling script only the filename needs to be specified.
-
array
$config: An array that allows you to add additional optional attributes to the link tag. These attributes are:
- 'media': Which media types the stylesheet should be applied to, 'all' by default.
- 'rel': The rel attribute of the <link> tag, 'stylesheet' by default can also be set to 'alternate stylesheet' to specify an alternate stylesheet. If set to 'alt' it will automatically be expanded to 'alternate stylesheet'.
- 'title': The title attribute for the link, most browsers that support alternative stylesheets will use this as a label in the stylesheet switching interface.
Adds a <meta> description to the page.
Calling add_desc() a second time will replace any previous values.
void
add_desc
(string $desc)
-
string
$desc: What to put in the <meta> description tag
$enrober->add_desc('This is a page description.');
$enrober->add_desc('This description just replaced the old one.');
Adds a content filter to be applied with ob_start()
void
add_filter
(string $filter, [bool $filter_mode = ENROBER_FILTER_BODY])
-
string
$filter: A string with the name of the filter function to use
-
bool
$filter_mode:
What part of the page should be filtered?
- ENROBER_FILTER_BODY - Filter the body of the page. If no filter mode is specified, this is used as the default.
- ENROBER_FILTER_HEAD - Filter the header of the template.
- ENROBER_FILTER_FOOT - Filter the footer of the template.
- ENROBER_FILTER_ALL - Adds a head, body and foot filter with one command.
- ENROBER_FILTER_EVERYTHING - Buffers the entire page and then applies your filter to the whole thing at once.
- ENROBER_FILTER_ALWAYS_HEAD - Filter the head. Happens at request time, even on cached pages.
- ENROBER_FILTER_ALWAYS_BODY - Filter the body. Happens at request time, even on cached pages.
- ENROBER_FILTER_ALWAYS_FOOT - Filter the foot. Happens at request time, even on cached pages.
- ENROBER_FILTER_ALWAYS_ALL - Adds a head, body and foot filter with one command. Happens at request time, even on cached pages.
- ENROBER_FILTER_XHR - Before an XHR request is returned it is run through any XHR filters. Ideal for returning XHR requests in different formats (JSON, XML, etc.)
- false - Synonym for ENROBER_FILTER_BODY (deprecated)
- true - Synonym for ENROBER_FILTER_ALL (deprecated)
Note: If a request is an XHR request, it is filtered with any body filters, all filters, XHR filters and always filters. Evertything filters are not run on XHR requests. Also "always" filters are always run last so care must be taken that you don't corrupt any data transformations done by a XHR filter, for instance insert non-escaped characters into JSON, or search and replace tag names or property names in XML, etc.
Adds a JavaScript file to be linked via the %js% tag.
If a script is added a second time it is ignored.
void
add_js
(string $filepath)
-
string
$filepath:
The url of the JavaScript file to add absolute or relative to the calling script.
<?php
$enrober->add_js('http://cdn.example.com/1.5/jquery.min.js'); // Import jQuery from a CDN
$enrober->add_js('blink.js'); // Add a JavaScript file that is in the same
// directory as the page using it.
?>
Adds <meta> keywords to the page.
Multiple calls append to the list.
void
add_keywords
(mixed $keywords)
-
mixed
$keywords:
What to put in the <meta> keywords tag. Either a string of comma delimited keywords or an array of keywords
// the %keywords% template tag will now output
// <meta name="keywords" content="keyword1,keyword2,keyword3,keyword4">
Adds a new theme tag.
Theme tags allow you to specify where things Enrober generates are injected into the theme. There are a number of built in tags:
- %title% - The page's <title> tag
- %desc% - The page's description <meta> tag
- %keywords% - The page's keywords <meta> tag
- %themepath% - The URI for the directory that the current theme is stored in, useful for including the theme's CSS file.
- %css% - Any <link> tags for CSS files added via $enrober->add_css()
- %js% - Any <script> tags for JavaScript files added via $enrober->add_js()
- %generated% - Inserts a "Generated on" or "Cached on" message depending on whether or not caching is enabled on the current page.
- %canonical% - Where in the head to insert the Canonical URL if one was set with $enrober->url()
- %site_name% - The value for ENROBER_SITE_NAME specified in enrober-config.php
- %tagline% - The value for ENROBER_TAGLINE specified in enrober-config.php
If you add your own tags to your templates you can then set their value for any particular page with add_tag().
<?php
$enrober->add_tag('foo', 'bar'); // Adds the text "bar" anywhere in the
// header or footer that "%foo%" appears
$enrober->add_tag('foo', 'bar', 0); // Same as previous
$enrober->add_tag('foo', 'bar', 1); // Adds the text "bar" only in the header
$enrober->add_tag('foo', 'bar', 2); // Adds the text "bar" only in the footer
// By default anything added to a theme tag is run through htmlentities()
// to prevent XSS attacks. If you need to use HTML you can set the $sanitize
// parameter to false but if you are including any user generated content
// in it you will need to sanitize it yourself!
$enrober->add_tag('foo', '<em>bar</em>'); // Adds the text "bar", wrapped
// in a text representation of em tags:
// "<em>bar</em>"
$enrober->add_tag('foo', '<em>bar</em>', 0, true); // Same as previous
$enrober->add_tag('foo', '<em>bar</em>', 0, false); // Adds the text "bar",
// wrapped in em tags:
// "<em>bar</em>"
?>
void
add_tag
(string $name, string $value, [integer $location = 0], [bool $sanitize = true])
-
string
$name: The name of the theme tag to define (sans %%)
-
string
$value: The value to insert at the new theme tag
-
integer
$location: Where to process the tag. 0 = Header and Footer, 1 = Header only, 2 = Footer only
-
bool
$sanitize: If true, the $value is run through htmlentities() before inclusion in the page. Set to false if you need to include HTML, but you will need to sanitize any user input you include yourself!
Manually turn on/off caching, overriding the ENROBER_CACHE constant from the config file.
When caching is turned on with force_cache(), normal caching rules apply. To guarantee that the cached version of a page gets returned when one exists use manual_cache() set to true.
void
force_cache
(bool $cache)
-
bool
$cache: Should caching be enabled for this page? True = Cache, False = Don't cache
Forces the mobile or non-mobile version of a page to be displayed.
void
force_mobile
(bool|null $force)
-
bool|null
$force: True === force mobile, False === force non-mobile, null === revert to auto-detect
Returns the complete file system path to the cache file for the current version of the calling script.
set_theme() must be called before get_cache_file_path() because the theme name is used to generate the cache file's filename.
string
get_cache_file_path
()
Returns a list of themes currently available.
<?php
echo '<ul>';
// list currently installed themes
echo "<li>$t</li>";
}
echo '</ul>';
?>
array
get_themes
()
Returns the title of the page as it was set with go() Useful inside of XHR filters if transforming data into another format (JSON, XML, etc).
string
get_title
()
Invokes Enrober's page wrapping; invoke after calling any of the other Enrober methods you want to use and before page content starts.
If you have not already added a ob_gzhandler output buffer when go() is invoked, Enrober will automatically call ob_start('ob_gzhandler').
<?php
$enrober->go(); // Invoke Enrober without a page title
$enrober->go('Example'); // Invoke Enrober with the page title 'Example'
?>
void
go
([string $title = ''])
-
string
$title: If specified this string will be inserted into a <title> tag
Figure out if there is a cached version of this file/theme/cache-modifier combo.
set_theme() must be called before is_cached() because it uses the theme name to figure out the name of the cache file
bool
is_cached
()
Returns information regaurding whether we are currently in maintenance mode, whether the current user is the maintenance user and whether the current page is accessable during maintenance mode.
If it is not maintenance mode, returns false. If maintenance mode is currently active, an array containing the following is returned:
- user - True if the current user has the ENROBER_MAINTENANCE_IP ip address,
false otherwise
- page - True if this page is allowed during maintenance, false if it is not.
false|array
is_maintenance
()
Determines if the page should be served as a mobile page.
A return value of true does not necessarily mean that the user agent is a mobile device, it is possible that force_mobile() has forced the mobile version. For a more definitive answer use m().
bool
is_mobile
()
Determines if the current request is being served as a XHR request.
boolean
is_xhr
()
Examines the user agent string to try to determine whether the client is a mobile device.
// When viewed on through a non-mobile browser, returns:
// bool(false)
// When viewed via Safari on an iPhone, returns:
// array(8) {
// ["iphone"]=>
// bool(true)
// ["android"]=>
// bool(false)
// ["blackberry"]=>
// bool(false)
// ["palm"]=>
// bool(false)
// ["netfront"]=>
// bool(false)
// ["safari"]=>
// bool(true)
// ["opera"]=>
// bool(false)
// ["windows"]=>
// bool(false)
// }
mixed
m
()
Manually specify whether or not the file's cache should be invalidated
void
manual_cache
(bool|int $valid)
-
bool|int
$valid: - If True assume the cached is still good, if False the file is old and should be regenerated, if an integer is supplied it is assumed to be a unix timestamp and compared to the cache file's timestamp to determine the cache file's validity.
$enrober->manual_cache(true); // cache file is assumed to still be good no
// matter how old it is
$enrober->manual_cache(false); // cache file is assumed to be expired and
// must be re-processed
// expired if the current date is
// after midnight April 1st of the current year
Override the default theme.
Can only be called once, subsequent calls will be ignored. If no $theme is provided, the default theme is explicitly set as the theme.
Certain methods (for example is_cached and get_cache_file_path) require that the theme be set before they are called or they may raise warnings or errors, in these cases call set_theme() (with no parameters if you want to use the default theme) to avoid errors.
If you are using set_theme(), it must be called before go(). go() uses the default theme if one has not been set before go() is called.
$enrober->set_theme('pressy'); // Change the theme from the default to the 'pressy' theme
// or
$enrober->set_theme(); // Explicitly use the default theme.
void
set_theme
([string $theme = null])
-
string
$theme: A string containing the name of the theme to wrap the page in. If not provided the value of the ENROBER_DEFAULT_THEME constant from the config file is used.
Sets/gets the canonical URL for the page to be inserted at the %canonical% tag.
If called with no arguments or with null, returns the current canonical url. If an empty string, removes the canonical url. If it is anything else it is set as the canonical url.
Google's webmaster central has more information about canonical URLs.
$enrober->url('index.php');
// or
// or
$enrober->url('http://www.example.com/');
void
url
([string $url = null])
-
string
$url: The url to set as the canonical url.