Upgrade

In general

CREATE A BACKUP OF YOUR DATABASE BEFORE PERFORMING ANY UPGRADE.

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

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

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

PostgreSQL

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

MySQL

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

    to

    SET NAMES utf8

    Then replace all occurences of

    DEFAULT CHARSET=latin1

    with

    DEFAULT CHARSET=utf8
  • 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

PostgreSQL

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

MySQL

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:

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