Information for Developers

From PKP Wiki
Revision as of 15:11, 24 October 2012 by Alec (Talk | contribs) (Removed CVS instructions)

Jump to: navigation, search


You can access our Bugzilla database here. We welcome any bug reports and feature requests, so long as they are understandably written and flagged correctly (mostly an issue of setting the severity between enhancement; trivial; minor; normal; major; critical; or blocker levels, although you can also set the priority as well if you'd like). You can see a great set of bug-writing guidelines here.

You are also advised to search for similar reports to avoid duplication.


Making Patches

We're always happy to receive patches, whether for contribution to a project or for general community availability on the forums. The one thing we do ask is that you provide the patch in Unified Diff format. If you are using our git instructions to work with the application codebase (highly recommended), you can create unified diffs via git using the following command:

git diff -u ./ > patch.diff

... which will find all differences in the working directory and recursively, and write them to a file called patch.diff.

Applying Patches

If you want to apply a patch, download it to your development environment, and from the application's root directory and run

patch -p0 < ./path/to/patch.diff

The --dry-run option to the patch tool allows you to safely test the patch to see if it will apply cleanly, and if not, where the conflicts will arise.

For more Windows (and general) information, also see this forum thread.

Setting up a flexible development environment

NB: This is not a beginner's installation/configuration tutorial. We only highlight a few important differences from a standard installation as a help for experienced PKP, database, PHP and web server users.

Install and Configure Databases

  • There is nothing special to the database installation. Use your OS' standard installation procedure to install the necessary databases you want to test in parallel.
  • Edit to switch the database connection.

Install and Configure supported PHP versions

  • Download or build the PHP binaries you want to test (newer versions can be downloaded from or are part of the standard OS distributions, older versions must be built from source).
  • You'll need the thread-safe version if you want to test mod_php in Apache.
  • Install all binaries and configuration separately. Do not create any shared files or configuration (separate php.ini, separate installation directories).
  • On Windows:
    • Get the PHP zip arquive distributions where available and unzip them into separate folders.
    • XAMPP has lots of old Windows binaries if the version you look for is no longer officially supported on
    • Download the thread-safe VC6 version as VC9 versions are not compatible with Apache.
    • Do not install DLL files in C:\WINDOWS or any other directory on the path.
    • Do not install any registry keys.
    • Do not configure any shared environment variables.
  • Exception: Install PEAR in a central folder that is accessible by all PHP versions. Install necessary PEAR dependencies (e.g. PHPUnit, etc.) - see separate documentation on this Wiki for that.
  • Edit the development php.ini files as required:
    • extension_dir must point to the absolute path of the version specific extension binaries
    • enable extensions required by PKP software (e.g. database client, GD, etc.)
    • for PHP 4's php.ini only: cgi.fix_pathinfo=1
    • optional: error_reporting, display_errors, log_errors, error_log, max_execution_time, xdebug
  • Test all PHP installations separately: /path/to/php -c /path/to/php.ini -v (This should discover most problems with wrong extension paths).

For PHP 4 only: If you get an error "Client does not support authentication protocol requested by server" or simply "Database connection failed" in PHP4 while everything works fine for PHP5 then you may have created your MySQL account with a new style password.

Entering the following statement from a working MySQL client should fix the problem:

SET PASSWORD FOR 'some_user'@'some_host' = OLD_PASSWORD('newpwd');

Install and Configure Apache

We use Apache so that we can test CGI, FCGI and Module configurations in parallel. Install Apache 2.2 (standard distribution for your OS). Then get and install mod_fcgid as explained on the linked web pages.

All the magic lies in Apache's httpd.conf. Here's the Windows version. It should be easy to adapt that to your specific OS:

#General CGI Support
<IfDefine CGI>
    LoadModule cgi_module modules/
    AddHandler application/x-httpd-php .php
#General FCGI Support
<IfDefine FCGI>
    LoadModule fcgid_module modules/
    AddHandler fcgid-script .php
    <Directory "C:/path/to/your/pkp/doc/root">
        Options +ExecCGI
#PHP 4.3 support
<IfDefine PHP43>
    <IfDefine CGI>
        Action application/x-httpd-php "/php-cgi/php.exe"
        ScriptAlias /php-cgi/ "C:/path/to/php43/"
        <Directory "C:/path/to/php43">
            Order allow,deny
            Allow from
#PHP 5.2 support
<IfDefine PHP52>
    <IfDefine MODULE>
        LoadFile "C:/path/to/php52/php5ts.dll"
        LoadFile "C:/path/to/php52/libmysql.dll" # This is required (PHP52 only) otherwise PHP might load libmysql.dll from MySQL's own bin
        LoadModule php5_module "C:/path/to/php52/php5apache2_2.dll"
        PHPIniDir "C:/path/to/php52"
    <IfDefine FCGI>
        FcgidWrapper "C:/path/to/php52/php-cgi.exe" .php
    <IfDefine CGI>
        Action application/x-httpd-php "/php-cgi/php-cgi.exe"
        ScriptAlias /php-cgi/ "C:/path/to/php52/"
        <Directory "C:/path/to/php52">
            Order allow,deny
            Allow from
#PHP 5.3 support
<IfDefine PHP53>
    <IfDefine MODULE>
        LoadFile "C:/path/to/php53/php5ts.dll"
        LoadModule php5_module "C:/path/to/php53/php5apache2_2.dll"
        PHPIniDir "C:/path/to/php53"
    <IfDefine FCGI>
        FcgidWrapper "C:/path/to/php53/php-cgi.exe" .php
    <IfDefine CGI>
        Action application/x-httpd-php "/php-cgi/php-cgi.exe"
        ScriptAlias /php-cgi/ "C:/path/to/php53/"
        <Directory "C:/path/to/php53">
            Order allow,deny
            Allow from
DocumentRoot "C:/path/to/your/pkp/doc/root"
<Directory "C:/path/to/your/pkp/doc/root">
    Options +FollowSymLinks
    AllowOverride All
    Order allow,deny
    Allow from all

Now all you need to switch configurations is starting Apache like this:


A few examples:

http -DPHP43 -DCGI
http -DPHP53 -DFCGI

Please note that PHP 4.3 only supports CGI mode. PHP 4's module is only compatible with Apache 1.3 or 2.0 and PHP 4 does not correctly interpret fcgi's PATH_INFO when used with the FcgiWrapper directive.

PHP 4 compatibility coding oddities collection

We'll not try to reproduce a full catalogue of PHP4/5 incompatibilities here. Have a look at which is quite complete. There are however some PKP-specific solutions to certain compatibility problems that we document here.

Chaining -> accessors

PHP 4 does not support the chaining of -> accessors. We therefore write:

$someTempVar =& $firstObject->getOtherObject();
$someTargetVar =& $someTempVar->getTargetObject();

Passing objects as method parameters

Most of the more serious PHP4 compatibility problems have to do with the fact that PHP5 passes and assigns objects by reference by default while PHP4 makes shallow copies if not explicitly asked to use references. This results in a few coding particularities that I'll describe here.

We always use explicit by-ref method parameters when possible. This will automatically guarantee PHP4/5 compatibility:

function myMethod(&myObject) { ... }

Assigning objects to variables by-ref

We always assign objects explicitly by-ref when possible. This will automatically guarantee PHP4/5 compatibility:

$myObject =& $myOtherObject;

Default values for by-ref method parameters

PHP 5 allows default values for by-ref method parameters while PHP 4 doesn't. Default parameters for by-ref objects usually don't make sense. There's one notable exception though: Initializing a variable with null when the by-ref parameter is optional. As PHP4 doesn't support assinging default values to default parameters, we'll write

function myMethod(myObject = null) {...}

to maintain PHP4 compatibility although this is less efficient in PHP4.

Returning parameters by-ref

Returning non-variable return values by-ref in PHP 5 generates a warning while PHP 4 tolerates this. We therefore always use the following workaround:

function &myMethod() {
    $returner = null;
    return $returner;

Use of $this in the constructor

This is a tricky one. To understand it look at the following code:

class Test {
    var $instance;
    var $data;

    function Test() {
        $this->instance =& $this;

$instanceFromNew = new Test();
$instanceFromConstructor =& $instanceFromNew->instance;

$instanceFromNew->data = 1;
$instanceFromConstructor->data = 2;

echo $instanceFromNew->data."\n";
echo $instanceFromConstructor->data;

This will result in the output 1 - 2 for PHP 4 and 2 - 2 for PHP 5.


$instanceFromNew = new Test();


$instanceFromNew =& new Test();

Solves the problem in PHP 4 but causes a deprecation warning in PHP 5.3.

This is especially problematic in our case as we use lambda functions for validation that are created in the constructor and often get $this passed in as a parameter. If we don't use ... =& new ... in the caller then changes made by the instantiating caller to the object later on will not appear to the validator in PHP 4. This leads to validation errors and can cause security vulnerabilities. In PHP 5.3 the deprecation warning will be raised on parse time. This means that the workaround no longer works. We have to switch off E_DEPRECATION in PHP 5.3 until we drop PHP 4 compatibility.

Our solution to this problem is:

  • When you create a reference to $this within the constructor that will later be used to access data in the object instance that might be changed by the instantiating caller then you'll have to use the following workaround:
  if (checkPhpVersion('5.0.0')) { // WARNING: This form needs $this in constructor
      ... = new ...;
  } else {
      ... =& new ...;
  • In all other cases just use
... = new ...

in the caller. This is a little less efficient in PHP 4 but makes the code more readable and easier to maintain.