Skip to content

Install ddtrace via datadog-setup.php on PHP 7.0+#1290

Open
Teko012 wants to merge 1 commit into
mlocati:masterfrom
Teko012:feat/ddtrace-via-datadog-setup
Open

Install ddtrace via datadog-setup.php on PHP 7.0+#1290
Teko012 wants to merge 1 commit into
mlocati:masterfrom
Teko012:feat/ddtrace-via-datadog-setup

Conversation

@Teko012
Copy link
Copy Markdown
Contributor

@Teko012 Teko012 commented May 23, 2026

On PHP 7.0+ this PR switches the ddtrace installation path from the existing PECL + Cargo build to Datadog's official installer, datadog-setup.php. The PECL/Cargo path is preserved for PHP <7.0 and as a fallback when a user pins ddtrace to a version below 1.0.0.

Why

  • datadog-setup.php is Datadog's supported install path for the PHP tracer. Using it keeps the installation aligned with Datadog's release artifacts and version-pinning rules instead of relying on PECL's mirror of datadog/dd-trace.
  • It can co-install the companion modules (ddappsec, datadog-profiling) in lockstep with the matching tracer build, which is awkward to do via PECL.
  • It avoids building Rust from source via Cargo for the common case, which currently pulls curl-dev automake libtool (Alpine) or libssl libcurl4-openssl-dev automake libtool (Debian) and adds noticeable build time/image size.

What changes

installRemoteModule() — the ddtrace) branch (install-php-extensions)

The selection logic is reorganized around the PHP version:

  • PHP <7.0 — unchanged path: build from source via PECL + installCargo. If a user explicitly requests ddtrace-1.0.0 or newer on PHP <7.0, the script now errors out (ddtrace <version> requires PHP 7.0 or later) instead of silently failing later. With no version supplied, it still defaults to 0.75.0 (newer 0.x releases refuse PHP 5 in their configure script).
  • PHP 7.0+ with an explicit pre-1.0.0 version — keep using the legacy installCargo path so older 0.x releases stay reproducible.
  • PHP 7.0+, default or 1.0.0+ — call the new installDDTrace helper and set installRemoteModule_manuallyInstalled=2 so the surrounding code skips the standard PECL pipeline (this is the same convention used for other manually-installed modules like blackfire).

PECL stability flags (stable, beta, …) are still resolved via resolvePeclStabilityVersion before any of the branches above run.

New installDDTrace() helper (install-php-extensions)

installDDTrace [version]
  • Downloads datadog-setup.php from the corresponding GitHub release:
    • no version → https://github.com/DataDog/dd-trace-php/releases/latest/download/datadog-setup.php
    • version X.Y.Zhttps://github.com/DataDog/dd-trace-php/releases/download/X.Y.Z/datadog-setup.php
  • Runs it as php datadog-setup.php --php-bin=php [extra args].
  • Honors two new environment variables (see below) to optionally append --enable-appsec and/or --enable-profiling.
  • Uses curl $IPE_CURL_FLAGS -sSLf for the download so the existing IPE_INSECURE=1 toggle keeps working, and errors out cleanly with a ### ERROR ### Failed to download … message if the download fails.
  • Cleans up the temporary datadog-setup.php once the install completes.

New environment variables (README.md)

Variable Effect
IPE_DD_APPSEC=1 Pass --enable-appsec to datadog-setup.php, installing the ddappsec module alongside ddtrace. Requires PHP 7.0+ and the 1.x tracer line.
IPE_DD_PROFILING=1 Pass --enable-profiling to datadog-setup.php, installing the datadog-profiling module. Requires PHP 7.1+ on Alpine 3.13+ (any Debian works) and the 1.x tracer line.

Both follow the existing IPE_* env-var conventions (accept 1, y…, Y…).

buildRequiredPackageLists()ddtrace@alpine and ddtrace@debian (install-php-extensions)

The development packages that were unconditionally pulled in for ddtrace are now gated behind PHP_MAJMIN_VERSION -lt 700, because they're only needed by the Cargo build path:

  • Alpine: curl-dev automake libtool — installed only on PHP <7.0.
  • Debian: $buildRequiredPackageLists_libssl libcurl4-openssl-dev automake libtool — installed only on PHP <7.0.

For PHP 7.0+ the datadog-setup.php flow installs the prebuilt tracer binary, so none of these dev packages are needed.

Test script: scripts/tests/ddtrace

Adds an executable PHP test that:

  1. Verifies ddtrace_version() is defined and prints the resolved version.
  2. If IPE_DD_PROFILING was set during install, verifies the datadog-profiling extension is loaded.
  3. If IPE_DD_APPSEC was set during install, verifies the ddappsec extension is loaded.

The script exits non-zero on any failure so it can be wired into the existing extension test matrix.

Backwards compatibility

  • install-php-extensions ddtrace on PHP <7.0 behaves exactly as before (default 0.75.0, Cargo build, same build deps).
  • install-php-extensions ddtrace-<0.x.y> on PHP 7.0+ keeps the previous Cargo-based path.
  • The only behavioral change for existing users on PHP 7.0+ without a pinned version is the switch from the PECL/Cargo build to the official datadog-setup.php install — which yields the same ddtrace extension but no longer leaves curl-dev/libcurl4-openssl-dev/automake/libtool lingering as runtime-installed packages.

Closes #1163.

@Teko012
Copy link
Copy Markdown
Contributor Author

Teko012 commented May 25, 2026

@mlocati What do you think about this?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Datadog Profiler module

1 participant