User guide

Developer coding guidelines

    Coding Style

    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.

    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 (preferred) or $_something
    • camelCaseFunctionNames() are preferred. Example: printImageTitle()
    • Try to make your function names "speaking", so the name says what it generally does.
    • Functions that just get data without printing should be prefixed with a "get" and functions 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 (the correct syntax shoud be <?php) as they may not be usable on certain strict PHP installations
    • Avoid if/else short term writing for better code reading. Better always use brackets:
      if ($something) {
          echo "something";
      }
    Theme functions.php and plugins

    Prefix (preferred) or suffix your function names matching your theme's or plugin's name. So instead just using printSomething(), use mytheme_printSomething() or printSomething_mytheme(). This also helps users customizing your theme to notice which functions are unique to your theme/plugin and also avoids accidentally same named function conflicts with plugins or Zenphoto itself. Especially if you customize standard template functions.

    A good alternative to prefixing/suffixing is using a (static) class as a wrapper for all your custom functions like for example mytheme::printSomething(). Or you go the object way with a class in general.

    A few guidelines for coding in general:
    • 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. For function comments we generaly follow the PHPdoc style.

    Sanitizing and clearing

    Zenphoto provides a set of functions to perform this task:

    $_GET / $_POST / $_REQUEST

    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.

    Values for display

    Items from $_GET/$_POST entries or any unknown text you should be encoded 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() when there may be album names or query strings in the link.

    Note: It is recommended that the encoding of strings for display is 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 retrieved 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 format 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 support build of Zenphoto between releases, you can download it 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 has been moved to GitHub since Zenphoto 1.4.4 entirely.

    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 extensive lists. Note that not all clients feature all Git commands. 

    Recommended additional read: General contributor guidelines

    Creative Commons LicenseThis text by www.zenphoto.org is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

    For questions and comments please use the forum or discuss on the social networks.

    Related items