VirtueMart Developer Portal

Developer Guidelines

General

Using and updating the Changelog

Please use the date, your SVN username and the following characters to indicate a modification:

• -> Bug Fix
• + -> Addition
• ^ -> Change
• - -> Removed
• ! -> Note

An example entry could like like this:

06-09-2006 soeren_nb

^ changed this and that
# fixed bug no. 75 [Bug desription]
+ added feature from request no. 56 [feature description] 

Because you’re not the only one working on a development version, please add all queries which are necessary to update a database to comply with your changes.

^ ## Database structure changed ##
    ALTER TABLE mos_pshop_order_user_info ADD `extra_field_1` varchar(255) default NULL; 

Please read the section "Database" for all notes about the database and its scheme.

Compatibility

Supported PHP Versions

• VirtueMart 1.1: PHP >= 4.2.
• VirtueMart 1.2: PHP >= 5.2.
• VirtueMart 2.0: PHP >= 5.2.

MySQL version compatibility As there is no "real" database abstraction in Joomla!, we keep compatibility to MySQL. All SQL queries must be compatible with at least MySQL version 4.0.

Mambo Version compatibility

Future versions of VirtueMart won't support Mambo

Joomla! Version Compatibility

• VirtueMart 1.0.x is compatible to all Joomla! 1.0 versions (1.0.0 - 1.0.15).
• VirtueMart 1.1 is compatible to the Joomla! 1.0 and 1.5 series.
• VirtueMart 1.2 will be compatible to Joomla! 1.5 only.
• VirtueMart 2.0 will only be compatible to the Joomla! 1.5 and 1.6 series. 

Accessibility

Javascript

Coding Guidelines

Register Globals is Off

All code must work with PHP register_globals = Off.

Single Quotes vs. Double Quotes

Use single quotes to refer to an index between brackets of an array (example: $foo['name'] and not $foo[name] or $foo["name"]). Use single quotes instead of double quotes as much as possible because it’s faster to parse.

Line Spacing

Indent using 4 spaces or a tab.

Variable Settings

Always run PHP with full Error Reporting Level (E_ALL). You can change this level in the Joomla! Configuration (see "Server" => Error Reporting Level) and in your PHP.ini. Always initialize variables: (just $a=0 is initialization). Use isset( $var ) to check if a variable has been set. Use empty( $var) to check if Array indexes have been set or are empty.

PHP Code Tags

Always use <?php to delimit PHP code, not the shorthand. This is required for PEAR compliance and is also the most portable way to include PHP code ondiffering operating systems and setups.

Source Code Management Info (SVN)

$Id Tag inside the heading comment

Example: /* $Id: $ */ - a SVN client will automatically fill this header tag with valid information.

Header Comment Blocks

All source code files in the repository shall contain a "page-level" docblock at the top of each file and a "class-level" docblock immediately above each class. Below are examples of such docblocks.

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 *
 * @package    VirtueMart
 * @subpackage classes_product
 * @author     Original Author
 * @author     Another Author
 * @copyright  2008 VirtueMart Development Team
 * @license    http://www.gnu.org/copyleft/gpl.html GNU/GPL
 * @version    $Id:$
 */

/*
 * Place includes, constant defines and $_GLOBAL settings here.
 * Make sure they have appropriate docblocks to avoid phpDocumentor
 * construing they are documented by the page-level docblock.
 */

/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @author     Original Author
 * @author     Another Author
 * @copyright  2008 VirtueMart Development Team
 * @license    http://www.gnu.org/copyleft/gpl.html GNU/GPL
 * @version    Release:
 */
class foo {
    /** @var database Internal database class pointer */
    var $_db=null;
    /** @var object An object of configuration variables */
    var $_config=null;
    /** @var object An object of path variables */
    var $_path=null;
   /** @var mosSession The current session */
    var $_session=null;
    /** @var string The current template */
    var $_template=null;
   /** @var array An array to hold global user state within a session */

    /**
    * This function does something special.
    * @param string The name of the product
    * @param int The ID of the product
    * @return string HTML Table with a "snapshot" of the product
   */
    function myFunction( $arg1, &$arg2 ) {
        if( $that ) {
            doThis(); \\        }
    }
}

?>

Required Tags That Have Variable Content

Short Descriptions

Short descriptions must be provided for all docblocks. They should be a quick sentence, not the name of the item, but the description of the „what does this file / class?“.

@license

VirtueMart is released under the GNU/GPL license. You should keep this license for best compatibility.

• @license http://www.gnu.org/copyleft/gpl.html GNU/GPL

There’s no hard rule to determine when a new code contributor should be added to the list of authors for a given source file. In general, their changes should fall into the “substantial” category (meaning somewhere around 10% to 20% of code changes). Exceptions could be made for rewriting functions or contributing new logic.

Simple code reorganization or bug fixes would not justify the addition of a new individual to the list of authors.

Optional Tags

@copyright

Feel free to apply whatever copyrights you desire. When formatting this tag, the year should be in four digit format and if a span of years is involved, use a hyphen between the earliest and latest year. The copyright holder can be you, a list of people, a company, the PHP Group, etc. Examples:

• @copyright 2003 John Doe and Jennifer Buck * @copyright 2001-2004 John Doe * @copyright 2005 XYZ Corporation Order and Spacing

To ease long term readability of source code, the text and tags must conform to the order and spacing provided in the example above. This standard is adopted from the JavaDoc standard.

VirtueMart Source Code

Read more about how to obtain the VirtueMart source code and build the installer.

How to work with the Documentation Sources

General

VirtueMart manages its documentation in the DocBook format. You can checkout the sources in the DocBook format and transform the DocBook source using an XSL Transformer into PDF, HTML, CHM or whatever else...

The documentation source can be obtained by checking out the trunk from the SVN repository (see first section on this page).

Modifying and Improving the documentation

The best software to modify DocBook sources is the XML Mind XML Editor. After you have downloaded and installed the software you can just open the main documentation file and start working on it:

• /documentation/User_Manual/User_Manual.xml (the User Manual)
• /documentation/Developer_Manual/Developer_Manual.xml (the Developer Manual)

Database

Changes to the main db schema require a that an upgrade patch is posted as well. Your change will be backed out if you don’t provide a patch as well.

Changelog!

First of all you need to make an entry in the Changelog, including the SQL Queries to update a database scheme.

SQL Update File

All changes to the database scheme are collected in an SQL file. There’s a file for each minor version jump, e.g.

UPDATE-SCRIPT_com_virtuemart_1.1.0-to-1.2.0.sql

The file can be found in the subdirectory /sql.

A user must see which version of VirtueMart this SQL patch file applies to and to which version it updates the db scheme.

In this case the SQL file would update a db scheme from version 1.1.0 to 1.2.0.