A lightweight Django-like PHP framework implementing regex URL routing, template inheritance and a simple ORM with custom types.
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
apps
base
db
proj
.gitignore
LICENSE.html
README.textile
TODO
framework.php

README.textile

ProtoMan!

As Djangophiles interested in taking on PHP work without all the pain (we know it well), Comfy Chair decided to implement our favorite parts of Django and turn them into a relatively simple PHP framework. This is the result-in-progress.

Quickstart

The proj/ directory is what we use for testing; it contains a basic blog and some associated tests.

classes.php

This file holds your models. They’re defined based on defined types; there are several in the framework already, and you can create custom types if you’d like.

routes.php

This is where you define your URL’s and specify the controller methods they should hook up to.

controller.php

Define a controller class for your app to handle requests and render templates.

tests.php

Write your tests here. Your script will be executed on a clean, updated set of tables. For a line of code that should be evaluated as an actual test, place the expected result on the line immediately beneath it, followed by two newlines; all other lines of code should be separated by two newlines.

Comments (two-slash single-line only) are allowed and will be ignored.

types.php

Optionally define your own field types.

index.php

Include apps and define your database configuration and debug mode.

Database population and command line interface

Using the CLI commands, you can automatically build your table structure based on the databases you’ve defined and the apps you’ve included.

rebuild [db] [app]

Running this command will drop and recreate all tables for models defined in the specified app (for example, “php index.php dev blog”). ‘all’ can be used instead of an app name to rebuild all tables in the project.

test [app]

Again, ‘all’ can be used instead of an app name. This will drop and rebuild all tables for the app within the ‘test’ database, then run all tests in the tests.php file for the app you specify (or all tests.php files in your project).

Web server configuration

We use a Django-style URL scheme, so you’ll need URL rewriting for the routing to work. The Apache configuration has not yet been tested; the nginx server block is from a working installation.

Apache
RewriteEngine On
RewriteBase /

RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php?$1 [QSA,L]
nginx
server {
    listen          80;
    server_name     protoman;
    server_name_in_redirect off;
    
    access_log      /var/log/nginx/protoman.access_log main;
    error_log       /var/log/nginx/protoman.error_log info;
    
    root /home/phu/internal/protoman/proj;

     location ~* ^.+.(html|jpg|jpeg|gif|png|ico|css|pdf|txt|js)$ {
         expires 30d;
         break;
     }

    location /
    {
        if (!-f $request_filename) 
        {
            rewrite  ^(.*)$  /index.php?$1  last;
            break;
        }

        if (!-d $request_filename) 
        {
            rewrite  ^(.*)$  /index.php?$1  last;
            break;
        }
    }

    location ~ .*\.php$
    {
        include /etc/nginx/fastcgi_params;
        fastcgi_pass 127.0.0.1:9017;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME /home/phu/internal/protoman/proj$fastcgi_script_name;
    }
}

Features

There’s a relatively small set of “holy crap that’s awesome” stuff we figured we needed for this project to actually be useful to us commercially.

Complete

  • App-based site design
  • Multi-database configuration for dev/prod/test environments
  • Sandboxed testing framework based on simple PHP with simple reporting
  • Regex-based project- and app-based URL routing with arbitrarily-defined slugs/id’s
  • ‘Reverse’ URL building
  • Automatic form generation based on defined types
  • ‘contrib’-style basic apps including basic auth (user)
  • Arbitrary caching integration (memcached stock) with session fallback
  • Flexible database types with validation support
  • Automatic table creation based on models
  • Automatic admin interface generation
  • Native many-to-many support with basic PHP object/array operators
  • Simple template inheritance (without interfering with the use of standard PHP)
  • Support for calling multiple views per request
  • Basic ORM queries (get by ID, filter, order, group, insert, update, delete)
  • Database abstraction

Incomplete

  • Advanced ORM queries (e.g. Q objects)
  • Database-agnostic create statements (needs minor updates to be generic)
  • Migration-style table updates for schema changes
  • Group and permission models for auth module
  • Generic, gracefully-failing AJAX support through generated links

Current items of interest

  • Expand apps/auth to handle groups and permissions
  • Add tests to built-in apps
  • Documentation for common operations
  • Clean up Saveable (base ORM) class (was ported from being a standalone ORM, needs love)
  • Find a better way of including framework.php (put on PHP path?)

Project parameters

Working within the confines of PHP, we’re limited in certain ways (some of which we’ve chosen voluntarily).

Requirements

  • Maintain compatibility with PHP 5.2.x

Concessions/omissions

  • Namespaces (unsupported pre-5.3)
  • Decorators (using queued views instead)

License

Creative Commons Attribution-Noncommercial-Share Alike

The protoman framework is available only under this Creative Commons license.

You can also view a brief overview of the license.

If you want to use protoman commercially, or if you’d like to have your own site built/rebuilt on protoman, please contact Comfy Chair Consulting, Inc. (the copyright holder) at: info@comfychairconsulting.com