Writing Libraries in PHP

[ben2ong2]

Writing libraries in PHP

By Bill Moran


 
Intended Audience

This tutorial is intended for PHP programmers who are interested in writing reusable code. Experience with PHP4 and familiarity with writing classes are assumed. The article is primarily geared toward programmers who are new to writing code libraries, but experienced programmers may find the article informative as well.
Introduction
The core of any programming language is its API. The API (application programming interface) is the set of available functions that allow a programmer to use the programming language. Compare an API to the language's syntax, which is the rules for stringing the various commands together so the interpreter can understand them.

Most of the documentation on PHP is focused on explaining the functioning of the various APIs PHP has available. Likewise, if you create a PHP library, most of the work involved is usually in sorting out how the API will work.

When you code a library, your primary goal is to write code that can be reused. You might be concerned with code reuse within a single application or maybe you want to publish the library for others to use. Taking the time to code your library properly results in code that often becomes more useful than you initially expected, and reduces the time it takes you to create the rest of your application. It also makes it easier to involve other programmers in your project. Obviously, a well-written library is much more likely to be useful to other programmers than one that was created carelessly.

Libraries generally take on two forms: functions and classes. PHP is a language that I generally classify as "hybrid" because it has most of the capabilities of an object-oriented language, yet the native PHP API is functional in nature. The shortcomings of PHP's object programming are not bad enough to warrant avoidance of writing class libraries. In fact, the examples and explanations in this article are based completely on class libraries, so I'll be covering some of the workarounds for those shortcomings.
General Rules
Define the Goal
The first thing to do when writing a class library is to determine the goal of the library (actually, this should be done before starting any kind of project, whether programming or not). I could go into a long discussion of exactly how to define the goal and exactly how much detail is required, but suffice it to say that more is better.

I've seen this called “defining the ideal scene". You build a little utopia in your mind and imagine what your library would do if it were perfect. Identify key elements to this success. Is it simple? Is speed a critical concern? Must it accept many different types of input or can you establish firm guidelines for input? Security is always a concern, so will your library handle it or will it be up to the application that uses the library? Defining what the library will not do is often just as important as defining what it will do.

Be sure to document the goal. Depending on how your project is organized, you might include it in a README file. Documenting the goal helps keep you focused on what's important. Everyone has time constraints, focusing on what's important allows you to make the best use of your time. It also keeps you from turning the library into something it was never intended to be. The term "feature creep" was coined by people who either never documented a goal for their project, or ignored the goal after they started working. Documenting the goal is also important if the library is going to be made public. It keeps you from getting requests for features that don't belong, and avoids misunderstanding.
Document
Begin documenting immediately after you determine what your goal is. Actually, documenting the goal of your library bleeds right over into documenting the rest of the library.

[ben2ong2]

This DSN is actually many parameters cemented into a string. If you are connecting to a MySQL database named 'foobar' with the username: 'john' and password: 'doe' on a host called: 'spydor'; the DSN would be 'You are not allowed to view links. Register or Login;. All done in one argument! Contrast this with the plethora of functions one has to call using PHP’s native MySQL support just to connect to a database.

However, to make sense of the DSN from any other string, DB::connect() has to be internally separated into individual arguments like the username, password, hostname, database type and the database name always an additional step. Since things like making connections to a database are generally done only once in a script, gluing strings together to make a single argument and separating them doesn't have a serious impact on performance. Steer clear of functions that parse arguments internally if you have to use them in a script regularly, for example in loops.
Write quality functions
Say you want to set the header-block of an HTML document before pushing it off to the browser. (The header-block is all the stuff between the <head>...</head> tags.) Assume that you want to set both a title and a meta tag. Instead of an odd setHeader({title/meta}, name, value="") function that does it all, using setTitle(title) and setMeta(name, value) separately is a better solution. This sets the title and the meta tags independently of each other.

A header can have only one title tag, but it can have multiple meta tags. When that happens the code will have to call setMeta() multiple times. In such cases, a better solution is to pass setMeta() a two-dimensional array with name-value pairs, and have the work done in one fell swoop.

In general, one-shot functions such as this one are preferable. It's always better to call a function once with all the data it needs to process rather than to invoke it multiple times and feed it arguments incrementally at each call. The idea here is to write a function to minimize calls to it from other code.

In this light, our setHeader() solution was really a kludge. We can obviously refractor setHeader() to setHeader(title, array="") - where the array contains all the name-value pairs for the meta tag. But we must also consider the lost ability to set the title and meta tags independently of each other.

Also, in real-world environments a header can contain more tags than just title and meta. If suddenly, more tags need to be added after an application is ready, one will have to change setHeader() and alter all other code that depends on it. On the other hand, if the setTitle() and setMeta() approach was, used the change would only require writing one more function and then using it.
Optimizing functions
Many developers make the mistake of trying to optimize functions prematurely. The moment they find that they have a useful function at hand, they’ll get down to optimizing it. Remember that optimization is a relatively late step, and is best done when your Web application is ready. With the increasing time-to-deploy expectations that clients have these days, it makes perfect sense to complete the Web application, wait and see which functions get hit most, and then optimize them.