CREATE A BACKUP OF YOUR DATABASE BEFORE PERFORMING ANY UPGRADE.
You are advised to back up your data before performing any upgrade.
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.
Some web servers need to be restarted when new or updated language catalogs are installed (under locale/).
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.
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;
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.)
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.
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 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 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.
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.
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 ENGINE = InnoDB;
ALTER TABLE products_prod_id_seq ENGINE = InnoDB;
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.
After installing 0.5.1, open “System / Database upgrades” and follow the instructions on screen.
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.
JpGraph is no longer used; graphs are now created with ezComponents. See above about eZ Components installation.
PEAR is no longer required. All dependencies on PEAR packages have been replaced by phpaga’s own code.
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.
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 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
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
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.
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.
Execute the proper upgrade*.sql script from sql/.
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.
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
Starting with version 0.2-rc1 phpaga features database abstraction through Pear::DB. As of version 0.2 the following rdbms are supported:
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.