PHPLights : Documentation : Quickstart

From Linuxnetworks

Contents 1 Application structure 2 Calling the application 3 Implementing a controller with actions 4 Creating output

[edit] Application structure

The "app" directory in the phpLights package provides a good starting point for your new application. It contains the necessary directories and the entry point (index.php) with the bootstrapping code.

There are only a few files and directory which are absolutely necessary:

• index.php (start point)
• base.php (basic configuration)
• lib/ (for implemented classes controllers and models)
• template/ (for template files)
• template/base.php (basic view for output)
• template/error/internal.php (internal server error page)
• template/error/notfound.php (404 error page)

Optional files and directories are:

• config/ (configuration files)
• config/resource.php (available resources, e.g for databases)
• data/ (if needed)
• skin/ (css and image files)
• skin/default/css/debug.css (css for easy debugging)
• template/debug.php (view for easy debugging)

[edit] Calling the application

If the application is called without additional path information, defaults for controller and action are assumed. Therefore, the following URLs (assuming that "app" is the name of your application directory) are considered the same:

.../app
.../app/index.php
.../app/index.php/default
.../app/index.php/default/index

The first parameter after "index.php" specifies the controller, the second the action. By default, the class "DefaultController" is used and its "index" member function is called.

The first character of the first parameter (controller) is upper-cased and the string "Controller" is appended. Internally, the framework does a lookup for a .php file of this name in the lib/ directory of the application which must include a class of the same name. Contrary to the controller parameter, the action parameter is used unmodified to find a corresponding method name.

To fill your application with life, first implement the "index" method in the "DefaultController" class and add further public methods for more actions. The next step may include creating more controller classes with some methods implemented for providing more functionality.

[edit] Implementing a controller with actions

To get convenient access to often needed functionality, you should extend your own controller from the "LsController" base class. It provides usefull shortcuts for forwarding request to other controllers, creating new objects, adding views and creating subviews for generating the output, access configuration values and write messages to the log. The available functions are:

$this->forward( $controllername, $actionname );
$this->create( $classname, $interfacename, ... );
$this->addView( $viewname, $templatename );
$this->createView( $templatename );
$this->conf( $keypath, $defaultvalue = NULL );
$this->log( $message, $loglevel = LsLogger::Error );

Furthermore, you can access the complete context of the application which contains all necessary objects provided by for phpLights applications. There are shortcut functions available which return the objects:

LsFactory() 

creates class instances, $this->create() is an alias for LsFactory()->create()

LsLogger() 

log messages, $this->log() is an alias for LsLogger()->log()

LsConfig() 

get, add or remove configuration values, $this->conf() is an alias to LsConfig()->get()

LsRequest() 

provides access to user input and file uploads

LsResponse() 

holds HTTP header informations, cookies and views for generating output

LsUser() 

access to session data and authorization possibilities

LsDB() 

provides database connections via LsDB()->acquire()

LsTimer() 

enables performance measures via LsTimer()->add()

A basic application may look like this:

// get user input and make sure it is an integer (0 if not available)
$myval = LsResponse()->get 'request/myval', 0, LsStorage::Int );

// do something

// Add new view named 'vbody' with template 'app/template/default/index.php'
$vbody = $this->addView( 'vbody', 'default/index' );

// Add a variable named 'statusvar' to the 'vbody' view
$vbody->statusvar = 'Success';

[edit] Creating output

After you've implemented a small controller and the big business logic which makes your application useful, it's now time to generate the output shown to your users. You've already created one or more views and assigned some content to them so the output can depend on what you've added dynamically.

If you are using "LsViewPHP" class for your views (the default if nothing else is configured), the output is generated by the .php files in the template directory of your application. There must always be a "main.php" template as container for your views. It may provide the (X)HTML head and body and has markers where the available view output is placed. An example might be:

<html>
 <head>
  <title>My project</title>
 </head>
 <body>
  <?php $this->getView( 'vbody' )->display(); ?>
 </body>
</html>

This would create a HTML page which contains the output of the view "vbody" which we added in the index action of the controller. You can have many views in your template at different locations when you assign them in the controller via $this->addView(). Views can also contain subviews and theoretically there's no limit when nesting views.

The "vbody" view in our example (and all view in common) can contain values which were assigned by the controller inside the action methods, e.g. $vbody->statusvar = 'Success'. These variables are available in the template which belongs to the view ("default/index" for vbody):

<h1><?php echo $this->statusvar; ?></h1>

There are a many useful helper functions available as static methods in the helper class "LsVKit", e.g. for escaping the output:

<h1><?php echo LsVKit::escHTML( $this->statusvar ); ?></h1>

---

Back to Overview