phPit Foundation Framework
Created and Copyright 2011 by Jarvis Badgley, chiper at chipersoft dot com.
phPit (pronounced Peach-Pit) is a boilerplate framework designed for quick website creation. It provides the basic requirements of most sites, such as database access and clean url management, in a wrapper format that is easy to learn. Pages are created and worked with just like normal PHP files, but page code begins with the database, class autoload and session management already included and running on the page.
phPit Primary Features:
Models: phPit provides a quick and easy Database wrapper class for all MySQL functions, but the real meat of phPit's database integration is the model base class, DBRecord. DBRecord extends ArrayObject to make working with individual rows as painless as possible. To create a model, subclass DBRecord and define the table name and primary key(s). That's all you need to start reading and writing rows in the database, DBRecord writes all the queries for you, sanitizing data according to table column types. See
models/dExample.phpfor an implementation example.
Views: phPit is built on the philosophy that PHP is already a template engine itself, and an additional template engine is unnecessary. You are certainly welcome to use a template engine such as Smarty, and phPit will not get in your way, but it does not take any steps in that direction. Instead, phPit includes two objects designed to make page creation easier within an MVC structure.
- A standard
Pageclass that provides an object oriented approach to creating an HTML5 page foundation, entering any data you need in the HEAD tag by way of function calls. Page is intended to be subclassed for adding your site structure, such as the navigation, headers, footers and any other content that is not part of your central body. You just create an instance of your template object, call start() before your content and stop() after your content, leaving you to only worry about everything in between.
- A basic
Viewclass for rendering page layouts in the Output Buffer without sending them to the visitor.
- A standard
Controllers: phPit provides the typical "Clean URL" interface for executing individual pages. The page request URL is delimited by the directory slashes and the framework works backwards through the URL until it finds a controller name that matches. Any parts of the url not included in the controller name are passed to the controller as an array of arguments, and arguments that follow a name=value pairing are automatically parsed as named values in the array. Each controller file represents a single action, and is executed linearly like a standard php request outside a framework.
- PHP 5.2 or later
- No extra PEAR modules are required. phPit is designed to work in the easiest of environments
- phPit does expect magic_quotes and register_globals to be disabled. The .htaccess file attempts to override these values to ensure this.
- phPit uses PHP Data Objects for database access, and will need the pdo_mysql driver configured if you intend to use the Database class with MySQL (SQLite support is built into PHP as of 5.1.0).
- Apache 2.x with mod_rewrite
- Apache must be configured to allow mod_rewrite directives in .htaccess files.
- To begin, fork, clone or download the phPit project to your development environment. For simplicity sake it is recommended that phPit be installed at the base of it's own virtualhosted domain name, but it can be installed as a subdirectory as well.
- If phPit has been installed into a subdirectory instead of a domain root, or if you intend to use the database features, you must configure these settings by duplicating
config.phpand editing the necessary settings.
- That's it!
Point your browser to the address you installed phPit in. If you see the phPit logo, your installation was successful. If you see a directory index or a 503 Forbidden error, verify that your .htaccess file is present and that Apache is configured to use it.
From the base of the phPit installation:
.htaccess - This is the Apache configuration file that includes the mod_rewrite directives for handling page requests. This file MUST be installed for phPit to work. Linux and the Mac OS may hide this file from view, so it may be necessary to check using the terminal to see if this file is present.
config.default.php - The default configuration file. phPit will fall back to this file if config.php is not present. It is recommended that config.php be deliberately excluded from the development environment, and the default file be used for your settings, so as to keep your live production server's settings independent.
controllers - This folder will contain all your actual site pages. Controllers are named according to their web request path, with periods used in place of slashes. For example:
articles.view.phpwould be accessed as
/articles/view/, and any sub directories after that would be passed to the controller in the $arguments array. The contents of this folder cannot be accessed by direct Apache requests.
- 404.php - This is the file that phPit will execute if it cannot find a matching controller
- index.php - If no path is included, or a request for /index/ is made, this file is the default controller
- login.php - Basic login form, demonstrates the use of the User object
- logout.php - Opposite of the above
- postdump.php - Helper page for testing form output, will print the entire contents of the $_POST array.
- test.php - phPit developer's console, will eval() any code entered. Controller will only execute if CONSOLE_KEY is present in config file, and entered code will only be evaluated if the second field on the page matches what is defined in CONSOLE_KEY.
cache - Local location for storing cached information, needs to have permissions set to be writable by Apache/PHP. The contents of this folder cannot be accessed by direct Apache requests.
cron - Use this folder for storing any cronjob or maintenance scripts that you do not wish to be accessible from the web. The contents of this folder cannot be accessed by direct Apache requests.
css - This is the folder to contain any cascading style sheets used for your site. Unless specified elsewhere, the Page class will pull from this folder for style additions. By default this contains a global.css file that is included for any page on the site, which includes a boilerplate css reset and the styles for the /login controller.
files - Optional folder to use for storing any CMS uploaded content. Should have permissions set to be writable by Apache/PHP.
functions.php - This is the collecting place for any general purpose non-namespaced functions. It is included by main.php, but should fail silently if removed.
images - Your images folder, obviously. This folder is not required and may be removed or renamed if you so wish.
includes - Folder for any general purpose non-layout php files you wish to include from your controls. The contents of this folder cannot be accessed by direct Apache requests. Use
include Path::CodeInclude('filename')to include a file from this folder, omitting the .php extension from the file name.
libraries - Third party libraries and objects should be placed in this directory. Autoload will check this folder for any files matching the class name plus ".php". If the library you use does not follow this naming convention and cannot be renamed, you may create a file matching that pattern which includes the library files directly. You may also reference files in this folder directly by calling
include Path::Library('filename'), including the .php extension from the file name. The contents of this folder cannot be accessed by direct Apache requests.
- The PHPMailer library is included in this folder. If you do not wish to use PHPMailer, please also delete Email.php from the file, and remove the email directives from the config file.
- This folder is not required by phPit and can be deleted if you choose.
main.php - This is the core execution file for phPit. All web requests pass through main.php before executing the related controller file. For cron jobs, including this file at the beginning of the script will allow the script to execute just as a controller would.
models - Folder for all database model classes that extend from DBRecord. Autoload will check this folder for any files matching the class name plus ".php". The contents of this folder cannot be accessed by direct Apache requests. This folder is optional and can be removed if you do not wish to use the phPit's model structure.
objects - Folder for any non-model, non-third party code objects. The contents are entirely optional except where noted otherwise. Autoload will check this folder for any files matching the class name plus ".php". Use
include Path::OObject('filename')to directly include a file from this folder, omitting the .php extension from the file name. The contents of this folder cannot be accessed by direct Apache requests. The full installation of phPit includes the following:
- Autoloader - The autoload engine used by phPit to locate and load classes. This is required by phPit.
- Path - All file requests in PHP are done using absolute paths to avoid security issues. The Path class provides the helper functions for producing those paths. This is required by phPit.
- Database - phPit's PDO database class provides a singleton interface for maintaining a database connection, and offers convenience functions for easily making one-off queries.
- DBQuery - A chainable object for building sql queries non-linearly.
- DBRecord - phPit's base class for database models.
- Response - Collection of procedural functions for responding to requests, including url redirection and HTTP status codes.
- View - phPit's View class for rendering page templates.
- WebPath - Collection of procedural functions for manipulating urls. This class is required by the Page class.
templates - Folder for any template classes derived from the
Pageobject, which also resides in this folder. Autoload will check this folder for any files matching the class name plus ".php". Use
include Path::Template('filename')to directly include a file from this folder, omitting the .php extension from the file name. The contents of this folder cannot be accessed by direct Apache requests. This folder is optional and can be removed if you do not wish to use the Page class.
views - Folder for any layout files you wish to include from your controllers. The contents of this folder cannot be accessed by direct Apache requests. Use
include Path::View('filename')to include a file from this folder, omitting the .php extension from the file name. This folder is optional and can be removed if you do not wish to use the View class. Files can also be accessed and parsed via the View object like so:
$v = new View('filename'); $v['variable'] = 'some value'; $contents = $v->render();
Note that the Page class includes Prototype 1.7.1 and Scriptaculous 1.9 from Google CDN by default. If this is not your desired behavior, feel free to remove the calls from the class constructor.
PHP files beginning with lower case letters are procedural files. PHP files beginning with uppercase letters are class definitions, with the exception of non-system models which are always prefixed with a lowercase 'd'.
Variables are typically named with underscore delimited notation (ex: variable_name), but do not be surprised to also find camel-case notation. There is no delineation intended in this use, and all variables should be treated the same.
Standalone functions always use underscore delimited notation.
Static class functions always use UpperCamelCase. Instanced class functions always use lowerCamelCase.
phPit is released under an MIT license. No attribution is required and you are expected to make alterations. For details see the enclosed LICENSE file.
Credit for the name phPit goes to Reddit user whobutsb