Collaborative (PHP/MySQL) web development standards

[spaceman]

Hi All,

I'm a web developer myself, but looking to sub-contract some work out to others (sorry - I'm not looking for applicants!).

What I want to get hold of, or develop myself, is a set of guidelines/standards that I can hand to some who does work for me and say "right, this is the framework within which I'd like you to work". It would be a general document of web development standards such which folder structure to use on the web server, which file extensions to use (eg. .php and not .php4...), whether to use CSS or not, which browsers to be compatible with, which php files I'd expect to see (eg. common.inc, functions.inc), etc.

In other words, it would attempt to establish a project-independent (as far as that is possible) web site development framework. Naturally, it would be a living document, subject to improvement based on accumulated experience. Far from being an attempt to 'tell a programmer how to program', the idea is to assist in the process of managing multiple programmers/developers collaborating on the same web development project at the same time.

Does anyone know of such a document that I could use as a template to build my own? Or perhaps you'd like to post some suggested basic guidelines of your own to this thread? Maybe you have other advice/ideas you'd like to share on the subject of collaborative web development?

Thanks very much.

[johnn]

Some suggestions:

- Proper use of indenting 2 or 3 spaces and the use of curly braces. I prefer
While (...)
{
....
}

- Error handlings in one format that you all agree with.

- Functions should begin with a verb. For example: use insert_record() instead of record_insert();

- Comments use - where to put in a function, a script, or next to a strange variable.

- If a file is pure html file, I'd like to append with htm such as htm_login_form.htm so that we can recognize it quick.

- Do not use Upper case letter in a variable such as $validAddress or $Validaddress

Any other suggestions?

John

[freddydoesphp]

Unfortunately with a language like PHP which has a such a loose standard, it will be hard to convince others to abide by your ways. It is fine to say you should keep db stuff in an included file or you should use .php extensions but with stuff like where to put curly brackets, its really a personal preference and really has no effect on the code. With that note I prefer

function make_upper($str) {
     return strtoupper($str);
     } 

Which is quite different from how johnn would do it but it has the same output

function make_upper($str) 
{
return strtoupper($str);
} 

That just looks confusing to me.

[Anarchos]

Yeah I indent that way too. And not allowing upper case characters in variable names is retarded. I prefer formatting function names and variables with a oneTwo naming scheme, and there is no reason to mandate capitalization. So I'd do:

function makeUpper($myStr){
     return strtoupper($myStr);
     } 

Depending on the size and directory structure of the project you might want developers to prepend or append their initials to all unique files so that naming clashes don't occur. Also you should make a few standard directories. I recommend something to the effect of:

/include: all included files
/css: style sheets
/scripts: javascript
/images: images
/secure: .htaccess-protected directory that cannot be accessed externally
/output: any text-file output generated by scripts
/log: error logs

[qslack]

Personally I prefer code like this:

# * Function: make_uppercase
# Description: Take a string, $str, and return
# it, completely in capital letters
function make_uppercase($str) {
        return strtoupper($str); # comment (note 8-space tab on this line)
} 

I document functions with "# *" so I can easily search through and print out only subroutines. This is a big help in some of my projects where I can have nearly 100 subs in a single file.

I use the following comment types in my code:

# * function
# & what the whole file does
# $ last time modified (filled in by CVS)
# normal comment
# % information about stuff that needs to be added 

And I use this file structure:
/index.pl - most of the stuff is passed through the querystring (no need for separate files)
/res/ - Short for "resources"
-----/img/ - Images
-----/inc/ - Include files
-----/css/ - CSS files
-----/tmpl/ - Templates
-----/logs/ - Logs
/admin/index.pl - For admin tasks

Other people tend to catch on to my commenting style pretty quickly. That's pretty much the only non-ordinary thing I do in my code.

[7stud]

Hi,

How do you create directory structures on your local pc? I have all the latest versions of php/mysql/apache on win98, and I tried creating a subdirectory in the document root and php/apache couldn't see those files, so all my files are just mixed together.

Also, should every function and include be in a separate file? If you combine several functions in one file, then when you include the file, you might include some functions you aren't going to use, so that would slow down your script wouldn't it?

I gravitated to this style:

function make_upper($str) 
{
    return strtoupper($str);
}

because you can see if your braces match up very easily.

lol...great quotes in your signature qslack.

[freakysid]

A great question. My main task today is to ponder the architecture of a suite of web applications I am putting together for a project. Most will be written by me and some are pre-existing scripts.

There is a interesting methodology for Cold Fusion application architecture called fusebox www.fusebox.com There is also an article (with mixed reviews in the user comments) at www.phpbuilder on adapting the methodology for PHP. There are a few other articles on architecture at www.phpbuilder.com/columns/ that may be of interest.

Here is another methodology http://www.zend.com/zend/art/free-energy.php .

As for coding standards, I was made aware of the PEAR standards for PHP in a post here by Phillip Olsen. Here is the link http://php.net/manual/en/pear.standards.php

Best of luck

BTW - I can't get too excited about where the curly braces go around blocks of code. However, blocked code should always be indented within a control structure. My university has three acceptable ways of placing the curly braces around control structures in its coding standard.

[spaceman]

How do you create directory structures on your local pc? I have all the latest versions of php/mysql/apache on win98, and I tried creating a subdirectory in the document root and php/apache couldn't see those files, so all my files are just mixed together.

I used phptriad (http://sourceforge.net/projects/phptriad/) to get my local W2K pc up and running with php, mysql, apache, and phpmyadmin. So now on my hard drive I have
C:\apache\htdocs\
and it's here that I create all my subfolders for the web site projects I work on. For example, if I'm working on xyz.com's web site, then I'll create the folder:
C:\apache\htdocs\xyz.com\
In the above folder I'll stick all the orginal image files and stuff that I don't want to be on the web server, and then in this folder:
C:\apache\htdocs\xyz.com\www\
I stick all the files that will be ftp'd to the web server (including the use of sub-folders such as \images\, \include\, etc.

If you've installed and configured apache/php/mysql correctly, then you should just be able to point your browser to:
http://localhost/xyz.com/www/
to see your web site in all it's glory.

If you don't see it, then there are heaps of other threads on this forum and others to help you to get it right.

The point is that I need to have my local machine (running Windows/Apache) configured as best I can so that I can copy the whole lot up to my remote web server (UNIX/Apache) without have to make any special adjustments to any part of the code in order to get it working properly.

The way I've just described above is the way that works for me, but there may be a better way (as there normally is in this business).

Also, should every function and include be in a separate file? If you combine several functions in one file, then when you include the file, you might include some functions you aren't going to use, so that would slow down your script wouldn't it?

I maintain my own local (and big) functions.inc file which I copy and paste from one project to the next, and then I always (try) to strip out all the functions that I don't need for the current project. A simple project might use just a couple of the functions - larger ones might require most of them. The whole lot totals to about 30K (but no single project requires the whole lot). In the web site's header.inc I include this single, tailored functions.inc file every time so that the whole 'tool box' is available to any page/script that might choose to delve into it. If my basic understanding of the way php/Apache work on the remote web server, I don't believe this approach to be a significant overhead in the bigger scheme of things.

I gravitated to this style:

function make_upper($str) 
{
    return strtoupper($str);
}

because you can see if your braces match up very easily.

I also gravitate toward being able to match-up my curly brackets at the same indent-level.

[spaceman]

A couple of points to add...

All my files that are explicitly for including in other scripts I give a '.inc' extension, and then I include this .htaccess file in the www folder of my remote apache web server:

AddType application/x-httpd-php .htm
<Files ~ "\.inc$">
Order allow,deny
Deny from all
</Files>

This serves two functions:
1. Allows me to have name HTML web pages with php inside with a '.htm' extension as opposed to '.php'. Why? Because I believe (but don't have scientific proof) that web pages named with a .htm/.html extensions are _generally_ more search engine friendly than other web page extensions such as .php, .asp, .cfn, etc.
2. Denies web browser access to anyone trying to view my '.inc' files.

[firepages]

I can't get too excited about where the curly braces go around blocks of code.

[DreamDevil]

I prefer to use


function make_upper($str)
{return strtoupper($str);
}

This way you can see clearly and fast to what function the section belongs.

Well it's just an idea, but for me I think it's a good one

[TWTCommish]

I keep it like this (pay no attention to the actual conditionals, they're dummies):

  if ($var) {

  } else if ($var) {

  } else {

  }

Why? Because I'd hate the idea of wasting an entire line on one character, like this:

  if ($var) { 

  }
  else if ($var) {

  }
  else {
  
  }

I usually enter require/include commands at the top (when using PHP), and then indent things below that two spaces in, and then indent things inside conditionals and loops two spaces in as well, like this:

require("global.php");
  if ($var) {
    print "Hey";
  } else {
    print "Whoa";
  }

[TWTCommish]

Originally posted by DreamDevil
I prefer to use


function make_upper($str)
{return strtoupper($str);
}

This way you can see clearly and fast to what function the section belongs.

Well it's just an idea, but for me I think it's a good one

That a dummy function? I hope so, because...

$text = make_upper($text);

...isn't any quicker than:

$text = strtoupper($text);

I figure it's probably just a filler function -- just checking.

[Anarchos]

Actually, running strtoupper() from another function is faster.

[TWTCommish]

Really? How so?

[freddydoesphp]

I would like to know how you came about that rationale as well

[Anarchos]

Sarcasm...

[freddydoesphp]

You shouldn't sound so confident in your theories if they are just sarcasm.

[TWTCommish]

No big deal -- just tack a smilie face at the end and we might figure it out

[MattR]

I try and stick to this convention:

if( $bob ) {

  do something

} else {

  do something else

} // end if

while( $joe_wallet >= 0 ) {
  
  $joe_wallet->spend( 1 );

} // end while

$bob[ 1 ] = str_to_downer_roger_niner( 43 );

//////////////////
// Function eat_my_shorts
// Recieves: $shorts -- pair of sorts to eat (array)
//            $teeth -- number of teeth to bite
// Returns: $success -- true or false value determining if the user ate the $shorts
//////////////////
function eat_my_shorts( $shorts, $teeth = 20 ) {

  if( $shorts->waistband > 35 ) {

    $success = 0;

  } else if( $shorts->waistband < 30 ) {
   
    $success = 1;

  } // end if

  if( $success ) {

    stuff;
  
  } // end if

  return $success;

} // end function eat_my_shorts


// other functions 

Most are conventions I picked up in C and I keep then around now simply out of habit.

[Philip Olson]

Aside from the pear standards (as mentioned above but deserves another look :-) :

http://www.php.net/manual/en/pear.standards.php

Be sure to check out the two 'php hackers paradise' articles :

http://www.e-gineer.com/articles/php...paradise.phtml
http://www.e-gineer.com/articles/php...evisited.phtml

Also, one might be interested in this three part series :

http://zend.com/zend/art/mistake.php

As well as the various slide presentations shown at various PHP confrences :

http://conf.php.net/

Also, freakysid eluded to the related phpbuilder articles, be sure to check them out too.