php-8.6.0rc3

This README contains unresolved ports variables; replace them before using its commands.

+-----------------------------------------------------------------------
| Running php-8.6 on OpenBSD
+-----------------------------------------------------------------------

Connecting your web server software to php
==========================================
Web server programs such as httpd(8), nginx and Apache listen for
network requests and decide whether to respond themselves (as is the
case with simple "static" files) or pass the request on to other
software for handling. The web server must be configured to handle
this - different methods are used depending on the server software.

FastCGI: httpd(8), NGINX, lighttpd, etc
---------------------------------------
Most modern web servers support FastCGI which is a simple method of
interfacing to many kinds of application server. This is usually the
preferred method of passing requests to php, and is the only method
possible for many servers such as httpd(8), nginx and lighttpd.

The main OpenBSD php packages include php-fpm, FastCGI Process Manager.
This manages pools of FastCGI processes: starts/restarts them and
maintains a minimum and maximum number of spare processes as
configured. You can use rcctl(8) to enable php-fpm at boot,
and start it at runtime:

    rcctl enable php${SV}_fpm
    rcctl start php${SV}_fpm

php-fpm has its own configuration file, by default ${SYSCONFDIR}/php-fpm.conf.
This controls how the php processes are started. The default settings
are suitable for many standard cases, but can be changed to provide
greater control for sites handling high loads or to provide
separation between different php applications by running them
under different uids or in individual chroot(2) jails.

Your HTTP server needs to be configured to pass requests for PHP
resources to php-fpm, usually done by unix socket. See the documentation
and sample configuration. For nginx, see the "FastCGI server listening
on unix socket" example provided in ${LOCALBASE}/share/nginx/nginx.conf.
For OpenBSD base's httpd(8) you can use a configuration fragment like:

	location "*.php" {
		fastcgi socket "/run/php-fpm.sock"
	}

If you need to run multiple versions of PHP on one machine, create
another configuration file (e.g. php-fpm-X.Y.conf) and set it to use a
different socket path. Configure rc.d(8) to pass the parameter when
starting php-fpm, for example

    rcctl set phpXY_fpm flags -y /etc/php-fpm-X.Y.conf

Apache httpd
------------
For Apache, the most common option is with the mod_php Apache module
provided in the php-apache package. This is loaded directly as part of
the web server process. Configuration is fairly simple, but in this
case the operating system can't provide memory protection between
the two; therefore bugs in php can potentially do more damage.

Another option is to use FastCGI via php-fpm as in the above section;
you can use mod_proxy_fcgi to interface it with Apache.

If you wish to use the Apache module, make sure the php-apache-${PV}
package is installed, then enable it by creating a symbolic link:

    # ln -sf ${MODPHP_CONFIG_PATH}/modules.sample/php-${PV}.conf \
	${MODPHP_CONFIG_PATH}/modules/php.conf

To disable:

    # rm -f ${MODPHP_CONFIG_PATH}/modules/php.conf

After making either of these changes, restart Apache.

php configuration
=================
The recommended php configuration has been installed to:
    ${SYSCONFDIR}/php-${PV}.ini.

Modify this as required for your use.

Server APIs (SAPI)
==================
The main php package includes the cli and php_fpm (FastCGI process
manager) SAPIs. These cover many common use-cases. Others are packaged
separately: php-apache, php-cgi, php-dbg.

Extension modules
=================
Many language features in php are provided by extensions, which come
in several classes.

- some extensions are included in the main PHP package and are always
enabled; they don't need to be installed or enabled separately.

- opcache is in the main package but must be configured.
See https://www.php.net/manual/en/opcache.configuration.php

If using opcache with multiple php-fpm pools, you might want to use
"validate-root" and/or "validate-permission".

Note that a large opcache may result in slow daemon shutdown.
If this exceeds the default 30 second timeout, you may override it:

    rcctl set php${SV}_fpm timeout 90

- some 'core' extensions with extra dependencies are packaged separately
and can be installed with pkg_add(1). The list may vary between versions
of PHP, but these are usually available:

	php-bz2		php-mysqli	php-shmop
	php-curl	php-odbc	php-soap
	php-dba		php-pcntl	php-snmp
	php-enchant	php-pdo_mysql	php-sqlite3
	php-gd		php-pdo_odbc	php-pdo_dblib
	php-gmp		php-pdo_pgsql	php-tidy
	php-intl	php-pdo_sqlite	php-xsl
	php-ldap	php-pgsql	php-zip

- various useful third-party extensions from the PECL repository have
also been packaged. Examples include pecl${SV}-memcached (for use with
sysutils/memcached), pecl${SV}-imagick (image manipulation using ImageMagick),
pecl${SV}-redis (for use with databases/redis), etc.

For all extensions packaged separately (and for opcache), you will find a
file named ${SYSCONFDIR}/php-${PV}.sample/(MODULE_NAME).ini. To enable it,
add a symlink into ${SYSCONFDIR}/php-${PV} and restart:

    ln -sf ../php-${PV}.sample/MODULE_NAME.ini ${SYSCONFDIR}/php-${PV}/

To disable, remove the symlink from ${SYSCONFDIR}/php-${PV} and restart:

    rm ${SYSCONFDIR}/php-${PV}/MODULE_NAME.ini

If you have installed a number of extensions and wish to enable them all,
you can use these shell commands:

    # cd ${SYSCONFDIR}/php-${PV}.sample
    # for i in *; do ln -sf ../php-${PV}.sample/$i ../php-${PV}/; done

After enabling or disabling extensions (or otherwise modifying php's
configuration), use rcctl(8) to restart php${SV}_fpm or Apache.

Moving between PHP release branches
===================================
If moving between PHP versions (for example, if an old release branch
is no longer supported and has been removed from ports, or you have
software that requires a new version), you will need to:

1. update the configuration files as needed

It may be useful to use diff(1) to compare the default configuration in
${TRUEPREFIX}/share/examples/php-X.Y/php.ini-production for the old version
with ${SYSCONFDIR}/php-X.Y.ini and apply them to the new version's ini
file.

2. make sure that rc.d(8) starts the new version (either via rcctl
disable/stop/enable/start, or editing /etc/rc.conf.local directly).

3. add symlinks to ${SYSCONFDIR}/php-${PV} as shown in the above section
of this pkg-readme.

Living with chroot
==================
The chroot jail commonly used with PHP on OpenBSD means that only files
inside /var/www can be accessed, and path references should omit /var/www
prefixes.

File paths
----------
Sometimes it is hard to work with file paths in this case (for example
applications with some parts run from the web and some from the command
line); in those cases it can help to create a symlink so that /var/www
from _inside_ the chroot points to the expected locations. This can be
done with "mkdir -p /var/www/var; ln -s .. /var/www/var/www".

Socket paths for MariaDB
------------------------
See mariadb's pkg-readme file for information.

Making network connections
--------------------------
To resolve DNS host names, you will need to copy /etc/resolv.conf
into the ${CHROOT_DIR} chroot jail. To make TLS connections, you'll also
need /etc/ssl/cert.pem for CA certificates.

Additionally, if your scripts use PHP's key generation functions they
may need access to /etc/ssl/openssl.cnf.

To use these, copy the relevant files into the /var/www jail:

    # mkdir -p ${CHROOT_DIR}/etc/ssl
    # install -m 444 -o root -g bin /etc/resolv.conf ${CHROOT_DIR}/etc/
    # install -m 444 -o root -g bin /etc/ssl/cert.pem /etc/ssl/openssl.cnf \
          ${CHROOT_DIR}/etc/ssl/

As these files are updated from time to time, you might like to add
the above "install" lines to /etc/rc.local.

Executing other commands
------------------------
To run commands from inside the chroot using PHP's file execution functions
(exec, passthru, popen, etc) or the old mail() function which executes
/usr/sbin/sendmail, you must either create a statically-linked binary,
or install the relevant libraries and support files inside the chroot. 
Additionally you will need to provide /bin/sh inside the chroot, for
example: "cp /bin/sh /var/www/bin". Again you will want to make sure
that this is kept up to date. (In the specific case of mail, it is
normally preferred to use PHPMailer or similar, and submit the mail by
SMTP instead).