Read Me

INTRODUCTION

This readme file accompanies a fresh installation of PROPS, a simple but crafty
collection of basic code I have found useful for developing webapps in php.
This isn't brain surgery! I just wanted to produce a cleaned up
version of this that can be checked out from sourceforge with a single
subversion call. If it saves other people time so much the better.  The name is
a play on java struts and ruby rails, php being more of a pragmatic, everyman's
technology, I wanted the name and the framework itself to reflect that. I want
it to be something that can be fully grasped in 10 minutes. No fluff, no
bizarre pipelines to grep through, just basic reusable code.  If the design
seems overly complex in certain places it is only to steer clear of ambiguity
that could lead to getting painted into a corner down the road.  PROPS has many
guidelines, but all of them can be easily broken, I believe in ducktape.


GENERAL STRUCTURE

In a nutshell, here's the structure of props, 

* apache has a rewrite rule that redirects 404's to /index.php

* all browser requests go through /index.php, all printing is performed in index.php

* index.php renders a global header and footer and calls /pages/foo.php for the page body

* index.php has an array defining which pages handle which urls, this makes
  debugging easy, even for fresh eyes, nothing gets lost

* a file in /pages/ is a php script containing a function called _page() that
  produces the page body

* all classes go in the /classes directory

* classes are instantiated and used in functions in /pages/foo.php

In other words ...

Web request for /foo 
 -> index.php array defines /pages/foo.php as "handler"
   -> the __page() function in /pages/foo.php is called
 -> index.php renders a global header + returned string of foo.php + a footer
    it transparently gzip's it for appropriate browsers 
    and outputs the contents




GPC VARIABLES

PROPS has a style for handling GET/POST/COOKIE input

* GET/POST/COOKIE variables are accessed from the $site object, instantiated in
  index.php passed  into /pages/*

  $user_id = $site->gpc("id", "numeric"); 
  
  The second parameter is a simple way of bounds checking, possible values are
    numeric | mostlyalphanumeric

  GET/POST/COOKIE variables are merged into a single array, with collisions
  handled in this order, get overriding post overriding cookies.



DATABASE ABSTRACTION

Database access is done through my handy L7 interface (an L7 is a square...)

This performs connection caching, remembers $result ids for you, does optional
query serializing/caching (in a table), and a few other things I've found handy.

Cache on
$l7->cache_on();
  cached results from all queries will be pulled from a key/value table called "cache"

Cache off
$l7->cache_off();
  turns caching off

Horizontal grid  --- rows()

  foreach ( $l7->rows("select id,name from users ")  as $row) {
  list($id,$name) = $row; 
  }


Horizontal row   --- row()

  list($id, $name) = $l7->row("select id,name from users where id=1");


Vertical collumn --- col()

  list($ids) = $l7->col("select id from users") ;

Vertical grid    --- cols()

  list($ids, $names) = $l7->cols("select id,names from users") ;

Single cell      --- cell()
  $l7->cell("select name from users where id=1") 

Void query       --- query()
  $l7->query("delete from users") 



A fleshed out PROPS installation  might look something like this:

|-- index.php
|-- classes
|   |-- datapimp.class.php
|   |-- site.class.php
|-- media
|   |-- ajax.js
|   |-- jquery.js
|   |-- main.css
|   |-- logo.png
`-- pages
    |-- account.php
    |-- contact.php
    |-- login.php
    |-- character.php
    |-- cookie.php
    |-- mailpass.php
    |-- search.php
    |-- splash.php
    `-- upload.php

Lets say you want to add a blog to the site, 

* create the entry in index.php pointing /blog/ to /pages/blog.php
* create the appropriate tables in the db ... 
* create a blog object in the /classes/ directory 
* within the generic _page() function in /pages/blog.php instantiate your blog
  object, and within an IF structure keying of GPC data, call blog object
  methods for displaying, searching, etc.