Organizing Your PHP
Projects
Paul M. Jones
php | tek, chicago
May 21, 2009
1

Read These
• “Mythical Man-Month”, Brooks
• “Art of Project Management”, Berkun
• “Peopleware”, DeMarco and Lister
2

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
3

About Me
• Web Architect at OmniTI
<http://omniti.com>
• PHP since 1999
• Solar Framework (lead)
• Zend Framework (dev)
• PEAR Group (2007-2008)
• <http://paul-m-jones.com>
4

About You
• Project lead/manager?
• Want to share your code
with others?
• Want to use code from
others?
• Want to reduce recurring
integration issues?
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 ?
Modular App
Collection
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:
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\";
10

Standalone Application:
Typical Include File
<?php
if (! defined('APP_CONSTANT')) {
die(\"Direct access not allowed.\")
}
// expects certain global variables
?>
11

Standalone Application:
File Structure
index.php # main pages
page1.php #
page2.php #
page3.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/ #
12

Standalone Application:
Support 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/ # schema migrations
theme/ # themes or skins
tpl/ # templates
-- no standard naming or structure
-- index.html file in each directory
13

Project Evolution Tracks
One-Off
Heap
Standalone
App
Library ?
Modular App
Collection
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 • Eventum • Seagull*
• Code • Gallery • SugarCRM
Igniter*
• Joomla/ • Vanilla
• Coppermine Mambo
• WordPress
• DokuWiki • MediaWiki
• Drupal • PhpMyAdmin
17

Project Evolution Tracks
One-Off
Heap
Standalone
App
Library ?
Modular App
Collection
Framework CMS
18

Library Collection
• Specific, limited logic extracted
from an app
• Re-used directly in unrelated
applications and other libraries
• No global variables
• Class-oriented
• Can exist anywhere in the file
system
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
• Codebase
• Library collection
• Apps extend from it
• Support structure
• Bootstrap file
• Public assets
• Protected assets
21

Library/Framework Projects
• AdoDB • PAT • Seagull *
• Cake • PEAR • Smarty
• CgiApp • PHP Unit • Solar
• Code Igniter * • Phing • SwiftMailer
• EZ Components • Phly • Symfony
• HtmlPurifier • Prado • WACT
• Horde • Propel • WASP
• Mojavi/Agavi • Savant • Zend Framework
22

Project Evolution Tracks
class- One-Off include/
oriented Heap function
oriented
Standalone
App
Library ?
Modular App
Collection
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 code
as if it will be part of
a library collection.
25

Elements of
The One Lesson
• No use of global variables
• Namespace 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
• Automatic deconfliction of global
identifiers
• Classes (prefix, namespace)
• 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
• 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
// studly-caps
VendorAuthTypeKey => ...
Vendor/Auth/Type/Key.php?
Vendor/Auth/TypeKey.php?
// underscores
Vendor_Auth_TypeKey => Vendor/Auth/TypeKey.php
Vendor/ # @category Vendor
Auth.php # @package Vendor_Auth
Auth/ # ...
TypeKey.php # @subpackage
TypeKey/ # ...
32

Extended Effects of
The One Lesson
• Can be used anywhere (app, module,
lib, CMS, framework)
• Structure for refactoring and additions
• Testing, profiling, and public files can
parallel the same structure
• Intuitive for new developers
• No more include-path woes
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 namespaces for deconfliction
• Use class-to-file naming convention
• Not a silver bullet
• A valuable jump-start and mental map
35

• Questions?
• Comments?
• Criticism?
36

Bonus:
Framework Structures
37

Zend Framework
project
|-- application
| |-- bootstrap.php
| |-- configs
| | `-- application.ini
| |-- controllers
| | |-- ErrorController.php
| | `-- IndexController.php
| |-- models
| `-- views
| |-- helpers
| `-- scripts
| |-- error
| | `-- error.phtml
| `-- index
| `-- index.phtml
|-- library
| `-- Zend
|-- public
| `-- index.php
`-- tests
|-- application
| `-- bootstrap.php
|-- library
| `-- bootstrap.php
`-- phpunit.xml
38

Solar - System
39

Solar - Libraries
40

Thanks!
• http://omniti.com
• http://paul-m-jones.com
• http://solarphp.com
41