Introduction
As with any language, in PHP there are practices which, depending on your goals, increase or de-crease maintainability (by which we mean the ease of administration over the application life time).
Often we are tempted to create scripts that "just work". That's acceptable in most cases, but we have all been in a situations where we have been looking at source code written by someone else and couldn't understand anything. Furthermore, it's even the original developers themselves that have to understand the code they have written after a long period of time.
To prevent this, and to make your code likable by other programmers, these are some guidelines proposed by the CodePax community.
Always use constants, never use literal values
By the strictest interpretation, this means you shouldn't use strings or numbers in your code. Instead, you should define everything in a separate area as constants, using define() . Boolean values TRUE and FALSE are accepted, because they are already constants. Sometimes 0 and 1 are accepted as well.
For example, instead of writing:
print "The date is " . date() . " now.";
this tip suggests that you should be using:
define('DATE_MESSAGE', 'The date is %s now.'); printf (DATE_MESSAGE, date());
And instead of using regular expressions as strings, you could also define them as constants.
Of course, it's quite rare that we really need follow this to the strictest sense. Many times we're better off just writing strings in-line in the code, without having to deal with separate inclusions of other files. But imagine the case in which your application must be multi-lingual: this is where applying this rule could really come in handy. To change the language of your interface, you would simply define different values for the constants.
You can overdo it, of course. For example, when you find yourself defining something like:
define('HTML_NEW_LINE', '<br />');
Unless you have a good reason for it, you know that you're doing something wrong, as you shouldn't use html presentation inside your code (See the "Separate your presentation from actual code" section).
Don't overuse arrays
If you're working with arrays, you should pay attention when you begin writing something like:
$tb_[$global_['section']]['fields']['id']['table']['trigger_insert']['post']['1']['sql'] = "INSERT INTO users (password, fullname, email) VALUES ('default', '[NEWlastname] [NEWname]', '[NEWemail]')"; // ... many other similar ones
The problem here is it will require some forensic work to track down where those values are interpreted. Another piece of advice would be to define arrays with
$fields = array( 'id' => $id, 'fullname' => $fullname, 'email' => $email // ... And so on )
which makes for a much better maintainable code, because it's easier to re-assign those array values to other places where they may be needed.
Separate the application presentation layer from the actual code
Whether you use a PHP Framework or not, you're better off using one of the available template systems. In its simplest form, this might mean using one separate PHP file containing each of the HTML you use throughout your application. In more complex cases, such as when having to delegate the task of template design to people who don't know PHP, this might mean using Smarty, or a different template engine.
Research existing methods of solving problems
There is PEAR, Zend Framework which could contain just the component you need to solve your problem! You should be aware of all the options you have before deciding to write any large component from scratch.
Organize your files consistently
How do you organize your files? The most important aspect of file organization is that you do it clearly and consistently, so that someone who sees your application for the first time can find where a certain function or class is defined with a minimal amount of exploration.
Make use of the get_include_path() and set_include_path() to load libraries. And until the new PHP namespaces become widespread, use a prefix for your class names so that they cannot conflict with other classes. The Pear and Zend Framework naming standard is a good example. It maps the directory and file name of a class to the actual class name. For example, if your class was in PHP/CodeSniffer.php, it would be defined as
class PHP_CodeSniffer
Other tips
Have you got an idea for increasing PHP code maintainability? Do you see something that should be changed, or is inaccurate? We invite you to go ahead and create a new revision. The content on CodePax is written by everyone!