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 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.

    A few general rules:

    We are very well aware that existing legacy code is not always consistent with this rules. But newer code should follow these (and older code may/will be changed on the go as needed and spotted if it doesn't break anything).

    These apply and are mandatory if you contribute to Zenphoto core but we recommend to use this for your own themes and plugins as well.

    General code

    • 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.
    • Try to make your function and variable names "speaking", so the name says what it generally does or stands for. Even if the name gets longer by doing this.. Eg: $album_name instead of $an and printImageTitle()instead of p_it()
    • Avoid if/else short term writing for better code reading. Better always use brackets:
      if ($something) {
          echo "something"; 
      }
    • 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
    • Use HTML as HTML and only echo lines via PHP but avoid larger HTML chunks or complete pages because it disables syntax highlighting in the editor and is generally inconvenient.

    Function/Method/class names

    • camelCaseFunctionNames are preferred over underscore names. Example: printImageTitle(). (Yes, we still have a lot underscore names in our code as well).
    • Very long names may use underscores for readability, especially class names that also need to be readably as filenames.
    • Functions/methods that just get data without printing should be prefixed with a "get" and functions that echo something with "print". Examples:
      • getImageTitle(): gets the plain title to be passed to a variable for processing.
      • printImageTitle(): echos the title directly including filter processing or additionall HTML markup.

    Variable names

    • Variable names should be all lowercase to avoid typos as the case makes a different: Instead of $MyAlbum use $myalbum.
    • Use underscores to make variable names better readable: $my_album;
    • Global variables should always be named like $_zp_something (preferred - especially for general ones) or $_something (for limited local ones within plugins for example) so you can spot instantly what it is.

    File names

    Generally files should be named speaking so you get an idea what it is by its name.

    • Filenames should be all lowercase to avoid accidental typos as server UNIX systems are case senstive other than WIndows or MacOS
    • Procedural function files should use the prefix "functions-", e.g. functions-somespecific.php. These should not contain any executional code.
    • Class files also should use the prefix "class-", e.g. class-classname.php. 
      • The class name in the file should match the actual class name: If you class is name myClass_special the file must be class-myclass_special.php.
      • There should only be one class per file.
      • The the file should not contain any executional code.
    • Executional files are just named after what they do like global_definitions.php
    • Executional files that are split into individual file for better organizations and are not to be used directly/standalone but to be included within other files should be prefixed like inc-whatever.php.

    Theme functions.php and plugins

    We recommend to use on of these ways to help users customizing your theme or working with your plugin to notice which functions are unique to your theme/plugin. It also avoids accidentally same named function conflicts with plugins or Zenphoto itself:

    • Use 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. This is the recommended way although not all official (legacy) code follows it itself yet. The more complex your theme or plugin is use more than one class.
    • The class way is preferred and recommened but if using procedural functions prefix or suffix your function names matching your theme's or plugin's name. So instead just using printSomething(), use mytheme_printSomething() or printSomething_mytheme().

    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: https://git-scm.com/downloads

    If you find using the console inconvenient, that site also has a list of graphical Git clients: https://git-scm.com/downloads/guisAt 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.

    Code examples are released under the GPL v2 or later license

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

    Related items