PHPC-2647, PHPC-2715: Fix all possible build configurations (standalone vs. in-tree, in-source vs. out-of-source)

[alcaeus]

PHPC-2647, PHPC-2715

This PR revives the original goal of PHPC-2647 — keeping generated config headers (common-config.h, bson/config.h, mongoc-config.h, etc.) out of the source tree during out-of-source builds — while correctly handling all four build layouts the extension supports. It supersedes the partial fixes in PHPC-2714 and PHPC-2715.

The four build layouts

1. phpize — in-source

phpize is run in the source directory, and ./configure is invoked from that same directory. This is the standard workflow for building the extension standalone.

cd /path/to/mongo-php-driver
phpize
./configure
make

PHP_EXT_BUILDDIR(mongodb) = . (resolves to /path/to/mongo-php-driver); PHP_EXT_SRCDIR(mongodb) = /path/to/mongo-php-driver

2. phpize — out-of-source

phpize is run in the source directory to generate configure, then configure is invoked from a separate build directory. This is the layout used by RHEL/RPM packaging and any packager that wants a clean source tree.

cd /path/to/mongo-php-driver
phpize
mkdir /tmp/build && cd /tmp/build
/path/to/mongo-php-driver/configure
make

PHP_EXT_BUILDDIR(mongodb) = . (resolves to /tmp/build); PHP_EXT_SRCDIR(mongodb) = /path/to/mongo-php-driver

3. PHP in-tree — source = build

The extension is compiled statically into PHP (used by projects like
StaticPHP). PHP's buildconf
discovers the extension's config.m4 via a glob over ext/*/config.m4, and
./configure is run from the PHP source directory, which doubles as the build
directory.

ln -s /path/to/mongo-php-driver /path/to/php-src/ext/mongodb
cd /path/to/php-src
./buildconf --force
./configure --enable-mongodb
make

PHP_EXT_BUILDDIR(mongodb) = ext/mongodb (resolves to /path/to/php-src/ext/mongodb); PHP_EXT_SRCDIR(mongodb) = /path/to/php-src/ext/mongodb

4. PHP in-tree — source ≠ build

Same as (3) but PHP itself is configured with a dedicated build directory.

ln -s /path/to/mongo-php-driver /path/to/php-src/ext/mongodb
cd /path/to/php-src && ./buildconf --force
mkdir /tmp/php-build && cd /tmp/php-build
/path/to/php-src/configure --enable-mongodb
make

PHP_EXT_BUILDDIR(mongodb) = ext/mongodb (resolves to /tmp/php-build/ext/mongodb); PHP_EXT_SRCDIR(mongodb) = /path/to/php-src/ext/mongodb

History of the problem

PHPC-2647 (a2bb085) changed AC_CONFIG_FILES from absolute source-tree
paths to bare relative paths (e.g. src/libmongoc/src/common/src/common-config.h).
Relative paths in AC_CONFIG_FILES are resolved relative to the directory
where ./configure was invoked:

Build layout	configure invocation dir	Headers written to
phpize in-source	/source	/source/src/... — in source tree
phpize out-of-source	/build	/build/src/... — in build tree ✓
PHP in-tree (src=build)	/php-src	/php-src/src/libmongoc/... — wrong location ✗
PHP in-tree (src≠build)	/php-build	/php-build/src/libmongoc/... — wrong location ✗

For in-tree PHP builds (layouts 3 and 4), the configure invocation directory is
the PHP root, so bare relative paths like src/libmongoc/... land at
/php-root/src/libmongoc/... instead of under ext/mongodb/.

PHPC-2714 (79b6416) fixed layouts 3 and 4 by using
${php_mongodb_ext_builddir}/src/... where
php_mongodb_ext_builddir = PHP_EXT_BUILDDIR(mongodb). That macro expands to
ext/mongodb for in-tree builds and . for phpize builds, so the headers land
in the right place relative to the build root in all cases. However, the fix
added build-tree include paths via $abs_builddir/$php_mongodb_ext_builddir/...,
which failed for phpize out-of-source builds (layout 2) due to how abs_builddir
interacts with relative PHP_EXT_BUILDDIR expansion. The failure was not caught
because no CI job tested layout 2 at the time.

PHPC-2715 (8f28ee4) added a CI job for out-of-source builds and fixed the
failure by reverting AC_CONFIG_FILES to use PHP_EXT_SRCDIR(mongodb) (the
absolute source-tree path). This restores the pre-PHPC-2647 behaviour: headers
are always written to the source tree. The include paths, however, continued
to point into the build tree:

Build layout	AC_CONFIG_FILES writes to	Include path reads from	Match?
phpize in-source	/source/src/... (srcdir)	/source/src/... (builddir = srcdir)	✓
phpize out-of-source	/source/src/... (srcdir)	/build/src/... (builddir ≠ srcdir)	✗
PHP in-tree (src=build)	/php-src/ext/mongodb/src/...	/php-src/ext/mongodb/src/...	✓
PHP in-tree (src≠build)	/php-src/ext/mongodb/src/...	/php-build/ext/mongodb/src/...	✗

PHPC-2715 works only when source dir = build dir (layouts 1 and 3), which
happened to cover all tested scenarios. Layouts 2 and 4 remained broken.
Additionally, using PHP_EXT_SRCDIR always writes generated files into the
source tree, abandoning the PHPC-2647 goal.

What this PR does

Three changes:

1. Add PHP_MONGODB_ADD_BUILD_INCLUDE to scripts/autotools/m4/php_mongodb.m4

A new macro, parallel to the existing PHP_MONGODB_ADD_INCLUDE (which uses
PHP_EXT_SRCDIR) and PHP_MONGODB_ADD_BUILD_DIR (which uses
PHP_EXT_BUILDDIR):

AC_DEFUN([PHP_MONGODB_ADD_BUILD_INCLUDE],[
  PHP_EXPAND_PATH(PHP_EXT_BUILDDIR(mongodb), php_mongodb_abs_builddir)
  PHP_ADD_INCLUDE([$php_mongodb_abs_builddir/$1])
])

PHP_ADD_INCLUDE calls PHP_EXPAND_PATH internally, which resolves a path to
absolute using cd $path && pwd. This probe requires the target directory to
exist, but the build subdirectories (e.g. src/libmongoc/src/libbson/src/) are
only created by PHP_ADD_BUILD_DIR later in AC_CONFIG_COMMANDS_PRE. Passing
the full relative path (e.g. ./src/libmongoc/src/libbson/src/) would cause
PHP_EXPAND_PATH to silently discard it when the cd fails.

To avoid this, we first expand only PHP_EXT_BUILDDIR(mongodb) — which is .
or ext/mongodb, both of which exist at configure time — to get the absolute
build root. We then append the subdirectory and pass the resulting absolute path
to PHP_ADD_INCLUDE. PHP_EXPAND_PATH short-circuits for paths starting with
/ and uses them as-is, so the subdirectory is not required to exist yet.

2. Use PHP_EXT_BUILDDIR for AC_CONFIG_FILES and PHP_MONGODB_ADD_BUILD_INCLUDE for the compiler include paths in config.m4

AC_CONFIG_FILES paths now use ${mongodb_builddir} where
mongodb_builddir = PHP_EXT_BUILDDIR(mongodb). A PHP_MONGODB_ADD_BUILD_INCLUDE
call is added alongside each group of AC_CONFIG_FILES entries so the compiler
include paths mirror the write locations:

Build layout	AC_CONFIG_FILES writes to	ADD_BUILD_INCLUDE adds	Source tree written?
phpize in-source	./src/... → /source/src/...	-I/source/src/...	Yes (unavoidable: src=build)
phpize out-of-source	./src/... → /build/src/...	-I/build/src/...	No ✓
PHP in-tree (src=build)	ext/mongodb/src/... → /php-src/ext/mongodb/src/...	-I/php-src/ext/mongodb/src/...	Yes (unavoidable: src=build)
PHP in-tree (src≠build)	ext/mongodb/src/... → /php-build/ext/mongodb/src/...	-I/php-build/ext/mongodb/src/...	No ✓

Write location and include path always agree. The source tree is only written to
when the build directory is the same as the source directory, which is
unavoidable by definition.

3. Extend test-in-tree-build in .github/workflows/tests.yml with an out-of-source mode

The existing job (formerly test-static-php-build, added in PHPC-2714) only
ran PHP's configure from the PHP source directory (layout 3). A mode matrix
(from-source, out-of-source) is added. The out-of-source mode creates a
separate /tmp/php-build directory and runs configure and make from there,
exercising layout 4.

CI coverage

The test-in-tree-build job (renamed from test-static-php-build, added in PHPC-2714) covers layouts 3 and 4 via a mode matrix (from-source and out-of-source).
The test-out-of-source-build job (added in PHPC-2715) covers layout 2.
Layout 1 is covered by the standard linux-test jobs.

[GromNaN]

Should you target the branch 2.3?

[alcaeus]

Should you target the branch 2.3?

Correct, fixed.

[Copilot]

Pull request overview

This PR updates the extension’s Autotools configuration to correctly place and include generated config headers across all four supported build layouts (standalone vs. in-tree, in-source vs. out-of-source), and expands CI coverage to exercise the missing in-tree out-of-source layout.

Changes:

• Added a new Autotools helper macro to add include paths rooted at the extension build directory (for generated headers).
• Switched AC_CONFIG_FILES outputs in config.m4 to target the extension build directory and mirrored that with build-directory include paths.
• Extended the GitHub Actions in-tree build job to run both in-source and out-of-source PHP builds.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
scripts/autotools/m4/php_mongodb.m4	Adds PHP_MONGODB_ADD_BUILD_INCLUDE to register include paths for generated headers in the build tree.
config.m4	Writes generated config headers into the extension build directory and adds corresponding build include paths.
.github/workflows/tests.yml	Renames/extends the in-tree static PHP build job with a matrix to cover out-of-source builds.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot review

[remicollet]

LGTM (tested with 2.3.1 + #2007 + #2014)

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.