Naviserver PHP module

1) To compile PHP as a module for Naviserver, you need:

- installed Naviserver 4.99 or later
- PHP 5.x or later (tested with 5.6.6)

It has been tested with Drupal, RoundCube webmail, MailBee webmail, 
Mambo, Horder/IMP, MediaWiki, PmWiki

2) Compiling PHP

  This modules requires a PHP with ZTS and pthreads support.
  If the version of PHP installed on your system does not have TZS enabled,
  you have to compile PHP locally. When one tries to compile the module
  with a PHP installation without ZTS support, the compilation
  will output the error message

     #error Naviserver module is only useable in thread-safe mode

  The Makefile of this module provides support for building
  PHP with ZTS support. Note, that PHP has a very long list of
  build-options and you might have to adjust this list by
  shortening or extending the configure options according
  to your application needs.

  PHP can be build from the nsphp directory via

      $ make php

  This command will download and build PHP as shared library and
  install it under /usr/local/ns/php and compile nsphp against it.
  Note that you might have to install some more packages on your
  system in case some of the configured libraries for PHP are
  missing. You can also fix such issues by shortening the configure

3) Building nsphp

  When building the nsphp module you must tell it where the naviserver
  and php you would like to use are installed:

  make NAVISERVER=/usr/local/ns PHP_CONFIG=/usr/local/ns/php/bin/php-config

4) Changing nsd.tcl

  a) Enabling PHP

    Then enable the PHP module:

    ns_section	"ns/server/${server}/modules"
    ns_param    nsphp		${home}/bin/

  b) New section

    Add a new section to pass options to PHP (required):
    The 'map' command will cause Naviserver to pass all requests to *.php to
    the PHP module (can be specified multiple times).  Example:

    ns_section	"ns/server/${server}/module/nsphp"
    ns_param 	map 		*.php
    ns_param 	map 		*.php4

5) Calling PHP scripts from Tcl

  ns_php version

     Return PHP version

  ns_php eval string

     Evaluate PHP expression and return result

  ns_php evalfile filename

     Evaluate spacified PHP file

  ns_php call function

     Call PHP function and return result

  ns_php var varname

     Returns value of the PHP variable

6) Native PHP functions


     Returns HTTP header


     Evaluate Tcl code from PHP script and return result as string

  ns_log(severity, string);

     Put string in the server log, severity is one of
     'Notice', 'Warning', 'Error', 'Debug', 'Fatal'


     Returns information, name can be one of:
        address, boottime, builddate, threads,
        config, home, hostname, locks, log,
        major, minor, name, nsd, pageroot, patchlevel,
        pid, platform, tag, uptime, version, winnt


    Returns info about current connection, name can be one of:
        authpassword, authuser, close, content, contentlength,
	copy, driver, encoding, flags,
	host, id, isconnected, location, method,
	peeraddr, peerport, port, protocol, query, request,
        server, sock, start, status, url, urlc, urlencoding,
        urlv, version,


    Returns input headers as an array


    Returns output headers as an array


    Performs HTTP redirection

  ns_returndata(status, type, data);
  ns_returnfile(status, type, file);

    Return data or file contents, status is HTTP status like 200, type
    is content type like text/html

  ns_queryexists name

    Returns 1 if query parameter exists in the request

  ns_queryget name

    Returns value of the query parameter


    Returns all query parameters as an array

  nsv_get(array, key);
  nsv_set(array, key, value);
  nsv_incr(array, key, count);
  nsv_append(array, key, value);
  nsv_exists(array, key)
  nsv_unset(array, key);

    Interface to NSV arrays of the Naviserver, array is name of the array, all
    functions except last 2 will create array if it does not exists. Values in NSV arrays
    can be shared with Tcl and other connections.

7) PDO driver for ns_db

  This module implements internal PDO driver which uses the same ns_db handles and pools as
  the rest of Naviserver. 

  To allocate DB handle use:

     $db = new PDO("naviserver:poolname");

  where naviserver is PDO driver name and poolname is any pool defined
  in nsd.tcl. After that is works the same way as other PHP PDO drivers.

  The limitations are:
     - all values are strings
     - no native bind parameters, it uses PHP/PDO bind emulation