Team development method for PHP

Introduction

In this article I am going to explain one of possible ways of developing PHP applications in a team. This method emerged during our work on information system for students of the Ankara University (http://ogrenci.ankara.edu.tr).

I would like to thank Onur Boyaci and Dincer Akay and all the other people who took part in the project.

Methods of PHP development

Most widely method

I would call it a HTML encapsulation method because rather that embed PHP in HTML, HTML is encapsulated and 'echo'ed by PHP:

...
<table>
<?php
for ( $i=0; $i<10; $i++ )
  echo "<tr><td>This is line number $i</td></tr>";
?>
</table>
...

Another aspect is that different PHP files are used. For example for search page we would have a 'search.php' and for login page 'login.php'.

I would call this method a 'CGI' method because it resembles traditional CGI programming approach. Such a wide use of it is probably influenced by that CGI tradition, general 'programming' approach and some features of HTML, namely luck of aims for separation content from presentation.

This model has many good points. It offers a better control over execution and presentation of the content, aids separation to functions by enabling a programmer to write chunks of HTML code in functions thus helping to structure the program up; which in turn makes it more understandable and manageable. Giving more control to programmer helps to manage resources in a more rational fusion.

But there are shortcomings. HTML encapsulated that way is very hard to update with WYSIWYG tools, there is a lot of recurrence and code becomes cluttered.

Proposed principles

Let me first outline the concept and then explain it in detail:

• Single 'selector' file
• Database abstraction layer
• Embedding PHP
• Separation to files by functionality

Single 'selector' file

Idea is to collect all the common functionality in the same place. I'm using the following structure:

<?php
// Include all the necessary files
include("db.abstraction.php");
...
// Connect to the database
sqlConnect();
...
// Perform the necessary action
switch( $action )
{
  case "add":
    addNote( $title, $body );
    break;
...
}
...
// Select the appropriate page to show
switch( $page )
{
  case "update":
    include("update.php");
    break;
...
}
...
// Disconnect from the database
sqlDisconnect();
?>

So what are the advantages of this approach?

• All the common functionality is gathered in one place. Authentication, opening database connections or session management is done in a single place and for all the files.
• Now you do not need to include relevant utility files into every page - it is done 'centrally'.
• Once you want to update some PHP code you do not need to search for it in a respective file between heaps of HTML markup but correct it in a single file.
• For team work it provides a valuable separation between logic and presentation.

And what are the disadvantages? Hmm, well, resource management could be better - database connections are opened even for files which do not access database in any way and you have to pass extra parameters in your queries. 'action' and 'page' in this case.

Database abstraction layer

Writing database-related functions I've noticed a very interesting thing: I've only done 3 different things:

• execute SQL query which does not return any result
• execute a query and get all the results
• and execute a query and get only the first row

This can be summed up in 3 database abstraction layer functions plus connection and disconnection:

• sqlConnect()
• sqlExec( $query )
• sqlGetResult( $query )
• sqlGetRow( $query )
• and sqlDisconnect()

Once you want to switch to another database or just change something in the way it works, just change the abstraction layer functions! So much for the abstraction layer.

Embedding PHP

As opposed to encapsulating HTML. Idea is to leave as much as possible of HTML intact so that people working on HTML design can easily redesign the page if necessary. Let's rewrite the first example conforming to this method:

...
<table>
<?php
for ( $i=0; $i<10; $i++ )
{
?>
<tr><td>This is line number <?php echo $i; ?></td></tr>
<?php
}
?>
</table>
...

Hope you see the point.

Separation to files by functionality

Another point is to separate files by functionality so that all the project becomes more manageable and easier to write as a team. In the example following this chapter, files separated as following:

• 'index.php' - the 'selector' file
• 'db.abstraction.php' - database abstraction layer
• 'db.functions.php' - utility database functions
• other '.php' files - HTML pages with embedded PHP

Example

To illustrate the ideas I explained above I have written a small notebook using MySQL database. You can download it from here: notebook.tar.gz.

Now let me show how this project can be developed by a team. Usual development cycle consists of:

1. Analysis
2. Implementation
3. Testing
4. Deployment

After the last stage usually a second cycle follows. I will skip testing and deployment here.

Analysis

Let's start from the analysis. We want a user of our notebook to be able to:

• Add notes
• View note list
• View each note
• Update notes
• Remove notes

And a note should consist of:

1. Id - for proper unique identification
2. Title - a short description
3. Body - full text

Which means that we will have to design following pages:

1. 'list.php' which would feature the complete list of all the messages (only titles here) and links for updating and removing notes and for adding a new one.
2. 'new.php' for adding a new note
3. 'update.php' for updating existing ones
4. 'remove.php' an 'are you sure' page actually - so as not to delete notes by mistake.

and following database utility functions:

1. addNote( $title, $body ) - to add a new note
2. updateNote( $id, $title, $body ) - to update an existing one
3. removeNote( $id ) - to remove a note
4. listNotes() - to list all the notes (titles)
5. getNote( $id ) - to get a complete note (title and body)

Implementation

Now it's time for team work. Different people can be assigned to the following fields:

• 'index.php', the 'selector' file - all the 'actions' are done here
• HTML design
• Embedding PHP code into HTML
• Writing utility database functions
• Writing abstraction layer

As for the abstraction layer, once written it can be just copied from project to project with minor changes. With abstraction layer in place, writing database utility functions becomes all too trivial:

<?php
...
function addNote( $title, $body )
{
  execSQL( "insert into notes (title,body) values ('$title','$body')" );
}
...
?>

Refer to the code for detail on writing other files.

Conclusion

Hope the method I have described above would be helpful as it have been for me. And sorry for poor english and style.