PHP Application Development Part One

Settling for the “quick and dirty” solution often costs far more time than it saves. This is as true of PHP coding practices as anything else. In this first article in the series, you will learn practices that will save you time and headaches in the long run, and help you write better PHP code.

When building applications in PHP, it is often far too simple to settle for the “quick and dirty” solution – poorly written, monolithic code that will never be used again and lacks any clear intent. Since PHP is typically used in small projects that could themselves be described as “quick and dirty,” developers will excuse their poor code by stating that they will not have to work on the code again and that they have no intention of ever reusing it. The fact remains, however, that as with any job worth doing, it should be done well.

This paradigm holds true in this situation for a number of reasons. First, when you take the time to write good code, you will almost always find something reusable in any new code you write. Second, code will always require maintenance or changes. It may not be you, but it will be someone, someday – that is of course unless the code is so bad the poor fellow has to start from scratch. The intent of this article is to cover some of the most fundamental, low level rules of writing good PHP code.

The first practice we will discuss covers directory structure and security along with filesystem naming conventions for PHP applications. After that, we will cover some coding conventions such as function and variable naming, indentation, and more. Lastly we will review basic coding considerations to provide flexibility, scalability, and efficiency. Before beginning, let it be understood that some of the conventions advocated in this article could be considered a matter of preference and are by no means the single correct solution, however they are time tested and have proven effective time and again in application development.

{mospagebreak title=Directory structure conventions}

Directory structure and filesystem naming conventions are something that rarely receive enough attention in PHP applications. It is common practice to simply begin work and save all project files to a publicly accessible Web directory, despite the fact that many PHP files, especially configuration files and files uploaded through the application itself, never need to be directly accessed via the Web. It is also common to see files of all types – configuration files, function libraries, class files, logs, and so forth all mixed in the main application directory or all stuffed into one subdirectory.

In addition to this, files of all kinds tend to have haphazard names that often do not adequately convey the purpose of the file – a problem that is compounded when the files do not live in a directory that conveys the general purpose of a group of files. As a project grows, something seemingly insignificant like a bit of filesystem disorganization can become a maintenance nightmare.

It is important to organize your project files, period. Directories should have names that are meaningful and should be in the appropriate location. The image below is an example of what a basic PHP Web application directory structure should look like. Images used in this article will be captured in Windows but do not rely on any operating system specific features or system directories.

 

In this example, “public_html” is the Web accessible directory and “webapp” is our project directory. On Red Hat this might be “/home/webapp/”. The “public_html” directory (the default name for the web directory in Red Hat) will contain files a user would directly access in a Web browser, such as “index.php”. In this directory you would organize your css files, javascript files, and images into the appropriate directories. These files must be in the Web accessible directory since browsers need access to them.

The parent directory, “webapp”, is where all files that do not need to be accessed by a Web browser will reside. The “classes” directory will be used to store class files, the “config” directory will store configuration files, “lib” will store files containing function libraries, “logs” will contain our applications custom log files, and “templates” will be the directory where we store our HTML template files.

The names of these directories are clear and meaningful and reside in the proper locations. In a product intended for repeat use, files outside of the public Web directory would be stored in a centralized location on the server and accessed by project scripts at that location either directly or by creating symbolic links (shortcuts in Windows) to those directories.

There are some simple security considerations when planning your Web applications directory structure, one of which we addressed above – keeping files out of the Web accessible directory if they aren’t accessed via the Web. Other simple considerations include preventing directory listings, blocking hotlinking, and password protecting areas that require a login through .htaccess files (or IIS Virtual Directory configuration). Authentication through .htaccess files uses basic HTTP authentication and is only one possible method of requiring authentication on a directory.

{mospagebreak title=File naming conventions}

Once an appropriate directory structure is established, it’s time to consider file naming conventions. The directory structure above gives us obvious locations for our files but does not imply any sort of scheme for the names of the files themselves. When naming your files, it is of the utmost importance to give files meaningful names. If you have ever had to work through an existing system with poorly named files, you know how difficult it can be to figure out which files perform which functions.

The two most common conventions for file naming are “word separation” and “camel caps”. An example of word spacing would be a file named “new_member_signup.php”. An example of a file named with camel caps would be “newMemberSignup.php”. It is my opinion that camel caps is the appropriate convention in all situations and that neither files nor directories should begin with capital letters. Using this convention makes it easy to read file and directory names quickly and it is also simple to retype them, which is not the case when using word spacing.

It is also good to avoid file names that are redundant with the name of the directory containing them. You would not name a string function library “lib.string.php” and place it in the lib directory – if it is in the lib directory in the first place, you know that the file will be a function library – “string.php” will suffice. The same rule applies to class files, configuration files, etc. All in all, the conventions for the physical application are quite simple and easy to remember.

{mospagebreak title=Coding conventions}

As with your physical application, the logical application should also adhere to standard conventions. Classes, functions, variables and constants should all be named and formatted in a consistent manner that clearly and concisely conveys intent. Since we are discussing the logical application now, otherwise known as code, let’s go to a few examples. First, we will see an example of code that simply fails to adequately convey intent and lacks readability.

 <?php
 $_X = foo(2);
 print $_X;
 
 function foo($bar) {
 return $bar * $bar; }
 ?>

While this example is quite academic in nature, the point is made. The variable “$X” and the function “foo” do nothing to convey their intent – you must actually read the code inside of the function to know what will be displayed by this script. Imagine the function “foo” containing a complex algorithm and returning various codes if errors are encountered. You would have to work through the function line by line to determine exactly what is going on.

This example also displays very poorly formatted code in the function “foo”, making it somewhat difficult to look at. Additionally, the uppercasing of the variable “$X” puts the variable into the same formatting space as constants and superglobal variables in PHP, making it appear as if it were simply typed incorrectly. Consider now the improved version of our example.

 <?php
 $myNumber = 2;
 $mySquaredNumber = square($myNumber);

 function square($number)
 {
  return $number * $number;
 }
 ?>

Not only is this example easier to read, but the variables and the function name are clear, and it is obvious what the code is going to do without even reading the function defintion. Variables in this example are formatted with camel caps, just like files and directories in our application. This makes them easy to read and easy to type. Curly braces in our function definition appear on their own lines, improving the readability of the function and clearly encapsulating the code within them. Additionally, code directly following a curly brace should always be indented one tab space until the next closing curly brace. Let’s now expand our examples to see a second comparison. Afterward we will review our fundamental code formatting rules in list form.

 <?php
 print new foo_class(2);
 
 class foo_class{
 function foo_class($foo) { return $foo * $foo; }}
 ?>

This example is bad in even more ways than the first. To begin with, using a class instance in static context is wasteful. The class name does not give any hint as to what its purpose is, nor does the constructor method that is used to return the square of a given number. Again, this example is obviously academic but I’m absolutely certain that most PHP developers have seen code of this nature in the real world – it is never pretty to look at or maintain. Now, consider this revision.

 <?php
 $myNumber = 2;
 $myNumberSquared = Math::square($myNumber);
 print $myNumber;
 
 class Math
 {
  function square($number)
  {
   if (is_numeric($number) == false)
   {
    return 0;
   }
   
   return $number * $number;
  }
 }
 ?>

This example takes up a lot more screen space but it is infinitely easier to look at. Again, our variables have clear names that indicate their purpose. Our class, unlike variables and functions, begins with a capital letter. Classes should use the camel caps format with an upper case first letter – this makes it clear when seen in code that a class is being referenced and it also logically denotes the classes position in the heirarchy of the application, literally appearing at a higher level than functions.

The code within the class is neatly indented and all curly braces appear on their own lines, making blocks of code nested inside one another easy to distinguish. This example even adds some basic error checking to be certain that the parameter “$number” is actually a number. Note that we do a proper test on the return value of our call to “is_numeric”, avoiding the use of short-circuit boolean logic. I will return to this point later.

To sum up our coding conventions, here is a simple list of rules.

  1. Variables should be given appropriate names and use the camel caps format.
  2. Class names should be given appropriate names and use the camel caps format with the first letter capitalized.
  3. Function names should also use the camel caps format, like variables, and should have appropriate names. Function parameters should also be named appropriately. These same rules apply to class methods.
  4. Curly braces should appear on lines by themselves and code inside them should be indented one tab space.
  5. Constants should appear in all capital letters.
  6. Class variables should be given appropriate names, use the camel caps format, and begin with an underscore. Class variables should never be accessed from outside of the class, and using the underscore allows us to code functions with the same name as class variables without problems. In PHP 5, this is less of a stylistic issue because you can actually specify method and variable visibility.
  7. Classes, functions and variables should never be named redundantly. That is, a function should not be named “fn_square” and a class should not be named “MathClass.”

Those six rules cover the fundamentals of stylistic coding conventions. Adhering to these conventions, whether you adhere to them exactly as described or make small changes to suit your style, will greatly improve the readability of code.

{mospagebreak title=PHP coding conventions}

The last topic of this article deals with fundamental PHP coding conventions. While it is never appropriate to prematurely optimize code, there is a set of basic rules to adhere to when coding PHP to maximize the efficiency of your code at the lowest level. In many applications these tips may never be an issue because the website may never be busy enough to require finely optimized code, however this does not mean we should write sloppy, inefficient PHP. Furthermore, there are many times when every microsecond of performance makes a difference, and when you are working on this type of mission critical project it is important that you have already trained yourself to write code that adheres to conventions stylistically as well as linguistically.

One of the simplest of these fundamental rules is the appropriate use of single quotes (‘) and double quotes (“). PHP will parse everything between a pair of double quotes searching for variables or nested expressions, whereas PHP treats anything inside of single quotes as a literal string. Consider the following example.

 <?php
 $typeOfString = “double quoted”;
 $myString = “This is a ”$typeOfString” string<br />n”;
 ?>

Not only is this difficult to read, because the variable is tucked into a string literal, it is inefficient. While it may only take a miniscule amount of time for the parser to deal with these strings, in a larger context with a great deal of string processing, the extra parse time can have a noticeable effect on performance. Instead, strings should be coded like the following example.

 <?php
 $typeOfString = ‘single quoted’;
 $myString = ‘This is a “’.$typeOfString.’” string<br />’.”n”;
 ?>

In this example, all string literals are enclosed in single quotes. The only double quoted string here is the newline escape sequence “n” which will not be correctly interpreted by PHP in single quotes. The parser simply has to concatenate two string literals with a variable and an escape sequence here, meaning very little text is actually processed.

While the next point does not apply in PHP 5, objects in PHP 4 are by default passed by value, not by reference, which can lead to inefficiencies throughout code. Objects in PHP 4 should be assigned initially by reference and then passed by reference as often as possible to minimize needless object creation. Consider the difference between the following examples.

 <?php
 $obj = new MyObject();
 callSomeFunction($obj);
 ?>

In this example, PHP will first create an instance of the “MyObject” class, then copy it into the “$obj” variable. When we execute “callSomeFunction($obj)”, the object is again copied and sent to the function for local use. If “MyObject” is a substantial class containing a lot of data, this is a big problem. More importantly, there are really not any common situations where an object should be passed by value – with that in mind consider the following example.

 <?php
 $obj = &new MyObject();
 callSomeFunction(&$obj);
 ?>

In this example PHP creates the “MyObject” instance and assigns it to “$obj” by reference instead of by value, meaning no additional copy is created, simply a pointer to a location in memory. This is repeated in the call to “callSomeFunction($obj)” where we pass a reference to the original object rather than a copy. This allows the function to do meaningful work with the object and even change its state without having to return a copy of the object to the calling code – it can simply modify the object reference, which is effectively modifying the original object itself.

One of the major points of concern I have observed in PHP applications is the needless coding of objects and functions to perform tasks that can already be performed by some function in PHP. This is most often the case with string, array and error handling functions. The only point I wish to make on this matter is that anyone working on a PHP application should be comfortable with using the manual. I frequently consult the manual even after more than three years of developing PHP applications full time. Always be sure to check the manual for functions that can satisfy your needs – using built in functions is significantly faster than using user functions.

On this point, it is important to choose the proper control structures for a job – knowing which structures are faster in which situations comes from experience and research. It is also important to use control structures in the most efficient way possible. In a loop, for example, minimizing the recalculation of values that do not change during execution of the structure is a good way to maintain efficiency. Consider the following examples.

 <?php
 $myArray = array(‘a’, ‘b’, c’);
 for ($i = 0; $i < count($myArray); $i++)
 {
  print $myArray[$i];
 }
 ?>

In this example, the number of elements in “$myArray” is recalculated on each iteration. This could be avoided by using the “for” loop like this:
 
 for ($i = 0, $ii = count($myArray); $i < $ii; $i++)

Here the number of elements in “$myArray” is saved when we initialize our incrementor, and never recalculated. Small matters like this, compounded with many other seemingly small matters discussed in this article, when tended to properly, can lead to code that scales smoothly without refactoring.

On to the next point – never use register_globals. Not only is it a security risk, it strips your data of context, forcing your code to make assumptions about the source and the trustworthiness of the data. Take advantage of the superglobal variables and use the “$GLOBALS” variable sparingly – constants are typically more suitable for data that needs to be globally accessible. Furthermore, avoid the use of the “global” statement – it creates inflexible, monolithic code that can often lead developers on a wild goose chase in search of the initial meaning of the variables being declared as global. If you have objects that need to be accessed in a global context, simply pass the object as a reference to any code that depends on it. This makes intent clear and never leaves you or other developers wondering where information comes from.

The last fundamental efficiency issue that I would like to bring up is avoiding excessive use of included files. While I completely advocate and encourage organization of code and minimizing duplication, it is also important to avoid going overboard with modularizing your code. If you do need highly modular code and have code spread across a great deal of include files, be sure that the actual Web scripts that depend on those files only include the files they need. If you have fifty class files and a script only needs two of them, it should not include them all. In very small applications, and even in some medium sized applications, there is no performance hit for this, depending on traffic and the server hardware.

Excessive use of include files leads to excessive disk IO, a fact that can hinder performance at exponential rates as traffic on a Web application increases. Do not be afraid to modularize your code because of this; simply be judicious and avoid wasteful file includes. One way to help with this is to use the “include_once” and “require_once” statements to avoid duplicate file inclusions. Another is to allow include files to include dependent files on their own, effectively chaining include files together. This allows your main script to include a class file directly and allows the class file to include any other files that it depends on itself, keeping the class functionality independent of the parent script. This helps a great deal in maintenance and avoiding confusion about what files must be included to use which pieces of functionality.

{mospagebreak title=Conclusion}

I hope this article has provided some insight into the basic fundamental considerations when planning and developing a PHP application. The need for organization in any application is self evident, especially to developers who have worked on someone else’s (or even their own) ugly, unorganized code. This begins at the physical level, organizing files into meaningful directories and giving files meaningful names. It is continued at the logical level, where following conventions of style and linguistics lead to simple to read, clear code that makes its intent clear to the reader.

We have also discussed basic considerations for writing efficient PHP code – a topic that certainly goes well beyond the scope of this article, but which also has some simple considerations to keep in mind when building an application.

The next article in this series will cover more concrete application planning issues, such as data storage, logging, error handling, and configuration management and implementation. Throughout this series, we will build on the knowledge from previous articles and in the end, have a somewhat comprehensive guide to developing efficient, scalable, and maintanable PHP applications.

[gp-comments width="770" linklove="off" ]
antalya escort bayan antalya escort bayan