ChartDirector for PHP on Windows requires at least PHP versions 4.0.4pl1, and has been tested up to PHP 5.0.0 (the latest PHP release as of the date of this document).

ChartDirector for PHP is releaed in Windows, Linux, FreeBSD and Solaris editions. 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	chartdir_php_linux.tar.gz
FreeBSD	chartdir_php_freebsd.tar.gz
Solaris	chartdir_php_sunos.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/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.

The core of ChartDirector is implemented as a PHP extension. If your PHP system supports dynamic loading of extensions, ChartDirector will automatically load the ChartDirector PHP extension when needed. Therefore, no PHP configuration is required to use ChartDirector.

However, the following types of PHP do not support dynamic loading of extensions or have restrictions. For these types of PHP, you may need to put an extension statement in php.ini to load ChartDirector.

• PHP working as a multi-threaded web server module does not support dynamic loading of extensions (eg. "Server API = Apache" and "Thread Safety = enabled"). From experience, PHP/Apache on Windows is likely to be multi-threaded and is affected. PHP on Linux/FreeBSD/Solaris is likely to be single-threaded and is not affected.
  
  
• System administrators may disable dynamic loading of extensions by setting "enable_dl = No" or "safe_mode = Yes" in php.ini.
  
  
• On Windows, PHP requires the extension files to be in the same logical drive as the PHP extension directory. If your web server HTML directory is in a different logical drive from your PHP extension directory, you would need to copy everything in "ChartDirector/lib" to the PHP extension directory.

You may use phpinfo to find out if the your PHP system belongs to one of the above types. Another method is to simply try the ChartDirector for PHP sample scripts to see if they work.

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


In the sample scripts index page, there is a "check installation" link on the right window. If it returns the ChartDirector version along with some other information, then dynamic loading of ChartDirector is successful.

On the other hand, if it returns an error message saying "use extension statement in php.ini to load ChartDirector", you would need to use extension statement to load ChartDirector.

If you are seeing other error message (eg. "Permission Denied"), please refer to Trouble-Shooting ChartDirector for PHP Installation for trouble-shooting instructions. Note that messages in the "Boot Log" or the "Font Loading Test" are informational only and are not error messages.

You need to use extension statement to load ChartDirector if your PHP does not support dynamic loading of extensions.

If your PHP supports dynamic loading of extensions, using extension statement is optional and may improve performance. It is because by using extension statement, instead of dynamically loading ChartDirector everytime when it is needed, PHP will just pre-load it once during initialization.

To use extension statement in php.ini to load ChartDirector:

• Copy everything in "ChartDirector/lib" (including the fonts subdirectory for Linux/FreeBSD/Solaris version) to the PHP extension directory.
  
  

  Please ensure you know where is the PHP extension directory. From experience, the vast majority of issues are due to confusion on where is the PHP extension directory.

  
  
• Enter the line "extension=phpchartdir###.dll" in php.ini, where "phpchartdir###.dll" is a file chosen using the table below. The file depends on your PHP version, operating system, and PHP thread-safety settings. You may use phpinfo to find out these settings. From experience, the majority of PHP on Linux/FreeBSD/Solaris is not thread-safe.
  
  

  PHP Version	Windows	Linux/FreeBSD/Solaris
  		Not Thread-Safe	Thread-Safe
  4.0.4pl1	phpchartdir404.dll	phpchartdir404.dll	phpchartdir404mt.dll
  4.0.5 - 4.0.6	phpchartdir405.dll	phpchartdir405.dll	phpchartdir405mt.dll
  4.1.0 - 4.2.0	phpchartdir410.dll	phpchartdir410.dll	phpchartdir410mt.dll
  4.2.1 - 4.x.x	phpchartdir421.dll	phpchartdir421.dll	phpchartdir421mt.dll
  5.0.0 and above	phpchartdir500.dll	phpchartdir500.dll	phpchartdir500mt.dll

  
  

  Please make sure you know where is your active php.ini. If in doubt, use phpinfo to find out.

  
  
• Restart your web server. PHP only reads php.ini during initialization, so you would need to restart your web server to have the changes take effect.

If you have purchased a license to use ChartDirector, you should receive a license key by email and/or by post.

Note that even without a license key, ChartDirector is fully functional and will not expire, but the charts generated will contain a small yellow banner at the bottom. The yellow banner will disappear once you install the license key.

To install the license key, follow the steps below:

• Save the license key in an ASCII text file, and name the file "chartdir.lic". The ASCII text file should contain just one line, which is the license key. A sample license file is available at http://www.advsofteng.com/chartdir.lic for your reference.
  
  
• Put the license file in the same directory as "libchartdir.so" (Linux/FreeBSD/Solaris) or "chartdir.dll" (Windows), which should be in the "ChartDirector/lib" directory or your PHP extension directory.
  
  
• Make sure the web server "anonymous user" has sufficient privileges to read the license file.

For license installation issues, please refer to http://www.advsofteng.com/license_diag.html for trouble-shooting instructions.

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


If ChartDirector is installed correctly, you should see sample charts being generated by the sample PHP programs as you click through the links in the "index.php" page.

If for some reason, you cannot see the charts, please refer to Trouble-Shooting ChartDirector for PHP Installation for trouble-shooting instructions.

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":


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


Another option is to copy everything in "ChartDirector/lib" to your PHP extension directory (you may have already done that if you are using extension statement to load ChartDirector). In this case, you just need to copy one file "phpchartdir.php" to your script directory. It will search for the other ChartDirector files in the PHP extension directory.

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.