Elefant Cheat Sheet

Getting Started

These are the steps to get Elefant up and running.
git clone http://github.com/jbroadway/elefant.git
Point a virtualhost to the new elefant folder
cd elefant
chmod -R 777 cache conf css files install layouts
./conf/elefant install or example.com/install/ via web

Utilities

./conf/elefant build-app <name> Generate app skeleton
./conf/elefant backup <path> Backup your website
./conf/elefant export-db <file> Backup your database
./conf/elefant List all available commands

Folder Structure

apps Your applications
cache Cached templates
conf Configuration files
css Stylesheets
files Uploaded files
index.php Front controller
install Web installer
js Javascript files
lang Translations
layouts Design templates
lib Core classes
tests Unit tests

Request Routing

/ →   conf('General', 'default_handler')
/appname →   apps/appname/handlers/index.php
/appname/handler →   apps/appname/handlers/handler.php
/appname/handler/extra →   apps/appname/handlers/handler/extra.php
Cascade occurs in reverse order until a matching handler is found.

App Structure

apps/appname/
             conf Configuration files
             forms Form validations
             handlers Request handlers
             lib Custom classes
             models Data models
             views App templates

Available Objects

These are made available inside handlers.
$this Controller object
$memcache Memcache object
$page Page object
$tpl Template object

Core Classes

Useful properties, methods, and usage patterns of the core classes.

Controller

->run($uri, $data=array()) Resolves and returns the output of a handler.
->handle($handler) Returns the output of a handler by file name.
->restful($obj) Create a RESTful API from an object.
->redirect($uri) Redirect the current request to $uri.
->hook($type, $data) Run any handlers assigned to a hook type.
->error($code=404, $title, $msg) Trigger the default error handler.
->params($one, $two, ...) Retrieve specified request parameters.
->request_method() Get the request method.
->get_put_data() Get data from a PUT request.
->get_raw_post_data() Get the raw data from a POST request.
->flush($data) Flush chunked data to client.
->is_https() Check if using HTTPS
->force_https() Redirect to HTTPS if using HTTP.
->force_http() Redirect to HTTP if using HTTPS.
->require_login() Require authentication to continue.
->require_admin() Require admin auth to continue.
->add_notification($msg) Add a notification for the current admin.

Direct-to-database helper functions

All functions except db_error() and db_lastid() accept $sql plus an array or variable number of values for replacement of placeholders, for example:
$res = db_execute('select * from mytable where id = ?', $id);
db_execute() Execute a statement and return true/false.
db_single() Fetch a single object.
db_shift() Fetch the a single value from the first result returned.
db_fetch_array() Fetch an array of all result objects.
db_shift_array() Fetch an array of a single field.
db_pairs() Fetch an associative array of two fields.
db_lastid() Get the last inserted id value (int).
db_error() Get the last error message, or false if no error.

Form

$f = new Form($method, $rules) Constructor method.
if ($f->submit()) {
  // handle form
}
Is the form submitted and valid?
Form::verify_value($value, $type, $validator) Validate any data value.
$f->merge_values($obj) Merge $_GET or $_POST values with an object for pre-filling a re-rendered form.
$f->failed = array() Fields that failed validation.
$f->method = 'post' Required request method.
$f->rules = array() Validation rules.
$f->verify_csrf = true Whether to prevent CSRF attacks.
$f->error = false The reason submit() failed to pass.

I18n

i18n_get($str) Translate a string into the current language.
i18n_getf($str, $vals) Like i18n_get() with vsprintf().
$language The current language.
$locale The current locale.
$charset = 'UTF-8' The current language's character set.
$fullname The full name of the current language.
$url_includes_lang Whether the URL includes the language, e.g., /fr/index.
$new_request_uri The URL with the prefixed language removed.
$negotiation Negotiation method used to determine language.
$error Any error that occurs in the class.

Model

Usage:
class Mytable extends Model {
  /* custom methods */
}
Create model for mytable db table.
$m = new Mytable(array(
  'name'=>'John',
  'age'=>30
));
$m->put();
Insert a new object.
echo $m->id; The ID from the inserted object.
$m = new Mytable(1); Fetch object by ID.
$m->age = 31;
$m->put();
Update the object.
$obj = $m->orig ();
Return the original (non-Model) object.
$m->remove() Delete the object.
$res = $m->query()
  ->where('age > 30')
  ->order('name asc')
  ->fetch(20, 0);
Build a custom query and fetch the results.
$res is an array of Mytable objects.
Additional fetch methods:
->fetch_assoc() Fetch a key/value pair of two fields.
->fetch_field() Fetch an array of one fields.
->fetch_orig() Fetch the original (non-Model) objects.

Page

->render() Renders the page with its layout templates.
->add_script($script, $to='head') Add script to $head or $tail.
$body = '' Body content.
$head = '' Extra scripts for <head> section.
$tail = '' Extra scripts before </body>.
$layout = 'default' Design template.
$title = '' Page title.
$menu_title = '' Alternate navigation title.
$window_title = '' Alternate browser window title.

Template

->render($template, $data) Render a template file.
->run_includes($template) Run and include handlers in a string.
->sanitize($value) Sanitize a string for safe output. Prevents XSS.
$charset = 'UTF-8' Template character set.
{{ var }} In-template variable substitution.
{{ var|filter_name }} Variable filtering.
{" Text "} In-template translatable text.
{% foreach foo %}
{% end %}
In-template looping.
{% if foo %}
{% elseif bar %}
{% else %}
{% end %}
In-template conditional logic.
{! app/handler?param=value !} Call a handler from a template.
{# app/handler?param=value #} Hard-code handler output in a template.

User

Extends Model with the following:
User::encrypt_pass($plain) Generates a random salt and encrypts a string.
User::require_login() Checks if a user has been logged in.
User::require_admin() Checks if a user has been logged in as an admin.
User::is_valid() Check if the user is valid.
User::logout($redirect_to) Log the current user out.