Organizing Your PHP

Projects
Paul M. Jones
php|works atlanta
September 12-14, 2007
 “Project Planning in
One Lesson”
• Goals of organization
• Look at actual projects
• One lesson for organizing
your PHP code base
• Elements of The One Lesson
• Corollary effects
2
 Read These
• “Mythical Man-Month”, Brooks
• “Art of Project Management”, Berkun
• “Peopleware”, DeMarco and Lister

3
 About Paul
• Savant template system
• PEAR involvement
• DB_Table, Text_Wiki
• PEAR Group representative
• Zend Framework
• Zend_Db, Zend_View
• Solar Framework for PHP5
• http://paul-m-jones.com/
4
 About You

• Project lead/manager?
• Want to share your code
with others?
• Want to use code from
others?

5
 About Organizing
• Security
• Integration and extension
• Adaptable to change
• Maintenance
• Consistent and predictable
• Re-use rules on multiple projects
6
 Project Evolution Tracks
One-Off Heap

Standalone App

?
Library Collection Modular App

Framework CMS
7
 One-Off Heap
• No discernible architecture
• Browse directly to the scripts
• Little to no separation of
concerns
• All variables are global
• Add to it piece by piece
• Unmanageable and difficult to
extend
8
 Standalone Application
• One-off heap ++
• Series of separate page scripts
and common includes
• Installed in web root
• Each responsible for global
execution environment
• Script variables still "global"
9
 Standalone Application:
File Structure
index.php # main pages
task1.php #
task2.php #
task3.php #
sub/ # sub-section
index.php #
zim.php #
gir.php #
irk.php #
inc/ # script includes
config.inc.php #
prepend.inc.php #
append.inc.php #
lib/ # libraries
foo.class.php #
Bundle1/ #
Bundle2/ #

10
 Standalone Application:
File Structure
bin/ # command-line tools
cache/ # cache files
cron/ # cronjob scripts
css/ # stylesheets
docs/ # documentation
img/ # images
install/ # installation scripts
js/ # javascript
log/ # log files
sql/ # sql create/update commands
theme/ # themes or skins
tpl/ # templates

-- no standard naming or structure

-- index.html file in each directory
11
 Standalone Application:
Typical Main Script
// Setup or bootstrapping
define('INCLUDE_PATH', dirname(__FILE__) . '/');
include_once INCLUDE_PATH . "inc/prepend.inc.php"
include_once INCLUDE_PATH . "lib/foo.class.php";
include_once INCLUDE_PATH . "lib/View.class.php";

// Actions (if we're lucky)

$foo = new Foo();
$data = $foo->getData();

// Display (if we're lucky)

$view = new View(INCLUDE_PATH . 'tpl/');
$view->assign($data);
echo $view->fetch('template.tpl');

// Teardown
include_once INCLUDE_PATH . "inc/append.inc.php";
12
 Standalone Application:
Typical Include File
<?php
if (! defined('APP_CONSTANT')) {
die("Direct access not allowed.")
}

// expects certain global variables

?>

13
 Project Evolution Tracks
One-Off Heap

Standalone App

Library Collection Modular App

Framework CMS
14
 Modular Application
• Standalone application ++
• Same file structure and script style
• One additional directory:
“modules”, “plugins”, etc
• Hooks in the “main” scripts for
additional behaviors
• Use global variables to coordinate
between modules

15
 CMS
• Modular application ++
• General-purpose
application broker
• All "main" scripts become
sub-applications
• Still in the web root, still
using globals to coordinate

16
Application/CMS Projects
• Achievo • Joomla/Mambo
• Code Igniter * • MediaWiki
• Coppermine • PhpMyAdmin
• DokuWiki • Seagull *
• Drupal • SugarCRM
• Eventum • Vanilla
• Gallery 2 • WordPress
17
 Project Evolution Tracks
One-Off Heap

Standalone App

Library Collection Modular App

Framework CMS
18
 Library Collection
• Specific, limited logic
extracted from an app
• Re-used directly in
unrelated applications and
other libraries
• No global variables
• Can exist anywhere in the
file system (esp. w/PEAR)

19
 Library Project:
Typical File Structure
Foo.php # Foo
Foo/ #
Component.php # Foo_Component
Component/ #
Element1.php # Foo_Component_Element1
Element2.php # Foo_Component_Element2
... #
Bar.php # Bar
Bar/ #
Task.php # Bar_Task
Part/ #
Part1.php # Bar_Task_Part1
Part2.php # Bar_Task_Part2
...
20
 Framework
• Collection of integrated libraries
• Standardized structure and
naming conventions
• Generic bootstrap file to
initialize environment
• Front & page controllers to load
application logic as a library
• New applications extend from it
21
 Library/Framework
Projects
• AdoDB • PHP Unit • Solar
• Cake • Phing • SwiftMailer
• CgiApp • Phly • Symfony
• EZ Components • Prado • WACT
• Horde • Propel • WASP
• Mojavi/Agavi • Savant • Zend
Framework
• PAT • Seagull *
• PEAR • Smarty
22
16
 Project Evolution Tracks
One-Off Heap

Standalone App

?
Library Collection Modular App

Framework CMS
23
 About Organizing
• Security
• Integration and extension
• Adaptable to change
• Maintenance
• Consistent and predictable
• Re-use rules on multiple projects
24
 The One Lesson

• Organize your project

as if it will be part of a
library collection.*
• (* ... if you don't choose an existing framework
or CMS.)

25
 Elements of
The One Lesson

• No use of global variables

• Namespace prefix on all global identifiers
• Class-to-file naming convention

26
 1. Stop Using Globals

• No more register_globals
• No more $GLOBALS
• No “global” keyword in
functions and methods

27
 2. Use A Namespace
Prefix On Identifiers
• No true namespaces in PHP
• Prefix all global identifiers for
automatic deconfliction
• Classes
• Functions, variables,
constants if you must
• Use with $_SESSION,
$_COOKIE, etc. keys
28
 Namespace Examples
• class User {}
• class Vendor_User {}
• function get_info()
•function vendor_get_info()
•$_SESSION[‘prefs’]
•$_SESSION[‘Vendor’][‘prefs’]
29
 Choosing a
Namespace Prefix
• Project, vendor, brand,
channel
• A short word or acronym,
not a letter (“Z”)
• A unique name, not a
generic one related to a
task (Date, HTML, RSS,
Table, User)

30
3. Class-To-File Naming
Convention
• Horde, PEAR, Solar, Zend, others
• Highly predictable file locations
• Lends itself to autoloading
• Maps well to @category, @package, and
@subpackage for API documentation

31
 Class-to-File Naming
Examples
• VendorAuthTypeKey => Vendor/Auth/Type/Key.php ?
• Vendor_Auth_TypeKey => Vendor/Auth/TypeKey.php
• (Not necessarily the inheritance hierarchy)

Vendor/ # @category Vendor

Auth.php # @package Vendor_Auth
Auth/ #
TypeKey.php # @subpackage Vendor_Auth_TypeKey
TypeKey/ #

32
 Extended Effects of
The One Lesson
• No more include-path woes

• Can move almost entirely outside

web root

• Structure for refactoring and

additions

• New developers can intuit

structure

• Testing, profiling, and public files can

parallel the same structure
33
 About Organizing
• Security
• Integration and extension
• Adaptable to change
• Maintenance
• Consistent and predictable
• Re-use rules on multiple projects
34
 Summary
• Organize your project as if it will be part of
a library collection
• Avoid globals
• Use namespace prefixes for deconfliction
• Use class-to-file naming convention
• Not a silver bullet
• A valuable jump-start and mental map
35
• Questions?
• Comments?
• Criticism?

36