Class Enrober

Description

Located in /enrober.php (line 105)


	
			
Method Summary
static object singleton ()
void add_cache_modifier (string $modifier)
void add_css (string $filepath, [array $config = null])
void add_desc (string $desc)
void add_filter (string $filter, [bool $filter_mode = ENROBER_FILTER_BODY])
void add_js (string $filepath)
void add_keywords (mixed $keywords)
void add_tag (string $name, string $value, [integer $location = 0], [bool $sanitize = true])
void force_cache (bool $cache)
void force_mobile (bool|null $force)
array get_themes ()
string get_title ()
void go ([string $title = ''])
bool is_cached ()
false|array is_maintenance ()
bool is_mobile ()
boolean is_xhr ()
mixed m ()
void manual_cache (bool|int $valid)
void set_theme ([string $theme = null])
void url ([string $url = null])
Methods
static singleton (line 254)

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.

  • access: public
static object singleton ()
add_cache_modifier (line 456)

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.

  • access: public
void add_cache_modifier (string $modifier)
  • string $modifier: A string that identifies this version of the page. Can contain letters, numbers and underscores.
    1.  <?php
    2.     // In this example we'll build a store finder that takes a zipcode and
    3.     // returns information for fictional stores in our database
    4.  
    5.     // Get the zipcode the user entered
    6.     $zip $_REQUEST['zip'];
    7.  
    8.     // Strip out any non-numeric characters
    9.     $zip preg_replace('/[^0-9]/'''$zip);
    10.  
    11.     // Call a function that does some extra validiation
    12.     if (is_valid_zip($zip)) {
    13.         // According to our rules it's a valid zipcode,
    14.         // instruct Enrober to cache a different version of
    15.         // the page for this zipcode
    16.         $enrober->add_cache_modifier('zip' $zip);
    17.     }
    18.  
    19.     // Start buffering the page with Enrober
    20.     $enrober->go("Stores in the $zip zipcode");
    21.  
    22.  
    23.  
    24.     // Everything below here is for the sake of making the example complete
    25.     // and has nothing to do with the use of add_cache_modifier()
    26.  
    27.  
    28.  
    29.     if (is_valid_zip($zip)) {
    30.  
    31.         echo "<h1>Stores in the $zip zipcode</h1>";
    32.  
    33.         // Flush the h1 before the database query
    34.         ob_flush();
    35.         flush();
    36.  
    37.         // Connect to our database
    38.         $mysqli new mysqli('localhost''db_user''db_password''db_name');
    39.  
    40.         // create a prepared statement to get the information from the database
    41.         if ($stmt $mysqli->prepare('SELECT name, address, phone,' .
    42.                 'hours FROM stores WHERE zip=?')) {
    43.  
    44.                 $stmt->bind_param('s'$zip);
    45.                 $stmt->execute();
    46.  
    47.                 $stmt->bind_result($store_name$store_address$store_phone);
    48.  
    49.                 // Loop through the results and display them
    50.                 while ($stmt->fetch()) {
    51.                     echo '<div class="store">';
    52.                     echo '<h2>' htmlentities($store_name'</h2>';
    53.                     echo '<ul>';
    54.                     echo '<li>Address: ' htmlentities($store_address'</li>';
    55.                     echo '<li>Phone: ' htmlentities($store_phone'</li>';
    56.                     echo '</ul>';
    57.                     echo '</div>';
    58.                 }
    59.  
    60.                 $stmt->close();
    61.         }
    62.  
    63.         $mysqli->close();
    64.     else {
    65.         echo '<p>Sorry, no stores found in your area</p>';
    66.     }
    67.  ?>
add_css (line 1252)

Adds a CSS file to be inserted at the %css% tag.

If a stylesheet is added a second time it is ignored.

  1.  <?php
  2.  // Linked as a regular stylesheet
  3.  $enrober->add_css('extra.css');
  4.  
  5.  // Linked as a print-only stylesheet
  6.  $enrober->add_css('print.css'array('media' => 'print');
  7.  
  8.  // Linked as an alternative stylesheet
  9.  $enrober->add_css('alternate.css'array('rel' => 'alt''title' => 'Alternate layout');
  10.  
  11.  // Not added because it is a duplicate
  12.  $enrober->add_css('extra.css');
  13.  ?>

  • access: public
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.
add_desc (line 642)

Adds a <meta> description to the page.

Calling add_desc() a second time will replace any previous values.

  • access: public
void add_desc (string $desc)
  • string $desc: What to put in the <meta> description tag
    1.  $enrober->add_desc('This is a page description.');
    2.  $enrober->add_desc('This description just replaced the old one.');
add_filter (line 1360)

Adds a content filter to be applied with ob_start()

  • since:

    1.2.0 More granularity in where filters are applied. True/false have been deprecated.

    1.  <?php
    2.  // Apply the HTML Tidy callback to the body of the
    3.  // page to fix any broken markup (Requires the Tidy
    4.  // extension for PHP).  The entire document is processed as one piece.
    5.  $enrober->add_filter('ob_tidyhandler'ENROBER_FILTER_EVERYTHING);
    6.  
    7.  // This filter function collapses any whitespace
    8.  // between HTML tags down to a single space
    9.  function collapse_whitespace($in{
    10.      return preg_replace('/>\s+</','> <'$in);
    11.  }
    12.  
    13.  // add our custom filter, filtering everything
    14.  // including the header and footer.  Each section is filtered by itself.
    15.  $enrober->add_filter('collapse_whitespace'ENROBER_FILTER_ALL);
    16.  
    17.  // Censor the words foo, bar and baz.
    18.  function censor($in{
    19.      $out str_replace('foo''***'$in);
    20.      $out str_replace('bar''***'$out);
    21.      $out str_replace('baz''***'$out);
    22.      return $out;
    23.  }
    24.  
    25.  $enrober->add_filter('censor')// Implicitly only filtering the body of the page.
    26.  ?>

  • access: public
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.

add_js (line 1300)

Adds a JavaScript file to be linked via the %js% tag.

If a script is added a second time it is ignored.

  • access: public
void add_js (string $filepath)
  • string $filepath:

    The url of the JavaScript file to add absolute or relative to the calling script.

    1.  <?php
    2.  $enrober->add_js('http://cdn.example.com/1.5/jquery.min.js')// Import jQuery from a CDN
    3.  $enrober->add_js('blink.js')// Add a JavaScript file that is in the same
    4.                                // directory as the page using it.
    5.  ?>

add_keywords (line 619)

Adds <meta> keywords to the page.

Multiple calls append to the list.

  • access: public
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

    1.  $enrober->add_keywords('keyword1,keyword2');
    2.  $enrober->add_keywords(array('keyword3''keyword4'));
    3.  // the %keywords% template tag will now output
    4.  // <meta name="keywords" content="keyword1,keyword2,keyword3,keyword4">

add_tag (line 1446)

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().

  1.  <?php
  2.  $enrober->add_tag('foo''bar')// Adds the text "bar" anywhere in the
  3.                                   // header or footer that "%foo%" appears
  4.  $enrober->add_tag('foo''bar'0)// Same as previous
  5.  $enrober->add_tag('foo''bar'1)// Adds the text "bar" only in the header
  6.  $enrober->add_tag('foo''bar'2)// Adds the text "bar" only in the footer
  7.  
  8.  // By default anything added to a theme tag is run through htmlentities()
  9.  // to prevent XSS attacks. If you need to use HTML you can set the $sanitize
  10.  // parameter to false but if you are including any user generated content
  11.  // in it you will need to sanitize it yourself!
  12.  $enrober->add_tag('foo''<em>bar</em>')// Adds the text "bar", wrapped
  13.                                            // in a text representation of em tags:
  14.                                            // "&lt;em&gt;bar&lt;/em&gt;"
  15.  $enrober->add_tag('foo''<em>bar</em>'0true)// Same as previous
  16.  $enrober->add_tag('foo''<em>bar</em>'0false)// Adds the text "bar",
  17.                                                      // wrapped in em tags:
  18.                                                      // "<em>bar</em>"
  19.  ?>

  • access: public
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!
force_cache (line 1501)

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.

  • access: public
void force_cache (bool $cache)
  • bool $cache: Should caching be enabled for this page? True = Cache, False = Don't cache
force_mobile (line 765)

Forces the mobile or non-mobile version of a page to be displayed.

  • since: 1.1.0
  • access: public
void force_mobile (bool|null $force)
  • bool|null $force: True === force mobile, False === force non-mobile, null === revert to auto-detect
get_cache_file_path (line 281)

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.

  1.  $enrober->set_theme();
  2.  $cache_path $enrober->get_cache_file_path();

  • return: The path to the cache file
  • access: public
string get_cache_file_path ()
get_themes (line 351)

Returns a list of themes currently available.

  1.  <?php
  2.  echo '<ul>';
  3.  // list currently installed themes
  4.  foreach($enrober->get_themes(as $t{
  5.      echo "<li>$t</li>";
  6.  }
  7.  echo '</ul>';
  8.  ?>

  • return: An array containing the names of all of the themes installed in this copy of Enrober
  • since: 1.1.0
  • access: public
array get_themes ()
get_title (line 373)

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).

  • since: 1.2.0
  • access: public
string get_title ()
go (line 864)

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').

  1.  <?php
  2.  $enrober->go()// Invoke Enrober without a page title
  3.  $enrober->go('Example')// Invoke Enrober with the page title 'Example'
  4.  ?>

  • access: public
void go ([string $title = ''])
  • string $title: If specified this string will be inserted into a <title> tag
is_cached (line 512)

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

  • access: public
bool is_cached ()
is_maintenance (line 535)

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.

  • since: 1.2.0
  • access: public
false|array is_maintenance ()
is_mobile (line 740)

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 ()
is_xhr (line 550)

Determines if the current request is being served as a XHR request.

  • since: 1.2.0
boolean is_xhr ()
m (line 692)

Examines the user agent string to try to determine whether the client is a mobile device.

  1.  $mobile $enrober->m();
  2.  var_dump($mobile);
  3.  
  4.  // When viewed on through a non-mobile browser, returns:
  5.  // bool(false)
  6.  
  7.  // When viewed via Safari on an iPhone, returns:
  8.  // array(8) {
  9.  //     ["iphone"]=>
  10.  //     bool(true)
  11.  //     ["android"]=>
  12.  //     bool(false)
  13.  //     ["blackberry"]=>
  14.  //     bool(false)
  15.  //     ["palm"]=>
  16.  //     bool(false)
  17.  //     ["netfront"]=>
  18.  //     bool(false)
  19.  //     ["safari"]=>
  20.  //     bool(true)
  21.  //     ["opera"]=>
  22.  //     bool(false)
  23.  //     ["windows"]=>
  24.  //     bool(false)
  25.  // }

  • return: Contains information about mobile user agents. If the user agent was not detected as mobile, it is set to false, otherwise it will be an array with the following keys set to true or false depending on whether or not the device appears to match the device type.
    • iphone: Device appears to be an iPhone
    • android: Device appears to be an Android
    • blackberry: Device appears to be an Black Berry
    • palm: Device appears to be a Palm device
    • windows: Device appears to be a Windows Phone or Windows CE device
    • netfront: Device appears to be running the NetFront browser
    • safari: Device appears to be running the Safari browser
    • opera: Device appears to be running the Opera browser
  • since: 1.1.0
  • access: public
mixed m ()
manual_cache (line 585)

Manually specify whether or not the file's cache should be invalidated

  • access: public
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.
    1.  $enrober->manual_cache(true)// cache file is assumed to still be good no
    2.                                // matter how old it is
    3.  $enrober->manual_cache(false)// cache file is assumed to be expired and
    4.                                 // must be re-processed
    5.  $enrober->manual_cache(mktime(0,0,0,4,1))// cache file is assumed to be
    6.                                             // expired if the current date is
    7.                                             // after midnight April 1st of the current year
set_theme (line 319)

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.

  1.  $enrober->set_theme('pressy')// Change the theme from the default to the 'pressy' theme
  2.  $enrober->go();
  3.  
  4.  // or
  5.  $enrober->set_theme()// Explicitly use the default theme.
  6.  $enrober->go();

  • since: 1.1.0 Previously the theme could be set as a second parameter to go(), but it is now required that you use set_theme().
  • access: public
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.
url (line 1483)

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.

  1.  $enrober->url('index.php');
  2.  // or
  3.  $enrober->url('/');
  4.  // or
  5.  $enrober->url('http://www.example.com/');

void url ([string $url = null])
  • string $url: The url to set as the canonical url.

Documentation generated on Wed, 04 May 2011 12:07:58 -0700 by phpDocumentor 1.4.3