# phpaga

Installation instructions
$Revision: 896 $
$Date: 2007-11-08 21:08:24 +0100 (Thu, 08 Nov 2007) $
Florian
Lanthaler

              florian at phpaga dot net

## Installation

Installing phpaga is not a fully automated process, there are a few simple steps that you must go through. If you are upgrading from a previous version you might be interested in the chapter .

For a fresh install you need to do the following steps:

- Copy phpaga files to the destination folder(s).

- Install the requirements.

- Create a database and grant the necessary rights to the phpaga user.

- Set some base configuration parameters.

- Point your browser to phpaga - an installer will create the necessary tables and populate them with the core data.

This document will guide you through the installation and give you some help. If you don't know how to install PHP or how to compile it with support for the packages listed under "requirements", then refer to the PHP website and the official PHP Documentation.

### Requirements

The following software packages have to be installed on your server in order to use phpaga. The version numbers mentioned below are known to work. Refer to each package's website for installation instructions.

#### RDBMS

Currently PostgreSQL and MySQL are supported. If you are unsure about which to pick go for PostgreSQL - phpaga is developed and tested under PostgreSQL, and database-related parts are better tested with that platform.

##### PostgreSQL

7.4 - 8.2.4

http://www.postgresql.org/

##### MySQL

4.1.16, 5.1.2

http://www.mysql.com/

#### Web server

phpaga should work with any PHP-enabled web server. It has been tested with Apache (both 1.3.x and 2.x).

http://httpd.apache.org/

#### PHP with PDO

>= 5.2.0

PHP with support for PDO and the PDO driver(s) for PostgreSQL (or MySQL), gettext and gd. Visit http://www.php.net/ for more information on how to compile and install PHP, and http://www.php.net/gettext for information about PHP's gettext support. For the various supported languages to actually work, make sure you have the corresponding locales installed. Keep in mind that after installing a new locale you will need to restart the web server.

The `php.ini` settings register_globals and magic_quotes_gpc can both be Off. In case magic_quotes_gpc is On all escaping slashes in $_REQUEST, $_GET and $_POST will automatically be removed by phpaga.

The amount of memory available to PHP is defined by the memory_limit setting in `php.ini`. This value defaults to 8M, but you might need to raise it 16M or 32M if you encounter error messages like "*Fatal error*: Allowed memory size of 8388608 bytes exhausted (tried to allocate 65211 bytes) in *<some filename>* on line *<some line number>*". `etc/config.local.php` also provides the possibility to change this setting.

http://www.php.net/

#### eZ Components

2007.1.1

phpaga's chart displaying routines are based on ez Components.

http://ezcomponents.org/

#### Graphviz

2.2.1

This package is optional. If you would like to see project relationship graphs you will need to install Graphviz and set the related option "Enable Graphviz" under the sitewide configuration to "Yes". Note that phpaga will work nicely without this package (provided you set the option "Enable Graphviz" to "No") - you will just be missing the relationship graphs.

http://www.graphviz.org/

#### ImageMagick

6.0.6, 6.2.4

ImageMagick's "convert" is used to create preview thumbnails for uploaded files.

http://www.imagemagick.org/

### Additional requirements for the development version

If you fetched the source directly from phpaga's subversion repository you will need to install the following libraries. (They come already bundled with the official phpaga packages.)

#### Smarty

2.6.16

http://smarty.php.net/

phpaga uses Smarty as its templating engine. Smarty is written by Monte Ohrt and Andrei Zmievski.

#### R&OS pdf class

009e

The R&OS pdf class is a PHP class that allows the easy creation of PDF files. Get the file named pdfClassesAndFonts_009e.zip which contains the class, sample, and the required font metric files.

http://www.ros.co.nz/pdf/

#### smarty-gettext

1.0b1

http://sourceforge.net/projects/smarty-gettext/

smarty-gettext is a Smarty plugin written by Sagi Bashari that allows to use gettext with Smarty templates.

### Installation

#### Installation layout

Only phpaga's `htdocs/` directory needs to be read by the web server. All other directories can and should be outside the web server's document root. This can be achieved either by creating a virtual host and have it's document root point to the full path to `htdocs/`, or by installing phpaga completely outside the document root of an existing website and then adding an alias to the web server's configuration. This can be achieved under Apache with the following example:

      Alias /phpaga /usr/local/phpaga/htdocs/

If you can't modify the web server's settings (for example because you are using the services of a webhosting company) you should use the following strategy: Say your home directory is `/home/exampleuser`, and all your website content is stored under `/home/exampleuser/www/`. You copy phpaga to `/home/exampleuser/phpaga/`, move `/home/exampleuser/phpaga/htdocs` to `/home/exampleuser/www/phpaga` and mofidy `/home/exampleuser/www/phpaga/config.php` to include `/home/exampleuser/phpaga/etc/config.php`.

#### eZ Components

Install eZ Components into `ext/` and rename the extracted directory to `ezcomponents`.

          % cd phpaga/ext
          % tar xjf ezcomponents-2007.1.1.tar.bz2
          % mv ezcomponents-2007.1.1 ezcomponents

#### Additional steps for the development version

If you fetched the source directly from phpaga's subversion repository you will need to perform the following steps. If you are installing an official package you can skip this section.

1. Use the sample file `etc/config.local.php_sample` to create `etc/config.local.php` and fill in the necessary parameters.

2. Give the web server full permissions to the `files/` directory. This directory will contain the files users can upload and associate to objects (project, person, company, ...).

                 % chown www-data files/
                 % chmod 0700 files/

   If you do not have administrative rights on the server and therefore cannot change the directory's ownership, simply chmod 0777 the directory.

                 % chmod 0777 files/

3. Create a directory called templates_c in your phpaga-root directory (ie, /data/webs/phpaga/) and change its owner to your webserver's user (as the webserver has to write into it). Chmod it to 700. This directory is needed by Smarty, the template engine.

                 % mkdir templates_c
                 % chown www-data.www-data templates_c/
                 % chmod 0700 templates_c/

   If you do not have root or sudo permissions on your server (as is the case in many shared hosting environments), then you must chmod the `templates_c` directory 0777, giving everyone permission to read, write and execute the compiled smarty templates:

                 % mkdir templates_c
                 % chmod 0777 templates_c/

Install required 3rd party packages

1. If you have Smarty already installed on your server you can use it by editing the definition of SMARTY_DIR in `etc/config.local.php` accordingly.

               define("SMARTY_DIR", "/some/other/path/to/smarty/libs/");

   Otherwise install Smarty into `ext/` (no need to change `etc/config.local.php`).

               [ % cd phpaga/ext ]
               % tar zxf Smarty-x.x.x.tar.gz
               % mv Smarty-x.x.x smarty

2. Install the R&OS pdf class

               [% cd ext/ ]
               % mkdir pdfclass
               % cd pdfclass
               % unzip pdfClassesAndFonts_009e.zip

3. Install smarty-gettext

               [% cd ext/ ]
               % tar xvzf smarty-gettext-1.0b1.tgz
               % mv smarty-gettext-1.0b1 smarty-gettext

#### The database

Create a database and a database user with the necessary permissions and set the appropriate configuration settings in the file `etc/config.local.php` accordingly. Make sure the database is able to hold unicode/utf-8. We will name both the database and the user "phpaga" in the examples provided below.

If you are using phpaga with a webhosting provider, chances are that the provider will create the database for you and give you the credentials.

If you are upgrading from a previous version of phpaga refer to the section . For information about converting from MySQL to PostgreSQL read the section .

##### For PostgreSQL

Note: If you are using PostgreSQL 8.x, use 'UTF8' as the encoding of the database. For PostgreSQL 7.x, use the encoding 'UNICODE'.

        % psql template1
        template1> create database phpaga with encoding 'UTF8';
        template1> create user phpaga password 'yourpasswd';
        template1> grant all on database phpaga to phpaga;

Depending on your setup, you may also need to modify `pg_hba.conf`. This file is part of PostgreSQL and controls which hosts are allowed to connect, how clients are authenticated, which PostgreSQL user names they can use, which databases they can access. Refer to the PostgreSQL documentation if you are unsure about the proper settings.

##### For MySQL

        % mysql -uroot -p mysql
        mysql> create database phpaga default character set utf8 collate utf8_general_ci;
        mysql> grant all on phpaga.* to phpaga@localhost identified by 'yourpasswd';
        mysql> flush privileges;

## Configuration

Fire up your browser of choice and point it to the right URL. A simple wizard will guide you and help you to create the database structure, populate it with core data, and create the first user.

Insert the data as required and submit the form. The user will be created with all available permissions, and you are invited to log in.

In case you have any problems accessing phpaga, try to open test.php in your browser and check its output for helpful information.

PLEASE NOTE: If you can log in and everything is running smoothly, remove htdocs/test.php (or chmod it so that the webserver does not have access to it) - it might expose critical information.

Once you are logged in you can configure the default settings by selecting "Sitewide settings" from the admin menu.

From there you have the option to manage your categorie sections (task/project/job and other categories) from the admin menu, before you (or your users) start to add tasks.

Only the JPG format will work for the graphic logo that can be included in the PDF output, anything else will cause the output to be invalid.

## Upgrading phpaga

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

Apply the changes to the database structure by following the instructions in the sections or . Execute the proper `upgrade*.sql` script from `sql/`. For releases after 0.3 this won't be necessary - phpaga does now feature a web interface for database upgrades which you can reach at "System / Database upgrades".

If you were using phpaga with MySQL and would like to switch to PostgreSQL then read the section .

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

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

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

1. Create a mysqldump of phpaga containing just the data:

                   % mysqldump -uphpaga -pyourdbpasswd -c -t phpaga > phpaga_data.sql

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

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

## Appendix

### Bugs

Use the tools on the project site or feel free to drop a message to the phpaga-users mailing list to report bugs.

### Contact

Comments, questions and praise are welcome on the mailing list.