PHP and MySQL Web Development - P95 ppsx

442
Chapter 22 Using PHP and MySQL for Large Projects
code from other users that often answers the same questions you might have after read-
ing the basic manual page.You can reach the English language version at
/>Some programmers who come from a different language background might be tempted
to write wrapper functions to essentially rename PHP’s functions to match the language
with which they are familiar.This practice is sometimes called “syntactic sugar.” It’s a bad
idea—it will make your code harder for others to read and maintain. If you’re learning a
new language, you should learn how to use it properly. In addition, adding a level of
function call in this manner will slow down your code.All things considered, this is an
approach that should be avoided.
If you find that the functionality you require is not in the main PHP library, you have
two choices. If you need something pretty simple, you can choose to write your own
function or object. However, if you’re looking at building a fairly complex piece of func-
tionality—such as a shopping cart,Web email system, or Web forums—you won’t be sur-
prised to find that these probably have already been built by somebody else. One of the
strengths of working in the Open Source community is that code for application com-
ponents such as these is often freely available. If you find a component similar to the one
you want to build, even if it isn’t exactly right, you can look at the source code as a
starting point for modification or for building your own.
If you end up developing your own functions or components, you should seriously
consider making them available to the PHP community when you have finished. This is
the principle that keeps the PHP developer community such a helpful, active, and
knowledgeable group.
Writing Maintainable Code
The issue of maintainability is often overlooked in Web applications, particularly because
we often write them in a hurry. Getting started on the code, and getting it finished
quickly sometimes seems more important than planning it first. However, a little time
invested up front can save you a lot of time further down the road when you’re ready to
build the next iteration of an application.
Coding Standards

Most large IT organizations have coding standards—guidelines to the house style for
choosing file and variable names, guidelines for commenting code, guidelines for indent-
ing code, and so on.
Because of the document paradigm often previously applied to Web development,
coding standards have sometimes been overlooked in this area. If you are coding on your
own or in a small team, it’s easy to underestimate the importance of coding standards.
Don’t do it because your team and project might grow.Then you will not only end up
28 525x ch22 1/24/03 3:38 PM Page 442
443
Writing Maintainable Code
with a mess on your hands, but also a bunch of programmers who can’t make heads or
tails of any of the existing code.
Naming Conventions
The goals of defining a naming convention are
n
To make the code easy to read. If you define variables and function names sensibly,
you should be able to virtually read code as you would an English sentence, or at
least pseudocode.
n
To make identifier names easy to remember. If your identifiers are consistently for-
matted, it will be easier to remember what you called a particular variable or func-
tion.
Va r iable names should describe the data they contain. If you are storing somebody’s sur-
name, call it
$surname.You need to find a balance between length and readability. For
example, storing the name in
$n will make it easy to type, but the code will be difficult
to understand. Storing the name in
$surname_of_the_current_user is more informa-
tive, but it’s a lot to type (easier to make a typing error) and doesn’t really add that

much.
You need to make a decision on capitalization.Variable names are case sensitive in
PHP, as we’ve mentioned before.You need to decide whether your variable names will
be all lowercase, all uppercase, or a mix, for example, capitalizing the first letters of words.
We tend to use all lowercase, as it’s the easiest thing to remember.
It’s also a good idea to distinguish between variables and constants with case—a com-
mon scheme is to use all lowercase for variables (for example,
$result) and all uppercase
for constants (for example, PI).
One bad practice some programmers use is to have two variables with the same name
but different capitalization, just because they can, such as $name and $Name for instance. I
hope it is obvious why this is a terrible idea.
It is also best to avoid amusing capitalization schemes such as $WaReZ because no one
will be able to remember how it works.
You should also think about what scheme to use for multiword variable names. For
example:
$username
$user_name
$UserName
are all schemes I have seen used. It doesn’t matter which you opt for, but you should try
to be consistent about this.You might also want to set a sensible maximum limit of two
to three words in a variable name.
Function names have many of the same considerations, with a couple of extras.
Function names should generally be verb oriented. Consider built-in PHP functions
such as addslashes() or mysql_connect(),which describe what they are going to do
28 525x ch22 1/24/03 3:38 PM Page 443
444
Chapter 22 Using PHP and MySQL for Large Projects
to or with the parameters they are passed.This greatly enhances code readability. Notice
that these two functions have a different naming scheme for dealing with multiword

function names. PHP’s functions are inconsistent in this regard, presumably partly as a
result of having been written by a large group of people, but mostly because many func-
tion names have been adopted unchanged from various different languages and APIs.
Also remember that function names are not case sensitive in PHP.You should proba-
bly stick to a particular format anyway, just to avoid confusion.
You might want to consider using the module naming scheme used in many PHP
modules, that is, prefixing the name of functions with the module name. For example, all
the MySQL functions begin with mysql_, and all the IMAP functions begin with
imap_.If, for example, you have a shopping cart module in your code, you could prefix
the function in that module with cart_.
In the end, it doesn’t really matter what conventions and standards you use when
writing code, as long as some consistent guidelines are applied.
Commenting Your Code
All programs should be commented to a sensible level.You might ask what level of com-
menting is sensible. Generally you should consider adding a comment to each of the fol-
lowing items:
n
Files, whether complete scripts or include files. Each file should have a comment
stating what this file is, what it’s for, who wrote it, and when it was updated.
n
Functions. Function comments should specify what the function does, what input
it expects, and what it returns.
n
Classes. Comments should describe the purpose of the class. Class methods should
have the same type and level of comments as any other function.
n
Chunks of code within a script or function. I often find it useful to write a script
by beginning with a set of pseudocode style comments and then filling in the
code for each section. So an initial script might resemble this:
<?

// validate input data
// send to database
// report results
?>
This is quite handy because after you’ve filled in all the sections with function calls
or whatever, your code is already commented.
n
Complex code or hacks.When it takes you all day to do something, or you have
to do it in a weird way, write a comment explaining why you did it that way.This
way, when you next look at the code, you won’t be scratching your head and
thinking,“What on earth was that supposed to do?”
28 525x ch22 1/24/03 3:38 PM Page 444
445
Writing Maintainable Code
Another general guideline to follow is that you should comment as you go.You might
think you will come back and comment your code when you are finished with a proj-
ect. I guarantee you this will not happen, unless you have far less punishing development
timetables and more self-discipline than we do.
Indenting
As in any programming language, you should indent your code in a sensible and consis-
tent fashion. It’s like laying out a resumé or business letter. Indenting makes your code
easier to read and faster to understand.
In general, any program block that belongs inside a control structure should be
indented from the surrounding code.The degree of indenting should be noticeable (that
is, more than one space) but not excessive. I generally think the use of tabs should be
avoided.Although easy to type, they consume a lot of screen space on many people’s
monitors.We use an indent level of two to three spaces for all projects.
The way you lay out your curly braces is also an issue.The two most common
schemes are as follows:
Scheme 1:

if (condition) {
// do something
}
Scheme 2:
if (condition)
{
// do something else
}
Which one you use is up to you.The scheme you choose should (again) be used
consistently throughout a project to avoid confusion.
Breaking Up Code
Giant monolithic code is awful. Some people will have one huge script that does every-
thing in one main line of code. It is far better to break up the code into functions
and/or classes and put related items into include files.You can, for example, put all your
database-related functions in a file called
dbfunctions.php.
Reasons for breaking up your code into sensible chunks include the following:
n
It makes your code easier to read and understand.
n
It makes your code more reusable and minimizes redundancy. For example, with
the previous dbfunctions.php file, you could reuse it in every script in which
you need to connect to your database. If you need to change the way this works,
you have to change it in only one place.
28 525x ch22 1/24/03 3:38 PM Page 445
446
Chapter 22 Using PHP and MySQL for Large Projects
n
It facilitates teamwork. If the code is broken into components, you can then assign
responsibility for the components to team members. It also means that you can

avoid the situation in which one programmer is waiting for another to finish
working on GiantScript.php so that she can go ahead with her own work.
At the start of a project, you should spend some time thinking about how you are going
to break up a project into planned components.This requires drawing lines between
areas of functionality, but don’t get bogged down in this as it might change after you get
going on a project.You will also need to decide which components need to be built
first, which components depend on other components, and the time line for developing
all of them.
Even if all team members will be working on all pieces of the code, it’s generally a
good idea to assign primary responsibility for each component to a specific person.
Ultimately this would be the person who is responsible if something goes wrong with
her component. Someone should also take on the job of build manager—that is, the per-
son who makes sure that all the components are on track and working with the rest of
the components.This person usually also manages version control—we’ll talk about this
more later in the chapter.This person can be the project manager, or it can be allocated
as a separate responsibility.
Using a Standard Directory Structure
When starting a project, you need to think about how your component structure will be
reflected in your Web site’s directory structure. Just as it is a bad idea to have one giant
script containing all functionality, it’s usually a bad idea to have one giant directory con-
taining everything. Decide how you are going to split it up between components, logic,
content, and shared code libraries. Document your structure and make sure that every-
body working on the project has a copy so that they can find things.This leads in to the
next point.
Documenting and Sharing In-House Functions
As you develop function libraries, make them available to other programmers in your
team. Commonly, every programmer in a team writes her own set of database, date, or
debugging functions.This is a time waster. Make functions and classes available to others.
Remember that even if code is stored in an area or directory commonly available to
your team, they won’t know it’s there unless you tell them. Develop a system for docu-

menting in-house function libraries, and make it available to programmers on your team.
Implementing Version Control
Ve rsion control is the art of concurrent change management as applied to software
development.Version control systems generally act as a central repository or archive and
28 525x ch22 1/24/03 3:38 PM Page 446