protoman: A PHP repository from mandric

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

mandric/protoman