How to use /etc/php5/conf.d ?

[Olly Betts <olly@survex.com>]

I maintain the php5-xapian package.  Currently it modifies php.ini upon
installation to append "extension=xapian.so" (after checking with the
user using debconf), but I notice that /etc/php5/conf.d now exists which
offers a much cleaner solution.

Looking at the PHP policy draft it appears that this hasn't yet been
updated for that change, as it says:

http://webapps-common.alioth.debian.org/draft-php/html/ch-php-int.html

    2.2.3 Configuration files

    Each PHP engine has a seperate configuration file located at
    /etc/phpPHPVERSION/PHPSAPI/php.ini

    Additionally, each engine provides a directory at
    /etc/phpPHPVERSION/PHPSAPI/conf.d where 3rd party PHP libraries and
    modules can provide additional configuration information.

    XXX this second part is not yet true. 

It looks like the second part is now mostly true.  README.Debian in the
PHP packages gives some information - it says:

    Additionally, each SAPI is configured with the compile-time option

    --with-config-file-scan-dir=/etc/php5/$SAPI/conf.d

    which for all SAPI's is actually a symlink pointing to a central
    directory /etc/php5/conf.d.  Any file found in this directory ending
    in .ini will be treated as a configuration file by the php SAPI.

Which seems to describe the situation correctly, so I can just package
"/etc/php5/conf.d/xapian.ini" containing "extension=xapian.so", and
I think I don't need to mark it as a conffile.

README.Debian continues:

    The rationale with this method is that each SAPI can thus be
    identically configured with a minimal amount of conffile handling,
    but at the same time if you want to have SAPI-specific configuration,
    you can just remove the symlink.

Should a package attempt to do anything special in the situation?
Should I be trying to copy xapian.ini into the conf.d for every SAPI
or is it assumed that this is up to the sysadmin if he or she removes
the symlinks?

And is there a recommended way to handle edits made to php.ini by the
currently install version of a package when moving to using conf.d?
I can easily check for the appropriate line and remove it if present,
though I can't tell if it was added by my postinst or the sysadmin.

Cheers,
    Olly