the W3matter Framework
----------------------

We're really Rails programmers, but from time-to-time we have to do a PHP project.
So over time we build this framework which sort of mimics the Rails framework. It does not have many of the little features that makes rails nice to use, but it does a pretty good job.

If you know rails, you will be comfortable in here.
Its fast, minimal code, and has the following components:

active_record component (without the pluralizations :-[ )
controllers
views
models

Active Record Component
-----------------------

Its quite similar in operation to active record, but not as nice and object oriented as AR is. Here are some examples:

// Can be in a model file called "users.php"
class Users extends ActiveRecord {
}

// Some code in your controller
$user = new Users;

$user->find(10); 	// finds user id 10
echo $user->name;
$user->name = 'Joe';
$user->save();
echo $user->name;

$u = $user->find_by_email_and_password('eric@w3matter.com', 'haha');		// Finds a record by username AND password
echo $u['name'];
echo $user->name;

$user->find_or_create_by_email_and_password('eric2@w3matter.com', 'hehe');		// Tries to find, and if not creates a new record;
$user->name = 'Ericson';
$user->save();

$user = new Users;
$user->email = 'esconsult1@gmail.com';
$user->password = 'hehe';
$user->name = 'Ericson Smith';
if ($user->save()) {
	echo 'Haha, we're good!';
}

// A more complex find
$users = $user->find( array('all'=>true, 'conditions'=>array('name=? AND status=?', 'bob', 1), 'limit'=>20, 'page'=>1, 'order'=>'name ASC') );

It has some validation support, support for foreign keys (will load related records) and so on.

The biggest issues? It does not return an object when you make a call. However, its quite fast, and you really don't have to write much SQL anymore unless there are really complex cases.

We've include drivers for:

* mysql
* postgresql
* sqlite

Setup
-----

1. Download the code to a directory NOT in your web root

2. Point your webserver to the "public_html" directory, this means that all the framework code will be outside of your web root

3. Setup your database config in config/detabase.ini

4. Make some models, each named exactly as the name of your database 


Routing
-------

config/routes.php

Routing is quite similar to rails routing, but not as capable, you can still do almost anything in there. Its a good way to avoid most of the things you would have done in mod_rewrite.

map_route('/post/:date/:permalink', array('controller'=> 'posts', :action => 'show'));

The above will take a URL like this:
http://yoursite.com/post/2008-10-05/this-is-a-cool-post

And call the action "show" in the controller "posts" and pass in two variables: $this->params['date'], and $this->params['permalink']

Want to edit the routing code to add more features?
Its in "system/utils.php"


Directories
-----------

app/
app/models -- store all your model classes in here.
app/views -- put your views in here
app/controllers -- where your controllers live

autoload/  -- stuff any file in here and it will be automatically loaded

config/  -- various system configuration files

lib/ -- where you can keep your libraries

log/ -- where stuff is logged

public_html/ -- point your webserver to here. NOT THE TOP LEVEL DIRECTORY!!!

scripts/ -- where you can put any scripts

system/ -- where the core of the framework lives

tmp/	-- store any temporary files in here
tmp/sessions -- where PHP stores its session files


Prohibits External Posting
--------------------------

This part prevents robots from making external postings to your forms.
Simply add the following variable to your forms in a view like this:

<input type="hidden" name="utforms" value="<?= $this->utform ?>" />

The system will throw an error message in /welcome/sorry
You can edit the view in app/views/welcome/sorry.phtml to whatever you want.

Human Detection
------------------------

This determines if the visitor is a human or a robot.
For this to work you have to install google analytics on your site. Generally robots do not parse or run Javascript.
So it uses the cookies generated by Google Analytics, its a simpele boolean flag available in all your controllers:
$this->human


Authentication
-----------------------
We have built in authentication with login, signup and logout already, just create the table below in your database as a start, then you can go to these URL's:
http://yoursite.com/user/login 
http://yoursite.com/user/signup
http://yoursite.com/user/password

Its real simple to use too, in front of any code that you need protecting...

	$this->login_required();

This will do a whole range of things:

1. Save the state of any passed in parameters internally (as in $this->params)
2. Redirect the user to the signup page
3. When signup and login is done, return the user to the exact point where login_required() was called
4. Restore all the values in $this->params

This is a great way to get users to post content, have then login and signup, then process the values in the $this->params hash.


Users Table
-----------

Create a table like this for your users:
You can add other fields if you like.

CREATE TABLE users (
  id int(11) NOT NULL auto_increment,
  `name` varchar(32) NOT NULL,
  email varchar(64) NOT NULL,
  `password` varchar(32) NOT NULL,
  created_on datetime NOT NULL,
  last_login datetime NOT NULL,
  ip varchar(32) NOT NULL,
  session_id varchar(13) NOT NULL,
  PRIMARY KEY  (id),
  UNIQUE KEY `name` (`name`,email)
) ENGINE=InnoDB  DEFAULT CHARSET=latin1;