Information for Developers

From PKP Wiki
Revision as of 00:18, 5 January 2010 by (Talk | contribs) (Add multi-version PHP env installation 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.

CVS Access

Web-based CVS

You can browse our CVS repository online here.

Command Line CVS access

(This is not a guide on how to use CVS. For more CVS information, try here, here, and here.

You can check out all CVS modules via anonymous CVS. Before you do so, you should know which modules, exactly, you want to work with. OJS and OCS each have a stable and devel branch; the stable branches are standalone maintenance releases (extensions of OJS 2.2.2 and OCS 2.1.1 codebases), while the devel branches also requires the PKP Web Application Library (WAL) be checked out and installed in the lib/ directory. Harvester2 and Open Monograph Press only have one devel branch, and each require the PKP WAL. Lemon8 is a standalone program with only one branch at the moment.

Setting up the Environment

The following instructions are more or less directly applicable to any *nix operating systems (OS X incl.); Windows users probably need to do things a little differently. Also, these are general instructions, pertaining to how I manage my own setup -- you might want to do things a little bit differently.

Firstly, create a CVS directory to store all your cvs checkouts in. I created mine in /Users/jmacgreg/ and then entered into the new directory, from which I ran the remaining commands:

mkdir /Users/jmacgreg/cvs
cd cvs

You'll then have to log into our CVS repository using our anonymous credentials:

cvs -d login

You will be asked for a password — there is none, so just hit enter. After which you should be able to run the following commands to grab specific modules.

OJS and OCS stable branches

To grab the OCS and OJS stable branches, run the following commands:

cvs -d checkout -d ojs2-stable -r ojs2-branch-2_2_2 ojs2

The above command will download the current code for the OJS 2.2.2 branch of the ojs2 module, and deposit in a new 'ojs2-stable' directory in the directory you are currently in (you moved to your cvs/ directory, right?)

cvs -d checkout -d ocs2-stable -r ocs2-branch-2_1_1 ocs2

The above command will download the OCS 2.1.1 code into ocs2-stable/.

Setting this up to be served by Apache is up to you (I have it symlinked to my web folder). Remember, while this branch is still fairly stable in comparison to the heavily modified devel branch, it's still a work in progress and shouldn't be used in a production environment unless you know what you're doing.


To checkout the most recent Lemon8 code, run

cvs -d checkout -d lemon8-xml lemon8-xml

The above command will download the latest Lemon8 development code into a new lemon8-xml directory.

Development Branches

OJS and OCS development branches, as well as the only Harvester2 and OMP (and de facto development) branches, all work a little differently: they all rely on the PKP WAL module as a dependency. The WAL module needs to be 'installed' (symlinking is fine) in each branches' lib/ directory.

First, checkout the packages you need:

OJS devel (2.3):

cvs -d checkout -d ojs2-devel ojs2

Harvester devel (2.3):

cvs -d checkout -d harvester2 harvester2

OMP devel (2.3):

cvs -d checkout -d omp omp

Now the tricky part. You need to download the PKP WAL (called 'pkp' in CVS) and either copy it or symlink it to your devel instances' lib/ directory. I prefer symlinking, as I can do this for each devel instance I'm running, and only have to remember to update one directory.

Checkout the pkp module:

cvs -d checkout -d pkp pkp

Symlink the module to eg. OJS' lib/ directory:

ln -s /Users/jmacgreg/cvs/pkp /Users/jmacgreg/cvs/ojs2-devel/lib/pkp

... and repeat as necessary for each application.

Alternatively, it is possible to change into the ojs2-devel/lib and create, what are called, relative symlinks:

 cd ojs2-devel/lib
 ln -s ../../pkp


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 patching against one of the above CVS modules, the easiest thing to do is generate your patch using something like the following command (which will generate a diff of the entire directory you are currently in, for example ojs2-devel, against the entire cvs module):

cvs diff -uN ./ > 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.

Testing your code with all supported environments

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

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

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.

git Access (Incubation)

We are currently evaluating switching part of our internal development workflow to git. This is still work in progress. Only parts of Open Monograph Press (OMP) are currently developed in git.

We use git sub-modules to integrate our PKP application library into end-user applications. As this is a less known and a little tricky feature of git we developed a PKP-specific git sub-module tutorial for developers. Please follow the steps in this tutorial before starting to develop with git. It will help you to understand the basic concepts of git sub-modules and will also give you an idea of the general git repository set-up we use at PKP.

Once you have worked through the sub-module tutorial you may continue with HOW-TO check out PKP applications from git. This shows you the specific steps you should follow to set up a local PKP application development repository.

Those who love CVS but want to jump on git anyway should check out HOW-TO use git and CVS in parallel.