In general



You are advised to back up your data before performing any upgrade.

User files

From the previous installation, keep etc/config.local.php, files/ (contains uploaded files), and any custom plugins from plugins/ (for versions >= 0.6).


Check whether the software requirements have changed at the section Requirements.

Web server

Some web servers need to be restarted when new or updated language catalogs are installed (under locale/).

Database structure

Since after 0.3, phpaga features a web interface for database upgrades which can be opened at “System / Database upgrades”. Once you have installed the new release, open this page and follow the instructions shown there.


If you need additional help consider joining the user’s mailing list.

Upgrading from 0.6-beta* to 0.6


If you are upgrading from a 0.6-beta package, you might need to remove the NOT NULL condition from the bmt_classname field in the billing_methods table. You can do that by opening a psql shell (or the database administration tool of your choice) and issuing the following statement:

alter table billing_methods alter column bmt_classname drop not null;

Upgrading from 0.5.2 to 0.6

Billing plugins

Billing plugins have been moved to the directory plugins/billing/. If you had any custom plugins under lib/bill/ make sure you move them to their new place.

Also, billing plugins are now classes that extend the base class BillingDetails. Plugins that ship with phpaga have been converted. If you use a custom billing plugin you will need to migrate it to the new format. See Billing plugins for information on how to migrate existing plugins.

After upgrading to 0.6 and applying the database upgrade - and each time you install a new plugin - you must open the billing plugins management page (under Administration, Billing plugins). This will try to automatically recognize the migrated billing plugins, and allow to you manage all available billing plugins. (This step is required for the invoicing functionality to continue to work.)

User settings

The way user settings are stored has been changed (and made more flexible). These changes are not visible to the user, but any existing user’s (personal) configuration settings have to be configured again. This regards only a very few settings (mainly the number of records per page and some sorting preferences), therefore no migration script has been provided. Sitewide settings and permissions are not lost during this upgrade.

Language settings

The handling of language settings has been simplified. After the successful upgrade, all users will most likely default to English and will need to select their desired languages from within their user settings.

PDF customization

PDF files are now generated by TCPDF. The previously used PDF templates can no longer be used. If you have used custom PDF templates you will need to write new templates that are based on the PDF base classes.

Smarty 3

Smarty 2.x has been replaced by Smarty 3 (3.0.5 or later). In order to avoid any problems, you need to remove the compiled templates from the templates_c/ directory. Also, if you have written your own template set, make sure the templates are still valid.


If you are using the code from the bitbucket repository you need to install above new libraries (TCPDF and Smarty 3). This step is not necessary if you downloaded an official phpaga release package, as the libraries are bundled with the package.

To install the required TCPDF library: download the latest package and unzip it under phpaga/ext/, so that phpaga/ext/tcpdf/ contains the library and its subdirectories.


If you are using MySQL, and you are upgrading from any previous release, you might need to change the database engine used for the products table. You can do that by opening a mysql shell (or the database administration tool of your choice) and issuing the following two statements:

ALTER TABLE products_prod_id_seq ENGINE = InnoDB;

Upgrading from 0.5.1 to 0.5.2

After installing 0.5.2, an error will be shown when opening the dashboard. This is due to the fact that the tasks’ start and end dates need to be migrated to a different data type. Simply open “System / Database upgrades” and follow the instructions on screen.

Upgrading from 0.5 to 0.5.1

After installing 0.5.1, open “System / Database upgrades” and follow the instructions on screen.

Upgrading from 0.4 to 0.5

Invoices and payments

Support for payments on unpaid invoices/bills has been added. During the database upgrade from 0.4 to 0.5, all existing invoices will be automatically migrated.

If you have written your own billing plugin make sure to update it to make use of the payments system. Use one of the billing plugins that ship with phpaga to see what changes are necessary.

eZ Components / jqPlot

ezComponents are no longer used; graphs are now created with jqPlot, a plotting and charting plugin for the jQuery Javascript framework. phpaga comes with jqPlot (and jQuery) included, so no extra installation is required.

Upgrading from 0.3 to 0.4

JpGraph / eZ Components

JpGraph is no longer used; graphs are now created with ezComponents. See above about eZ Components installation.

PEAR replaced

PEAR is no longer required. All dependencies on PEAR packages have been replaced by phpaga’s own code.

Billing plugins

Filed (tracked) expenses can now be added to invoices. If you have written your own billing plugin you need to apply a few little changes. First, and most important, a new parameter needs to be added to the function parameter. Then, the invoice calculation details need to be extended. Also, billing plugins are no longer supposed to return an error code. Refer to one of the billing plugins that come shipped with phpaga to see what needs to be changed.

File upload and pictures

Files can now be associated to persons. The script tools/migrate_personpictures.php can be used to migrate the existing pictures (from persons.pe_fotoname to files).

UTF-8: Locales and database

UTF-8 is now used as the encoding for all supported locales. Unfortunately, in previous releases phpaga used to store data in a different format (depending on your locale, most likely LATIN1). Therefore you need to convert the database to UFT-8 before using phpaga 0.4. You will also need to make sure that the desired locales are available in UTF-8.

If you have been storing data with different encodings in the same database, the conversion will most likely produce garbled data, no matter what database system you are using.

iconv is a tool to convert the encoding of given files from one encoding to another; it should be available on most *nix-like systems. If it is not already installed, consult your package management system. A Win32 port of iconv is available at gettext (& libiconv) for Win32 with downloads at http://sourceforge.net/project/showfiles.php?group_id=25167 (fetch the libiconv-*-bin.woe32.zip package).


If for some technical reason you are not able to perform the steps below (for example because you do not have administrative rights to drop and create a database) you can enable the setting PHPAGA_PGSQL_ENCODING in etc/config.local.php. Read more about this setting in its description directly in the file. It is highly recommended, though, that you perform the steps below and migrate the existing data and structure to UTF-8.

The following steps need to be taken to convert the existing database (and data) to use UTF-8:

  • Create a database dump

    pg_dump -Fp -U phpaga phpaga >| /tmp/phpagadump.sql
  • Convert the database dump to UTF-8

    iconv -f LATIN1 -t UTF-8 phpagadump.sql -o phpagadump.sql.utf8

    Replace LATIN1 with the appropriate encoding for your data. Most likely this is will be LATIN2 if you were using the Hungarian locale, KOI8-R if you were using the Russian locale, and LATIN1 for most other languages supported by phpaga in versions <= 0.4.

  • Edit phpagadump.sql.utf8 and make sure that the line

    SET client_encoding = 'LATIN1';

    is changed to

    SET client_encoding = 'UTF8';
  • Connect to the database server from the terminal (psql)

  • Drop the existing database

    template1=> drop database phpaga;
  • Create the database with the proper encoding (‘UTF8’ for PostgreSQL 8.x, ‘UNICODE’ for PostgreSQL 7.x)

    template1=> create database phpaga with encoding 'UTF8';
  • Connect to the database

    template1=> \c phpaga
  • Restore the database from the converted dump

    phpaga=> \i phpagadump.sql.utf8


The following steps need to be taken to convert the existing database (and data) to use UTF-8. Replace “latin1” in the following example with the encoding currently used by your database. The procedure described below is not guaranteed to work - while it can work for certain data and encodings, it can also produce garbled data under certain circumstances.

  • Create a database dump

    mysqldump --default-character-set=latin1 -p -u username phpaga > phpagadump.sql
  • Edit phpagadump.sql and change the statement

    SET NAMES latin1


    SET NAMES utf8

    Then replace all occurences of



  • Connect to the database server from the terminal (mysql)

  • Drop the existing database

    mysql=> drop database phpaga;
  • Create the database with the proper encoding (‘UTF8’)

    mysql=> create database phpaga default character set utf8 collate utf8_general_ci;
  • Exit from the database terminal

  • Restore the database from the dump

    mysql --default-character-set=utf8 -p -u username phpaga < phpagadump.sql

Upgrading from 0.2 to 0.3

After 0.2 the internationalization mechanism was switched from definitions to gettext. Make sure your version of PHP supports gettext and has the locales for the languages you want to use installed. (See Requirements)

All application settings that were formerly defined in etc/config.php are now managed within phpaga itself. Once you have configured etc/config.local.php, you can fire up your browser and change these settings from the Admin menu (“Sitewide settings”).

Make sure you have PEAR DB version >= 1.6. Install the PEAR packages Log and Mail and all other required PEAR packages.

Execute the scripts required to upgrade the database structure. Depending on the RDBMS you are using, this will be sql/upgrade_0.2-0.3.pgsql for PostgreSQL or sql/upgrade_0.2-0.3.mysql for MySQL. If you use MySQL, execute also sql/mysql-innodb.mysql; this will convert all database tables to the InnoDB format.

phpaga 0.3 introduces a permission system. In order to migrate to the permission system, the former administrator gets all available permissions. It is then in her responsibility to assign the proper permissions to the remaining users. The necessary SQL statement to perform this migration is contained in the upgrading scripts (see above paragraph).

phpaga 0.3 introduces news to the billing system. Invoices can now have line items. In order to convert the existing invoices to the new format, you will need to run a conversion script. This script must be run after upgrade_0.2-0.3.(pgsql|mysql) has been applied and before any new invoice is created. The script is named convert_invoices.php and located in the directory tools/. Open the file with an editor and set the parameters in the first section according to your configuration. Then run the script from the shell.

Upgrading from 0.2rc1 to 0.2

Configuration settings are now defined via web. You will need to replace your old etc/config.php with the new one from the package, and later change the settings from the Admin menu (“Sitewide settings”).

Smarty and the R&OS pdf class are no longer bundled with phpaga. Refer to the Requirements section to find instructions on where to find and how to install these packages.

Upgrading from earlier versions


Execute the proper upgrade*.sql script from sql/.


From 0.1.1 to 0.2

The following instructions give you the necessary information to upgrade your phpaga database under MySQL from phpaga 0.1.1 to phpaga 0.2.

Since phpaga 0.2 we use Pear::DB to abstract database access. Since MySQL does not support sequences directly (it has the ‘autoincrement’ feature), Pear needs a set of help tables that contain the sequence values.

  • Apply sql/upgrade_0.1.1-0.2.mysql and sql/phpaga_sequences.mysql:

    $ mysql -uroot -p phpaga < sql/upgrade_0.1.1-0.2.mysql
    $ mysql -uroot -p phpaga < sql/phpaga_sequences.mysql
  • The user passwords need to be migrated from MySQL password() to md5 hashes, in order to have a common way to manage encrypted passwords on different rdmbs. You can use md5sum to generate md5 hashes. Example (under Debian GNU/Linux):

    $ md5sum.textutils --string oldpassword
    d5b5fffc89f961903fb3c9a173f1b667  "oldpassword"
    mysql> UPDATE users SET usr_passwd = 'd5b5fffc89f961903fb3c9a173f1b667'
    WHERE usr_login = '@YOUR_LOGIN@';

    If you do not have md5sum.textutils you can create a small php script that contains the following lines:

    echo md5('@PASSWORD@');

    and either parse it via the command line php or via a php-enabled webserver and the output string will be the correct md5 value for your password.

From 0.2-rc1 to 0.2

In order to upgrade from phpaga 0.2-rc1 to 0.2 release simply apply sql/upgrade_0.2_rc1-0.2.mysql:

$ mysql -uroot -p phpaga < sql/upgrade_0.2_rc1-0.2.mysql

Migrating phpaga from MySql to PostgreSQL

Starting with version 0.2-rc1 phpaga features database abstraction through Pear::DB. As of version 0.2 the following rdbms are supported:

  • PostgreSQL
  • MySQL

If you want to migrate your phpaga data from MySQL to PostgreSQL you might find the following instructions of help.

  • Create a mysqldump of phpaga containing just the data:

    mysqldump -uphpaga -pyourdbpasswd -c -t phpaga > phpaga_data.sql
  • Connect to the PostgreSQL phpaga database with pgsql using the phpaga db user:

    psql phpaga phpaga
    phpaga=> \\i phpaga_data.sql

    Check the output for errors.

  • Set the sequences to the correct values:

    phpaga=> \\i /path/to/phpaga/sql/phpaga_setseqvals.pgsql

This should be it. Please report any problems via the mailing list.