Skip to content

Quick Start

Jump to bottom
cepharum GmbH edited this page Apr 30, 2015 · 9 revisions

About Some Basic Concepts

File System

txf basically separates code of framework from code of any application relying on it. This way it is possible to put several applications on a server sharing single installation of txf as a common code base.

-+ <web folder>
 +-- txf
 +-- app1
 +-- app2

Any application is considered to extend code provided by txf. If you implement a new class or design it may either reside in that application's folder or in folder txf so all applications can use it. The same applies for configuration files and templates.

Configuration

txf works with configuration files that may be extended arbitrarily. Configuration of a txf application is built from a cascading set of configurations. The common base is given in txf/config/default/default.xml. This base may be overloaded by more specific configuration files with some of them being selected explicitly while the default configuration is loaded implicitly. Every application may have its own default configuration either residing in folder txf to have a single point of configuration or in separate config-folders per application. Such specific configuration files aren't replacing but extending default configuration.

Scripts

Accessible server-side scripts are put into an application's root folder. A script file in folder <webroot>/app1/home.php will be available at URL http://yourhost.com/app1/home. Scripts are not to be invoked directly but using some wrapper script selected by rewriting (see configuration of web servers). Thus scripts don't need to bootstrap txf and they don't have to call some final rendering to generate output. This is why the simple "Hello World!" example is actually as simple as this:

<?php
de\toxa\txf\view::main( "Hello World!" );

In opposition to this short example you are encouraged to explicitly put scripts into namespace de\toxa\txf as it simplifies use of txf code.

Due to wrapping scripts the runtime has been set up for e.g. autoloading classes already. That's why you may instantly start with using txf library code. In this example the class view is used to append some string to some viewport called main. After this the script ends which is causing the wrapping code to implicitly invoke output generation mapping content of viewports into regions to be embedded in templates rendering final output. That's why even this simple script isn't rendering plain text, but a well-formed HTML document.

Output

As demonstrated before scripts always render HTML output from viewports. However, any direct output is captured as well. That's why script may render code without regards to class view and viewports managed there.

<?php
namespace de\toxa\txf;
var_dump( "Hello World!" );

This will generate HTML document containing output of var_dump(). If your script is rendering something else but HTML you might disable implicit output by either rendering explicitly by invoking view::render() or by invoking view::engine()->disableOutput().

Flashing

Scripts might enqueue content to be included with upcoming output generated by current or any following script. This is very useful in cases when a script is e.g. processing input and redirecting to some other script or if some library code is trying to inform user no matter what using script is about to do. This kind of content is called a flash and might be generated using view::flash().

<?php
namespace de\toxa\txf;
view::flash( "Hello World!" );

Basically, this generates HTML document putting "Hello World!" in a different part of rendered document. The essential difference is obvious in a more complex example involving two scripts. First there is home:

<?php
namespace de\toxa\txf;
view::flash( "You've got redirected!" );
txf::redirectTo( "start" );

Next there is another script start in file <webroot>/app1/start.php:

<?php
namespace de\toxa\txf;
view::main( "Hello World." );

First script isn't rendering any output itself due to redirecting client browser to second script. That second script is then generating output containing "You've got redirected!" as a flash and "Hello World." the same way as before.

Flashes may take type of flash as second argument selecting one of several probable lists of flashes. Every call of view::flash() is adding another entry to the selected list of flashes. On generating output all flashes are grouped by those lists and included on rendering.

<?php
namespace de\toxa\txf;
view::flash( "Your input was missing!", "error" );
txf::redirectTo( "start" );

Micro Templates

txf encourages to use templates for rendering output including structural information. The class markup is providing access on templates generating commonly useful HTML fragments.

<?php
namespace de\toxa\txf;
view::main( markup::h1( "Hello World!" ) );
view::main( markup::bullets( array( "I", "am", "a", "list!" ), "someTypeMarker" ) );

Templates in General

txf comes with a bunch of templates ready to use. As with configurations and codes any application and any theme may substitute more specific versions of those templates or add new ones to use. Templates are located using a similar fallback system preferring application- and theme-specific templates over common templates of default theme as provided as part of txf. The distributed engine is processing PHP templates.

Parameters

Selectors

Scripts may take parameters as usual. However, using "selectors" is an often preferred way. Selectors are segments of requested URL's pathname appended to the invoked script's name. The set of selectors may be accessed using magic properties of class application.

<?php
namespace de\toxa\txf;
view::main( markup::h1( "Hello " . _1(application::current()->selectors[0], "World") . "!" ) );

On requesting this script using URL http://yourhost.com/app1/home/cepharum the generated output will be

Hello cepharum!

You may append as much selectors as you like.

Query Parameters

In addition any script may take parameters the usual way: The URL's query is parsed as a sequence of key-value-pairs (which is efforted by PHP, of course). However, txf comes with a class input wrapping all access on those parameters (as well as related parameters in body of POST requests) providing several benefits such as implicit auto-typing and input validation, default values, input persistence and session integration.

Default Values and Parameter Persistence

<?php
namespace de\toxa\txf;
$name = input::get( "name", "World" );
view::main( markup::h1( "Hello " . $name . "!" ) );

Using URL /app1/home will generate output

Hellow World!

for expected input parameter was missing and thus provided default was returned instead. Using URL /app1/home?name=cepharum will generate output

Hello cepharum!

Now using URL /app1/home again will keep generating output

Hello cepharum!

because input::get() was automatically writing previously given value into server-side session. This may be prevented by using different method for accessing parameter:

<?php
namespace de\toxa\txf;
$name = input::vget( "name", "World" );
view::main( markup::h1( "Hello " . $name . "!" ) );

The v in method's name vget stands for volatile. However, this is preventing input from writing actual input parameters to session, only. It isn't dropping any parameters existing there due to using input::get() before.

Validation and Optional Parameters

Class input comes with a set of predefined input validators that implicitly deliver values of proper type. The validator is selected in third argument to method input::get().

  • input::FORMAT_STRING is the default validator, actually not validating that much.
  • input::FORMAT_KEYWORD is validating strings containing usual keywords - starting with a letter or underscore followed by zero or more letters, digits or underscores.
  • input::FORMAT_INTEGER is validating input to be integer value returning actual integer on match.
  • input::FORMAT_BOOL is validating input to be boolean value ... including literal representations like 0, 1, no, yes, on, off, y, n ... returning actual boolean on match.
  • input::FORMAT_GUID is validating input to be UUID in hex format.
<?php
namespace de\toxa\txf;
$age = input::vget( "age", null, input::FORMAT_INTEGER );
var_dump( $age )

Requesting this script using /app1/home?age=34 results in output

int(34)

Using some invalid URL like /app1/home?age=SELECT+bad+FROM+table results in error due to input is missing default, actual input is invalid according to selected validator and parameter is implicitly considered required parameter. Parameters might be optional, of course:

<?php
namespace de\toxa\txf;
$age = input::vget( "age", null, input::FORMAT_INTEGER, true );
var_dump( $age )

This is rendering

NULL

The provided input is still considered invalid, but there is no error for the parameter might pass the whole configured chain of input sources without retrieving any actual input.

Custom Validators

Third argument may take string containing Perl-compatible regular expression to be used for validation, always resulting in a string on matching. Further options include providing custom callbacks for preparing input values prior to validation and/or for converting validated input to some specific type of value.

Sources

Input processing always relies on a chain of input sources that can be adjusted and extended by configuration and by runtime code. By default input processing checks these sources sequentially:

  1. If request is a POST-request: $_POST
  2. $_GET
  3. server-side session for persistent parameters
  4. configuration file (yes, default parameters might be defined in configuration, too)
  5. default given in arguments to input::get() or input::vget()

Forms

txf includes a separate class for describing and processing forms without writing HTML. This includes some very basic support for preventing XSRF attacks.

$form = html_form::create( $formName )
  ->setTexteditRow( 'name', _L('login name') )
  ->setPasswordRow( 'token', _L('password'), '' )
  ->setButtonRow( 'submit', _L('Authenticate'), 'login' )
  ->setButtonRow( 'submit', _L('Cancel'), 'cancel' );

if ( $form->hasInput() ) {
    if ( input::vget( 'submit' ) === 'login' ) {
        $name = input::vget( 'name', null, '/^[a-z]+$/' );
        // process form ...
    }
}

view::main( $form );

See those invocations of _L()? txf comes with a set of "shortcut methods" that mostly map on static methods for sake of convenience. _L() is a shortcut enabling localization of strings basically working with a gettext-compatible system. We've used a shortcut before: _1() is a method returning its first non-null argument.

Server-Side Sessions

txf includes class session managing server-side sessions including scopes and encryption. Every script might ask for session space valid in scope of current application for sharing information between scripts. A script may have its separate space in session as well. Presuming proper configuration of txf and PHP on your web server sessions are always encrypted on server implicitly. PHP usually writes session data to files on server. txf is adding session handler for encrypting those files using mcrypt library of PHP. The encryption relies on information stored in a client's session cookie so decryption doesn't work without that session cookie's value.

Clone this wiki locally