TWERP is a bonehead-simple php framework for doing small database-backed websites. Frustrated with the gap between, on one hand, relatively massive frameworks or CMS's like Drupal, Mambo or CakePHP, and, on the other hand, raw PHP, I came up with TWERP.

I suppose you could do a quite substantial website using TWERP but it probably would be kinda stupid to do that. The limiting factor is really how many built in features you want, and how many different basic page types you need. If those needs are modest, there is no reason you couldn't build a TWERP site supporting thousands or millions of users and millions of records.

Features

  • Model-View-Controller framework.
  • Automatic framework generation of your app: get a real app running in 5 minutes, and start customizing it to your liking.
  • pick from 40 basic CSS page layouts to get started.
  • built in php templating system for defining your page views
  • built-in dispatcher to support routing of urls you specify to particular controller routines.
  • Completely open (that is, unimplemented) 'Model' errr, model. use sqlite, mySQL, text files, the alpha channel of an image file, whatever.

Really nothing else: there's not much to it.

Installing TWERP and creating your application framework.

  • Download and unpack twerp into some directory inside your web server tree.
  • create a directory for your app also in you webserver tree, -- called, say, 'yourapp' -- and set its permissions so it can be read and written by everybody (chmod 777).
  • Access with your browser http://{your.server.name}/twerp/make_new. (The first time you access twerp/make_new, you'll be asked to set a login and password; remember them! You'll need them to access twerp/make_new from then on.)
  • Fill in the simple form that twerp/make_new presents, specifying your new application directory, your selection of basic css template, and a few other simple settings. Hit 'go' and TWERP builds an application framework in your specified app directory.
  • access your new app from the web with http://{your.server.name}/yourapp -- you're happening already with a twerp sample framework, already customized to your app name and chosen css template.
  • Start writing code to bend the sample app into your own thing.

Tour of the files and directories in your TWERP-generated app directory.

  • .htaccess -- apache configuration for your TWERP app; defines the mod_rewrite settings to prettify your application URLs.
  • index.php -- holds the TWERP dispatcher; you won't need to edit this at all.
  • twerplib/ -- twerp library code; you don't need to edit this either unless you want to change TWERP itself.
  • app/ -- this directory holds the files you will be customizing to define your application.
    • config.inc -- set up various TWERP configuration parameters here, including the all-important $usermap[] array to bind URLs to your controllers and the $view_arg_names[] array to declare new views.
    • controllers.php -- define your controller routines here.
    • models.php -- define your database interface here, defining m_xxx() functions which implement your applications datamodel, the interface to you data that all your controllers and views will use.
    • views.php -- define your procedural view_xxx() routines here.
    • view_templates/ -- in this directory, define all your view xxx.tpl.php files.

Defining Controllers

Typically you'll define a c_xxx() controller routine in controllers.php for each unique type of page in your site, including form submission handler routines and AJAX handlers. in these handler routines you'll call model routines (defined in models.php) to update/access your database, and view routines (defined in views.php or view_templates/xxx.tpl.php) to put stuff on the screen.

How does TWERP go about calling your page controller routines? The file app/controllers.php contains the definitions of your controllers, but also at its head in contains a series of map_url() declarations mapping particular response urls to your controller functions. Edit the file 'config.inc' in your app directory to add new behaviors to your app and override the framework defaults. For example, if you define mappings like: 

map_url('foo', 'c_foo');
map_url('bar', 'c_bar');
map_url('foo/edit', 'c_some_other_controller');
map_url('', 'c_default')

Then when the url

  • http://[servername]/yourapp/foo is hit, your routine c_foo() will be called;
  • http://[servername]/yourapp/bar will likewise trigger c_bar(), and
  • http://[servername]/yourapp/foo/edit will trigger c_some_other_controller().
  • the last entry in the table defines the basic default controller for the simple url http://[servername]/yourapp.

Of course you have to define your controller functions c_foo(), c_bar() etc in controllers.php. Any subsequent strings in the calling path will be passed to your controller as arguments.For example, using the above usermap definition, a call to http://[servername]/yourapp/bar/pringle/prangle/123 will call
c_bar('pringle', 'prangle', 123). Of course, the $_GET and $_POST arrays are available as well, if they are set by subsequent query parameters, in the case of $_GET, or in form action urls in the case of $_POST.

Defining Views.

TWERP also provides a very simple view mechanism modeled on (that is, stolen from) Drupal themes. 'views' are format functions that are passed arbitrary data -- you decide what -- and return html which your controller routine will then print to the screen. Views can be defined in two different ways: with a function definition, which you would define in views.php, which looks something like: 

function view_home_page($contents, $other_data){
	return "<h1> HOME PAGE</h1> <p> $contents </p> <div class=\"foobar\">$other_data</div>";
}

Dopey example, huh? from some controller, you would call this like: 

print view('home_page', "this is the content string", "this is the extra data string");

Don't let my simple string variables fool you -- these variables can be whatever you want, php objects or arrays. All this may not seem that interesting, but the interesting part comes with the second way of defining views: with template files.

To continue the example above, if you place in the sub-directory of your app called 'view_templates' a file called 'home_page.tpl.php', then the call of 

view('home_page', "content", "extra")
above would use that file as a template instead of your defined view_home_page() function. See the default view file in the default framework for an example of how it's structured, but quite simply its included as a html file, which may hold embedded fragments like 
 <?php echo $contents ?>

One more thing: as with the url-to-controller mapping discussed above, there is a registration that must be made in config.inc when you declare a new view. When you define a new view_xxx() function (or template file xxx.tpl.php) you must register the argument names for it in the $view_arg_names[] array in config.inc. Just add a line to the definition of $view_arg_names with the name of the view as the key and an array of the function argument names as the array value. For the example above, the definition of $view_arg_names might be: 

$view_arg_names = array(
    'foo' => array('a', 'b'),   // some other view template, defined as  view_foo($a, $b)
    'home_page' => array('la dee da, content string', 'ho-hum, extra data string')
    );

This declaration is necessary to allow the argument name access in the .tpl.php files to work. This declaration allows you to embed code like 

<?php echo $contents ?>
in your home_page.tpl.php file, and have TWERP know what variable you're talking about.

Defining Models

You're on your own here, buddy. I'm suggesting by the framework that you wrap all your database access calls in m_xxx() functions you define in the models.php file, and only call those functions in your c_xxx() controller routines defined in controllers.php. But obviously you can do whatever you want, just don't come cryin' to me if you get yourself in a big mess by breaking the MVC model.

Other services TWERP provides

Not much at present.

  • A message utility (twp_add_message(), and view_twp_messages()) lets you set a message which can be dumped to the page in the next page view. view_twp_messages() is just a regular view function so it can be overridden by the addition of twp_message.tpl.php in the view_templates directory.
  • twp_goto() allows you to jump to some other page on your site by passing in its relative url.

More about urlmap and apache mod_rewrite.

The $urlmap[] thing depends on mod_rewrite being enabled in your apache installation. If it isn't, this won't work quite right. If you can't get this to work, then you'll be limited to relatively ugly urls. For example, continuing the example above, instead of being able to have an url like
http://www.this_server.com/yourapp/foo/edit
you will have to use an url like
http://www.this_server.com/yourapp/?q=foo/edit
to access your 'inner' pages.

In summary

  • Define controller routines in controllers.php, and map urls to controller routines by $urlmap[] array entries in config.inc.
  • Define view routines procedurally in views.php, or as templates in the view_templates/ directory. Register views by entries in the $view_arg_names[] array in config.inc.
  • You might want to declare js/ and css/ directories under app/ -- or maybe just keep .js and .css files in the view_templates directory.
  • It's good form to call model routines (as defined in models.php), and view routines (as defined in views.php OR as templates in the view_templates directory) from your controller routines only.
  • Remember that only config.inc, models.php, controllers.php and views.php are automatically 'included' in your application: if you come up with other support files or libraries in your app, 'include_once' them in one of these files.
  • There's really no need to mess with index.php or anything in the twerplib/ directory. So don't unless you know what you're doing.

twerp.zip -- 20kb file

twerp.tar.gz -- 32kb file