You are on page 1of 38

Writing Maintainable PHP

Laura Thomson, OmniTI

PHP Quebec Conference
16th March 2007

• Defining the problem

• Basics of maintainable code
• Scaling the code base
• Maintaining legacy code

PHP Quebec 2007 2

What is Maintainability?

• Can somebody else understand your

code enough to change and update it?
• Can you understand your own code
enough to change and update it?
• Can the code be extended and
adapted easily?

PHP Quebec 2007 4

How do maintainability
problems arise?
• Lack of foresight about:
– Size of the project
– Time frame/future direction

• Developer ignorance (a big one)

PHP Quebec 2007 5

Sizing the project

• For small problems write small code

and be willing to write throwaway
• For big problems design before you
• The issue arises when projects grow
• Classic problem of being unable to
redevelop a prototype
PHP Quebec 2007 6
Developer ignorance

• Self taught and junior developers

• Lack of experience with working in teams
• Lack of experience with developing
significant code bases
• Lack of experience with other people’s
horrible code
• Have not yet been forced to revisit their
own old code
• How are they going to improve?
PHP Quebec 2007 7
Basics of maintainable code

(What you should already

Basics of maintainable code

• Common errors
• Coding standards
• Version control
• Developer education

PHP Quebec 2007 9

Common errors

• Obfuscated code (the big one)

• Failure to comment appropriately
• Inline functions
• Side effects
• Failure to read and fit in with existing
• Ignoring security (or planning to
PHP Quebec 2007 10
Obfuscated code

• The worst of all common errors:

– Poor naming
– Seventeen layers of handoff
– Misuse of define()
– Reimplementation of built in functions
– Failure to do the simplest thing that could
possibly work
– Premature optimization (and it’s virtually
always premature)
PHP Quebec 2007 11
Poor naming

• Not just $foo, $bar

function edit_item_name(itemID) {
var sItemID = "edit-item-" + itemID;
var oItemID = document.getElementById(sItemID);

• Imagine trying to find this error in the code

provide a category name (or) select an existing

PHP Quebec 2007 12

Abusing define()

define('STR_NBSP', ' ');
define('STR_BR_TAG', '<BR/>');
define('STR_BEGIN_TD', '<TD>');
define('STR_END_TD', '</TD>');

PHP Quebec 2007 13

Reimplementation of built ins

function change_to_lowercase($item,$key)
global $changes;
$changes[$key] = strtolower($item);

PHP Quebec 2007 14

• First, try the simplest thing that could possibly work.


* Description: Changes the case of text within tags <>
* Make sure the $argc and $argv variables are enabled.
* Invoke this script on CLI as follows:
* php <thisfilename.ext> file2Bparsed.ext

if ($argc <= 1 || !isset($argv[1])) {

die("\nPlease enter the file to be parsed\n");

$filename = $argv[1];
if (!file_exists($filename) || !is_readable($filename)) {
die("\nEnter a valid file\n");

PHP Quebec 2007 15

Simplicity - 2
$changes = array();
$is_match = false;
$fh = fopen($filename, "r");
$contents = fread($fh, filesize($filename));

$pattern = "/(<(\w+)>|<\/(\w+)>)/";

if (preg_match_all($pattern, $contents, $matches)) {

$is_match = true;
if (!empty($matches[0])) {
//change the matched elements to all lowercase
array_walk($matches[0], 'change_to_lowercase');

if (!$is_match) {
die("\nNo match found\n");

PHP Quebec 2007 16

Simplicity - 3
$fh = fopen($filename, "w");
if (!is_writable($filename)) {
die("\nFile is not writable\n");

$contents = str_replace($matches[0], $changes,

$success = fwrite($fh, $contents);
if ($success) {
print "\nSuccessfully matched and modified.\n";

PHP Quebec 2007 17

Premature optimization

• Often obfuscates code, and often

done without a good rational reason to
do so

function foo(&$bar) {…

PHP Quebec 2007 18

Coding standards

• Have and use a coding standard

• Don’t need to write one from scratch:
PHP standards exist for PEAR and for
the Zend Framework. These can be
used adhoc or serve as a basis for
your own
• Greenfields vs legacy: virtually

PHP Quebec 2007 19

How not to write a coding
• Make the rules awkward and difficult
to remember
• Apps Hungarian – the most abused
coding style ever
• Force millions of tiny files
(performance hit)
• Force complete OO (why not just use
PHP Quebec 2007 20
Example coding standard

• (Excerpts)
• Formatting e.g.
– Always use long form PHP tags <?php ?>
– Two space indents throughout, NO HARD TABS
– …
• Naming
– Use camel caps for OO identifiers (classnames,
methods, member variables), like this:
– …
PHP Quebec 2007 21
Standard - 2

• Comments
– Every file should have a header block
containing at a minimum…
– Single line comments are encouraged on
non-obvious code. These can also be
used to add "TODO", "DEBUG", and
"FIXME" items

PHP Quebec 2007 22

Standard - 3

• Declare functions and classes in library files that do not have any execution
side effects besides possibly instantiating variables or defining constants.

• All code should run clean with error reporting turned up to E_ALL

• Try to avoid use of the ternary operator for readability

• Avoid magic numbers, declare a constant

• Avoid embedding PHP logic in HTML and vice versa

• Use parentheses to reinforce unclear or complicated precedence.

• Avoid use of global keyword

• …

PHP Quebec 2007 23

Version control

• For any project that will take more

than a week, more than one code file,
or more than one developer .
• And most of the others as well.
• Frequent commits of conceptual
• Detailed commit messages (trac,
while it has shortcomings, is your
PHP Quebec 2007 24
The code under the rug

• If nobody ever notices how awful your code is, but

notices if it is late what happens?
• If the next guy only says “aaarrrgh” when you are
working somewhere else, does it make a sound?
• You need somebody other than the original author
doing QA anyway
• Peer review can be confronting, but valuable
• Somebody overseeing commits can pick up a lot of
evil … and act as a deterrent

PHP Quebec 2007 25

Developer education

• Don’t underestimate the importance

of training.
• How:
– Provide code layout and design
– Provide sample code
– Explain what’s required
– Give frequent feedback

PHP Quebec 2007 26

Scaling the code base
Frameworks and Architectures:
use and abuse
• Frameworks are buzzy, and Rails doesn’t help.
• Having an architecture like MVC can be a really good thing,
– Everybody has a different idea about how this ought to be
– Some of the ideas are really twisted
– Some make it hard to do very basic things simply
– Code bloats
– Which framework?
– No dominant paradigm yet, ergo little help with maintainability
Have a clear, simple, architecture that is easy to
add to, easy to explain to new developers, and
easy to remember now or in two or five years’

PHP Quebec 2007 28

What do you gain from a
• Standard code layout for that
• Often makes developing a prototype

PHP Quebec 2007 29


• Skills don’t transfer from one

framework to another
• Rapidly prototyped code not
necessarily appropriate for use in

PHP Quebec 2007 30

Two kinds of frameworks

• MVC style (e.g. Cake)

• Component style (e.g. eZ)

• Both kinds of music (e.g. ZF)

PHP Quebec 2007 31

Database abstraction use and
• Use PDO – it’s a defacto standard
• Standardize on use of prepared

PHP Quebec 2007 32


• Needs to be part of the initial build

• Trying to retrofit it is very hard, but
also what usually happens, and new
exploits need to be accounted for
• Build into your architecture stages of
input and output processing to
encourage filtering and escaping in
single locations

PHP Quebec 2007 33


• For projects beyond a certain size, you start

to need significant documentation
• If your plan says this code will grow large,
document as you go, from the start. If it’s
not done at the time, it will never be done.
• (Sometimes we can all be caught short)
• Aim for consistent production of lightweight
– Takes less time to produce (and therefore has
some chance of actually happening)
– Takes less time to read

PHP Quebec 2007 34

Maintaining Legacy Code
(or, “The Ninth Circle of Hell”)
Maintaining legacy code

• “Hell is other people’s code.”

- Anonymous, late twentieth century

- Sad true facts:

- You may never read all the legacy code
- There will be parts of it that are broken or never
- If the original author didn’t document it, chances
are you never will
- If it needs a complete rewrite, chances are you
won’t have time
- You will have to to deal with this at some stage if
you haven’t already.

PHP Quebec 2007 36


• Worth spending some time to audit:

– What you have in the way of documentation
– The basic architecture of the code
– Coding conventions if any
– What is used
– What is obviously broken or fragile and why
• Refactor as you go, to a lightweight plan
• Don’t get too ambitious.

PHP Quebec 2007 37


PHP Quebec 2007 38

You might also like