
.. _upgrade:

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
:ref:`requirements`.

Web server
----------

Some web servers need to be restarted when new or updated language catalogs are
installed (under :file:`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 :file:`plugins/billing/`. If
you had any custom plugins under :file:`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
:doc:`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 <http://www.smarty.net/>`_ (3.0.5 or
later). In order to avoid any problems, you need to remove the **compiled**
templates from the :file:`templates_c/` directory. Also, if you have written
your own template set, make sure the templates are `still valid
<http://smarty-php.googlecode.com/svn/trunk/distribution/SMARTY2_BC_NOTES>`_.

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 <http://www.tcpdf.org/>`_ library: download the
latest package and unzip it under :file:`phpaga/ext/`, so that
:file:`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
<http://www.jqplot.com/>`_, 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
:file:`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.

:program:`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 :program:`iconv` is available
at `gettext (&
libiconv) for Win32 <http://gettext.sourceforge.net/>`_ 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
:file:`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 :file:`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 :file:`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 :ref:`requirements`)

All application settings that were formerly defined in
:file:`etc/config.php` are now managed within
phpaga itself. Once you have configured
:file:`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 :file:`sql/upgrade_0.2-0.3.pgsql` for
PostgreSQL or :file:`sql/upgrade_0.2-0.3.mysql` for MySQL. If you use MySQL,
execute also :file:`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*
:file:`upgrade_0.2-0.3.(pgsql|mysql)` has been applied and *before* any new
invoice is created. The script is named :file:`convert_invoices.php` and
located in the directory :file:`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 :file:`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
:ref:`requirements` section to find instructions on where to find and how to
install these packages.

Upgrading from earlier versions
===============================

.. _upgrpgsql:

PostgreSQL
----------

Execute the proper :file:`upgrade*.sql` script from :file:`sql/`.

.. _upgrmysql:

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 :file:`sql/upgrade_0.1.1-0.2.mysql` and
  :file:`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: 

  .. code-block:: php


    <?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
:file:`sql/upgrade_0.2_rc1-0.2.mysql`: ::

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

.. _migration:

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.

