Installing ChartDirector for PHP

ChartDirector for PHP is released on Windows, Linux, FreeBSD, Mac OS X and Solaris. Before we start installation, you may want to verify the ChartDirector distribution you have downloaded is for your operating system by using the table below. If you do not know what is your operating system (eg. you are using a remote host), you may use phpinfo to find out.

Operating System	File Name
Windows	chartdir_php_win32.zip
Linux (i386)	chartdir_php_linux.tar.gz
Linux (x86_64 - 64bit OS)	chartdir_php_linux_64.tar.gz
FreeBSD (i386)	chartdir_php_freebsd.tar.gz
FreeBSD (amd64)	chartdir_php_freebsd_64.tar.gz
Mac OS X (Power PC/Intel)	chartdir_php_mac.tar.gz
Solaris (Sparc)	chartdir_php_sunos.tar.gz
Solaris (x86)	chartdir_php_sunos_86.tar.gz

To install ChartDirector for PHP, extract the files from the ChartDirector distribution to your web server HTML directory (or any directory that allow PHP scripts to execute):

If you are using Windows, you may use Winzip or similar tools to unzip the ChartDirector distribution.
If you are using Linux, FreeBSD, Mac OS X or Solaris, first copy the ChartDirector distribution to your web server HTML directory, then change to your web server HTML directory, and issue the following commands:
```
gunzip [chartdir_file_name].tar.gz
tar xvf [chartdir_file_name].tar
```

If you cannot access the command prompt (eg. you are using a remote host with no telnet access), you may extract ChartDirector on a local machine first (eg. using Winzip), then upload the files to your host using FTP.

If the connection to your remote host is not fast, you may consider to upload only the "ChartDirector/phpdemo" and "ChartDirector/lib" subdirectories, while keeping the documentation "ChartDirector/doc" in your local machine.

ChartDirector for PHP is implemented as a PHP extension, which consists of everything in "ChartDirector/lib". The method used by a PHP system to load an extension differs depending on the PHP system is configured.

Some PHP systems can dynamically load extensions from the web document directory. If you are using this type of PHP system, no further installation step is necessary. You may proceed to Running ChartDirector Sample Scripts.
Some PHP systems can only dynamically load extensions from the PHP extension directory. If you are using this type of PHP system, you would need to copy ChartDirector to the PHP extension directory.
Some PHP systems cannot dynamically load any extension at all. If you are using this type of PHP system, you would need to copy ChartDirector to the PHP extension directory, and use extension statement to load ChartDirector.

You may use phpinfo to examine your PHP configuration, so as to determine the type of PHP you using. For your convenience, the ChartDirector distribution includes a phpinfo page at (note: the exact URL depends on where you have extracted ChartDirector to):

http://aaa.bbb.ccc.ddd/ChartDirector/phpdemo/phpinfo.php

If your PHP system has any of the following characteristics, it is of type (3) mentioned above, that is, it cannot dynamically load any extension.

PHP 5.3.0 or above.
The PHP is intentionally configured to disable dynamic loading of extensions, such as by setting "enable_dl = No", or "safe_mode = Yes", or by including "dl" in the disable function list.
The PHP is configured with "Thread Safety = enabled", and the "Server API" is not "CGI" or "FastCGI". (This type of configuration is common on Windows, but uncommon in other operating systems).

If your PHP system has any of the following characteristics, it is of type (2) mentioned above. It can only dynamically load extensions from the PHP extension directory.

The PHP version 5.2.5 or above, but below 5.3.0. Since PHP 5.2.5, PHP is restricted to only load extensions in the PHP extension directory.
The PHP is running on Windows, and the web server HTML directory is not on the same hard disk volume as the PHP extension directory (eg. PHP is installed in "C:", but the web document directory is at "D:").

If your PHP system does not have any of the above characteristics, it is likely to be of type (1) mentioned above. It can load extensions from the web document directory.

Note: This step is only necessary if your PHP cannot dynamically load extensions from the web document directory. Otherwise this step is optional. See Verifying Your PHP Configuration for details.

To copy ChartDirector to the PHP extension directory, please copy everything in "ChartDirector/lib" (including the fonts subdirectory in Linux, FreeBSD and Solaris versions of ChartDirector) to the PHP extension directory.

Note: This step is only necessary if your PHP cannot dynamically load any extension. Otherwise this step is optional. See Verifying Your PHP Configuration for details.

Using extension statements may improve performance for PHP that uses SAPI. It is because instead of dynamically loading an extension on demand, PHP will pre-load it once during initialization. So it is not uncommon for installations to use extension statements, even if it is not mandatory.

To use extension statement to load ChartDirector, please ensure you have already copied ChartDirector to the PHP extension directory. Then add the following line to your php.ini.

 extension=phpchartdir###.dll 

In the above, the "phpchartdir###.dll" depends on your PHP version, operating system, and PHP thread safety settings. Please use the following table to determine the "phpchartdir###.dll" to use:

PHP Version	Windows		Linux, FreeBSD, Mac OS X, Solaris
PHP Version	Non-Thread-Safe	Thread-Safe	Non-Thread-Safe	Thread-Safe
4.0.4pl1	N/A	phpchartdir404.dll	phpchartdir404.dll	phpchartdir404mt.dll
4.0.5 - 4.0.6	N/A	phpchartdir405.dll	phpchartdir405.dll	phpchartdir405mt.dll
4.1.0 - 4.2.0	N/A	phpchartdir410.dll	phpchartdir410.dll	phpchartdir410mt.dll
4.2.1 - 4.x.x	N/A	phpchartdir421.dll	phpchartdir421.dll	phpchartdir421mt.dll
5.0.0 - 5.0.2	N/A	phpchartdir500.dll	phpchartdir500.dll	phpchartdir500mt.dll
5.0.3 - 5.0.5	N/A	phpchartdir503.dll	phpchartdir503.dll	phpchartdir503mt.dll
5.1.x	N/A	phpchartdir510.dll	phpchartdir510.dll	phpchartdir510mt.dll
5.2.x	phpchartdir520nts.dll	phpchartdir520.dll	phpchartdir520.dll	phpchartdir520mt.dll
5.3.0 or above	phpchartdir530nts.dll	phpchartdir530.dll	phpchartdir530.dll	phpchartdir530mt.dll

If your PHP "Server API" is not "CGI", you would need to restart you web server for any modification to "php.ini" to take effect.

ChartDirector for PHP comes with a number of sample PHP scripts under the "ChartDirector/phpdemo" directory. They are good examples and tutorials on how to use ChartDirector.

To try the sample scripts, use the following URL to view the sample scripts index page (note: the exact URL depends on where you have extracted ChartDirector to).

http://aaa.bbb.ccc.ddd/ChartDirector/phpdemo/index.php

In the sample scripts index page, there is a "check installation" link in the right window. Please click on that link. If it displays the ChartDirector version with some other information, it can be confirmed that ChartDirector is installed successfully.

If the "check installation" link returns an error message, please refer to Trouble-Shooting ChartDirector for PHP Installation for instructions on how to resolve the problem. Note that messages in the "Boot Log" or the "Font Loading Test" are informational only and are not error messages.

After confirming that ChartDirector is installed successfully, you may click the links in the left window to see the sample charts.

To use ChartDirector, please include the ChartDirector script "phpchartdir.php" in your own script using the PHP "require_once" statement. For example, all ChartDirector sample scripts use the following line to include "phpchartdir.php":

require_once("../lib/phpchartdir.php");

For your own scripts, you may copy everything in "ChartDirector/lib" (including the fonts subdirectory in Linux, FreeBSD, and Solaris versions) to your script directory. You may then use the following line to include "phpchartdir.php":

require_once("phpchartdir.php");

If the ChartDirector PHP extension has been copied to the PHP extension directory, you just need to copy one file "phpchartdir.php" to your script directory (instead of everything in "ChartDirector/lib").

Note that require_once assume the path is a file system path. If you use an absolute path name (eg. a path name starting with a slash "/"), the root is the file system root directory, not the web server root directory.

If you have purchased a license to use ChartDirector, you should have a license code delivered to your via email and postal mail.

If your license key is for upgrading from a previous version of ChartDirector, you need to append the upgrade license key to the previous version license key, and use the combined license key.

There are two alternative methods to install the license key.

Create a one-line ASCII file using Notepad or other text editor, and put the license code in that line. The whole file should contain only the license code. Name that file "chartdir.lic" and put the file in the same directory as the active "libchartdir.so" (for Linux, FreeBSD, Mac OS X and Solaris) or "chartdir.dll" (for Windows), which should be in the "ChartDirector/lib" directory or your PHP extension directory.

If the license file appears to have no effect (does not disable the yellow banner line), and you are running on a web server environment, please make sure the web server "anonymous user" has read access to the "chartdir.lic" file. You may copy the file "ChartDirector/phpdemo/cdinfo.php" to your web server and access it using a browser. It will display a diagnostic page explaining why the license cannot be loaded.

Make sure your license file is called "chartdir.lic". In particular, Notepad may automatically append ".txt" to the file name when creating a new file. So even if the file is saved as "chartdir.lic", it may end up as "chartdir.lic.txt". If this is the case, please rename the file back to "chartdir.lic".
An alternative method is to hard code the license key into the source code by using the setLicenseCode API. This method is recommended if your are redistributing ChartDirector, because your customer will then be unable to see the license key (unless your software is open source).

setLicenseCode(".....your-license-key.....");