Zenphoto

Coding Style

A few rules:

• Spaces should be used liberally. Eg: if($x == 2 || $y == 3) and not if($x==2||$y==3).
• Indentation should be hard tabs, not space-emulated tabs.
• Always use variable and function names that make sense and are self explanatory. Eg: $album_name and not $n
• $underscored_variable_names are preferred. Global variables should always be named like $_zp_something
• camelCaseFunctionNames() are preferred. Example: printImageTitle()
• Try to make your function names "speaking", so the name says what it generally does.
• Function that just get data without printing should be prefixed with a "get" and function that echo something with "print". Examples:
  • getImageTitle(): gets the title to be passed to a variable for processing.
  • printImageTitle(): echos the title directly.
• Don't use PHP "short tags" like <? in themes and plugins whereas the correct syntax shoud be as they may not be usable on certain strict PHP installations

Zenphoto code follows some basic style guidelines. We essentially use the 1TBS variant of the K&R notation C-code syntax, for example:

function foo($bar) {
 if ($bar == 2) {
   return $bar;
 } else if ($bar < 2) {
   while($bar < 2) {
     echo $bar;
     $bar++;
   }
 }
}

This is a fairly standard formatting for PHP code and makes things nice and readable.

And a few guidelines for coding in general that we encourage:

• Use generalization and abstraction. DRY! (Don't repeat yourself).
• Keep it simple - if something seems too complex it probably is.
• Keep efficiency in mind - try not to put filesystem operations in nested loops, for example.
• Write clean code! Make things readable and understandable.
• Comment your code so that others can understand it. Remember we are open source.

Sanitizing and clearing

Zenphoto provides a set of functions to perform this task:

$_GET / $_POST

Values you get from these super globals need to be secured. Use the function sanitize() and sanitize_numeric() for that purpose. The general rule of thumb is that these should be sanitied before storing in local variables to insure that this is not forgotten.

Values for display

If you items from $_GET/$_POST entries or any unknown text you should encode them using html_encode() when output for display. For links you should encode using pathurlencode(). PHP also has the urlencode() function which can be used on simple URLs, but to be safe use pathurlencode() if there may be album names or query strings in the link.

Note: it is recommended that encoding of strings for display be done in the statements that actually do the display. This avoids the possiblity of someone double encoding a string because they did not know it had already been done.

Values stored in the database

These should have already been sanitized if got from $_GET or $_POST and then formatted using db_quote() in the query string.

Commenting and Documentation

Zenphoto uses PHPDoc to generate function and class documentation. This works well because the documentation is both in-line with the code, and browsable externally as a reference.

Zenphoto's PHPDoc reference is on the main zenphoto.org site.

Instructions for how to form comments for functions and variables can be found on PHPDoc's site here. Or take a look at Zenphoto's code for examples.

Also don't forget to comment other parts outside the PHPdoc comment blocks if necessary.

Development build on GitHub

If you would like to simply test the development releases of Zenphoto between releases, you can the development version from GitHub. 

The nightly builds are located at: https://github.com/zenphoto/zenphoto/

Warning: The development packages may be unstable and haven't been thoroughly tested. Use them only if you wish to help test new features and give us feedback.

GitHub

Version control of the Zenphoto development will be moved to GitHub after Zenphoto 1.4.4 entirely. The development of 1.4.4 that version has already been move there:
https://github.com/zenphoto/zenphoto

Git clients

You can use Git via the console/terminal on your computer. You might need to install the Git binary libary first. You find install packages for all major systems here: http://git-scm.com/downloads

If you find using the console inconvenient, that site also has a list of graphical Git clients: http://git-scm.com/downloads/guis
At the bottom there are links to even more extensiv lists. Note that not all clients feature all Git commands (the official GitHub client for Mac for example is really stripped down to the basics). 

Submitting changes

If you have changes you would like applied to Zenphoto releases procede as follows:

1. First try hard to find a way to implement your change as a plugin. We are committed to the "Zen" part of Zenphoto and would like to keep the mainline as trim as possible.
2. Develop your code based on the "development" branch of Zenphoto. The development nightly build is a good place to start.
3. When you have completed your testing and debugging, double check you code against the latest SVN or nightly build to be sure that it contains all current updates.
4. Create a ticket on the bugtracker for the feature/fix if there is not already one. Attach your edited files to the script. A good idea is to Zip them into an archive that reflects the Zenphoto file structure so we know exactly where they go.
5. Understand that for various reasons we may choose not to incorporate your changes into the official release. Most predominately this would happen if we feel we would not be able to provide continued support of the feature/changes.) If you developed a plugin, then we would encourage you to make it available to interested users.

Recommended additional read: General contributor guidelines