Fork me on GitHub

eliza

eliza is a set of API designed to simplify the storage of information for web sites and applications. The concept is kiss (Keep It Simple Stupid!) feed classes define how information is stored, which eliza uses to create collections of feeds ready to be echoed.

What she features

Basic usage

First of all, you need to include the class autoloader and some basic definitions for eliza, you do this by including the main file eliza.php found in the root directory of this project.


    require 'eliza/eliza.php';  // includes eliza class autoloader and base definitions
            

Then, basically, all you need to work with eliza are two files, a feed class and a html template or page (and some stored information, of course).

An example of feed:

            
    class AFeed extends eliza\XMLDocument {
        public $AValue;
    }
            

An example of page:


    <?php 
    
        include 'eliza.php'; 
        eliza\Presentation::buffered();
    
    ?><!DOCTYPE html>
    <html lang="en">
        <head>
            <meta charset="utf-8">
        </head>
        <body>
            [AFeed /]
        </body>
    </html>
            

The above is a working example with a page that will show a list of values stored into xml files. This may very well be, but you should be aware of the methods and interfaces that lie underneath if you wish to have more control over things (see How to query feeds and How to manage collectionse).

How to query a feed

There are three main contexts in which you may want to query a feed: inside HTML content, from JavaScript or directly inside a PHP implementation.

in PHP

There are several PHP methods to invoke a feed collection, you may wish to choose the one that suits you better. In any case, you should remember that the origin implementation for the querying method is ::Feed($_args), defined by the feed you are invoking.

When the feed name is known:


    File::Feed($_args); // invoked directly from feed class
    eliza\Feed::File($_args) // loads feed, then calls the above method
            

If the feed name changes dynamically (inside variable):


    eliza\Request::feed($_feed, $_args); // used to dynamically invoke feeds
            

in JavaScript

It is possible to query a feed asynchronously using plugins/ElizaService.js This JavaScript interface reflects the querying method and all the collection methods applicable.

in HTML

Pseudo-tags are a simplified way to invoke and manage a collection of a particular feed. For example:


    [File /]{first} // will output the first file from the root directory
            

In order to use pseudo-tag correctly you have to make sure that the feed you wish to invoke is a valid one (see How to write a feed).

Pseudo-tags use the square bracket notation, with a slash before the closing bracket, for the feed invocation and braces to apply collection methods (see How to manage collections). The feed arguments are passed within the square brackets separated by an empty space; while parameters for collection methods are passed within the braces following the name of the method and a semi-colon, and, separated by a comma. Like so:


    [Feed arg1 arg2 /]{method1:arg1,arg2 method2:arg1,arg2}
            

How to write a feed

Writing a new feed is not a difficult endeavour, since a feed is basically the description of an item you wish to store, it will be clearer further on, but you should already be familiar with it if you know OOP. The most important aspect of a feed is the ability to query itself, in fact a querying method must be declared and implemented in order for a feed to be a valid one.

Another requirement for a feed to be valid is to extend eliza\Feed class, which also provides a unique Id for the feed.

Querying method (::Feed($_args))

A feed class has to declare and implement its querying method, which should return a collection of feeds of the self type (class in which the method is implemented).

The querying method must be declared public static in order for it to be accessible by eliza.


    public static Feed($_args) {
    
        #1 create an empty collection
        $Collection = new eliza\Collection();
        
        #2 add one or more feeds of the self type
        $Collection->append(new self());
        
        #3 return the collection of feeds
        return $Collection;
    }        
            

You should, of course, model the implementation to your needs (e.g.: database queries, service invocation, file access, ...). It is important, however, that you remember to return a collection; the collection may be empty, but instantiated nonetheless.

If you do not wish to bother with the querying implementation for your feeds you can always extend the provided basic feeds: File, FileContent, Image, XMLDocument, HTMLDocument

Basic feeds

Some basic feeds have already been implemented for you, these feeds offer some basic functionality. Of course, you can extend these feeds in order to customize the logic to your needs.

eliza\File

File is used to list the content of a directory. File can also be used to describe any file stored on the accessible file system.

eliza\FileContent

FileContent extends File adding a method to read and write the content of a particular file.

eliza\Image

Image extends File providing the ability to generate a thumbnail in case a file uses a recognized image format (i.e.: jpg, gif, png, bmp, ico). The HTML source generated by this feed class will show a thumbnail link to the original image file.

eliza\HTMLDocument

HTMLDocument extends File adding only a property which contains the content of the file.

eliza\XMLDocument

XMLDocument can be used to store multiple feeds of the same type, every item is described by its own xml file.

How to manage collections

A collection is basically a way to neatly organize a list of item, the collection interface offers many useful methods to manage your feeds throughout an application or website.

Classes

eliza classes are all defined in the namespace eliza\.

eliza\GlobalContext

This is a single ton class holding a collection of instances for all the PHP globally accessed variables (i.e.: $_GET, $_POST, $_FILES, $_SESSION, $_SERVER) and in particular the global configuration for eliza.

Global variables are accessible from anywhere in the code by invoking the eliza\GlobalContext class, and are read-only:


    eliza\GlobalContext::Get()->id; // returns $_GET['id']
    eliza\GlobalContext::Post()->comment; // return $_POST['comment']
    eliza\GlobalContext::Files()->upload; // returns $_FILES['upload']
    eliza\GlobalContext::Server()->HTTP_REFERER; // return $_SERVER['HTTP_REFERER']
            

For ::Session() things are, of course, a bit different since you may need to set a session variable. This is done by passing an array as argument for the method ::Session().


    eliza\GlobalContext::Session()->UserId; // returns $_SESSION['UserId']
    eliza\GlobalContext::Session(array(
        'UserId'=>'TheMaster'
    )); // sets value of $_SESSION['UserId']
            

Only the method ::Session() can set variables in the global context. This method automatically starts a session if necessary.

Global configuration (config.php)

The global configuration is a Collection of values that can be access globally by eliza. The configuration is defined in the file config.php.


    eliza\GlobalContext::Configuration()->Roles->eliza; // returns $cfg['Roles']['eliza']
            

You can if you wish edit directly the config.php file found with eliza, however I recommend making a copy of the file and save it in your document root, this way eliza will overwrite the default configuration with your own config.php. If a setting is not defined in your configuration then the default is used.

eliza\Presentation

This class contains mainly utility methods for the presentation of content within your pages or application. Two straightforward methods for buffering and caching content can be called from this class:


    eliza\Presentation::buffered(); // buffers the output generated after this call
    eliza\Presentation::cached(); // will buffer and cache the output generated after the call
            

But, the main role of this class is to parse a buffered output and intercept any pseudo-tag. The method ::replaceHTMLFeedReference($_content_with_pseudo_tag) will, in fact, replace all pseudo-tags with some dynamically generated content.

When a page is buffered using the ::buffered() all pseudo-tags will be automatically parsed.

eliza\Request

It is possible, using the method ::http($_url, $_request, $_method), to send a request to a remote address; the method ::feed($_feed, $_args) is an alternative way to invoke feeds from a feed name.

A more important aspect of this class is the ability to manage privileges throughout your application or website.

roles and permissions

Errors and exceptions

Errors and exceptions can be fired by calling the method oops($_message), and a warning page with report will be showed.

versions

eliza was coded by