DH_PHP(1)

📦
version 5.22 · 7 versions
, in ubuntu stonking

💖 DH_PHP — ok bestie, let's talk PHP packaging 💖

dh_php — registering configuration snippets to the PHP ✨ (yes, that's literally the NAME line, no I will not be boring about it)

🌸 SYNOPSIS 🌸

dh_php [debhelper options] [--conditional=expression]
[--error-handler=function] [-n|--noscripts] [--php-version=php_version]

🦋 DESCRIPTION 🦋

So. dh_php is a debhelper program, and its whole job — its moment, its main character purpose — is correctly installing PHP configuration snippets, plus setting up postinst, prerm and dependencies in PHP web server modules and web applications. Slay.

It supports the following configuration types:

  • PHP modules

And that's the list. One icon. 👑

Now, the tea: dh_php supports only a configuration file driven approach. Like, there is no other way in. If a file named debian/package.php exists, then the actual actions are determined by that file. That's it, that's the whole vibe check. 💅

🎀 OPERATION MODES 🎀

dh_php can only be used in a configuration file driven approach. Periodt. The configuration driven mode is fully documented down in the FILES section, and you activate it by supplying a debhelper(7) configuration file (e.g. debian/package.php).

Lowkey important: config-file-driven is not a preference, it's the only mode. Don't come looking for a flag to turn it off, bestie. 🙈

✨ INVOCATION ✨

dh_php is not part of debhelper itself, and it might require information available in the php-all-dev package. So packages that make use of dh_php should declare a build-dependency against the virtual dh-php package. Ngl, do not skip that step. 🫶

dh_php supports both: you can call it directly from a debian/rules file, or use it as a dh(1) addon.

  • In the former case (called directly), the helper should run after dh_install(1) or their respective counter parts in local implementations, at earliest. Like, earliest. Not sooner. 😤

Alternatively, you can use it as a dh addon by invoking it with:

%:
   dh $@ --with php

💜 FILES 💜

  • debian/package.php
  • debian/php

These list files to be registered with the PHP. The file is interpreted as a line separated list of installation stanzas, where each entry consists of whitespace separated values conforming to the file semantics below. 📝

🍓 FILE SEMANTICS 🍓

Every single line is a triple:

type file [arguments]

where the values are interpreted as follows:

  • type — Denotes the type of file to be installed. Recognized values are mod for PHP modules.
  • file — Is interpreted as an existing file name within the source package. No path expansion is effectuated. And just like dh_install(1), dh_php can not rename files. No rebranding, no glow-up, the name is the name. 💀

🧚 MODULES 🧚

Modules get handled specially and are determined by the mod type. Modules can have a .ini suffix. In that case the file is interpreted as a module configuration file respectively, and it's installed to /etc/php/<VERSION(s)/mods-available>. If the file is ending with a .so suffix, it's interpreted as an actual module shared object and it gets installed to the PHP module directory. ✨

Moreover — and this is the good part — if a .ini file is installed, the configuration is activated in the maintainer script at installation time. Automatic. Iconic. 👑

A typical module configuration has two lines: one for the .ini file, and one for the .so file, albeit the latter could be installed by upstream's makefile, too. So don't stress if you don't see it. 🌈

dh_php will set dependencies in ${php:Depends} accordingly when this type of configuration is found. It's giving takes care of you. 🫶

💅 OPTIONS 💅

  • --php-version=php_version — Make all calls to PHP versioned with <php_version>, e.g. php-config becomes php-config<php_version>. Yes, it just glues it on there. ✨
  • --error-handler=function — Call the named shell function if running the maintainer script fails. The function should be provided in the prerm and postinst scripts, before the #DEBHELPER# token. 👀
  • -e, --noenable — Install maintainer scripts accordingly, but do not enable the scripts or configuration by default. Shy mode. 🙈
  • -n, --noscripts — Do not modify preinst/postinst/postrm/prerm maintainer scripts. Hands off, bestie. 🚫

⚠️ NOTES ⚠️

Warning bestie!! Note that this command is not idempotent. 😭 dh_prep(1) should be called between invocations of this command. Otherwise, it may cause multiple instances of the same text to be added to maintainer scripts.

Like, it will just keep stacking the same text over and over. Not cute. Call dh_prep(1). Fr fr. 💀

🌟 EXAMPLES 🌟

The examples below list valid entries for a debian/package.php file. For example, the two lines below install a fictional foo PHP module along a Debian specific .ini file:

mod src/foo/foo.so
mod debian/foo.ini

Two lines. That's it. Obsessed. 🎀

👀 SEE ALSO 👀

phpquery(8), debhelper(7), dh(1)

💌 AUTHOR 💌

This manual and dh_php was written by Arno Toell <debian@toell.net> for Apache 2 and modified for PHP by Ondrej Sury <ondrej@sury.org>. Thank you for your service, kings. 🫡👑

Ok that's the whole page bestie!! This was perl v5.42.3, dated 2026-09-03, from the User Contributed Perl Documentation crew — mwah, go register your config snippets, you got this 💖✨🎀🦋🌸

📦 where this page comes from