### Navigation

- index
- next |
- previous |
- phpaga v0.6-beta1 documentation »

# Upgrade

## In general

### Data

CREATE A BACKUP OF YOUR DATABASE BEFORE PERFORMING ANY UPGRADE.

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

### Requirements

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.

### Help

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

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

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

### Libraries

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.

### Sidebar

In case you are missing the (optional) sidebar after a successful upgrade: this is not a bug - the sidebar has been removed in favour of a cleaner layout.

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

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

### Navigation

- index
- next |
- previous |
- phpaga v0.6-beta1 documentation »