feat: Add tooling to generate stubs for the Public PHP API

[PROFeNoM]

Description

AIDM-460 & AIDM-463

This PR adds simple tooling to add one stub file (src/ddtrace_php_api.stubs.php) for all the Public PHP API files (pulled from the files declared in the bridge).

This allows us to generate a stub file locally using make generate_stubs (PHP 8+).

Additionally, all stubs files (there are four) will be merged together and added to the final artifact as datadog-tracer.stubs.php.

The generated files up-to-date job will regenerate PHP stubs and compare them on each commit, failing if there is a difference.

Reviewer checklist

• Test coverage seems ok.
• Appropriate labels assigned.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 0% with 423 lines in your changes missing coverage. Please review.

Project coverage is 70.32%. Comparing base (0e77db0) to head (2a70431).
Report is 32 commits behind head on master.

Files with missing lines	Patch %	Lines
src/ddtrace_php_api.stubs.php	0.00%	423 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (0e77db0) and HEAD (2a70431). Click for more details.

HEAD has 1 upload less than BASE

Flag	BASE (0e77db0)	HEAD (2a70431)
tracer-php	12	11

Additional details and impacted files

@@              Coverage Diff              @@
##             master    #2933       +/-   ##
=============================================
- Coverage     82.10%   70.32%   -11.78%     
- Complexity     2527     2739      +212     
=============================================
  Files           108      136       +28     
  Lines         10359    14822     +4463     
  Branches          0      989      +989     
=============================================
+ Hits           8505    10424     +1919     
- Misses         1854     3855     +2001     
- Partials          0      543      +543     

Flag	Coverage Δ
appsec-extension	68.34% <ø> (?)
tracer-php	71.07% <0.00%> (-11.04%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/ddtrace_php_api.stubs.php	0.00% <0.00%> (ø)

... and 35 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0e77db0...2a70431. Read the comment docs.

[pr-commenter]

Benchmarks [ tracer ]

Benchmark execution time: 2024-11-14 09:05:46

Comparing candidate commit 2a70431 in PR branch alex/AIDM-460_public-php-api-stubs with baseline commit 0e77db0 in branch master.

Found 0 performance improvements and 0 performance regressions! Performance is the same for 178 metrics, 0 unstable metrics.

[bwoebi]

Could you please rename the cbindgen up-to-date step in circleci to generated files up-to-date and add make generate_stubs; git diff --exit-code src/ddtrace_php_api.stubs.php? (and switch the container to a buster container which also includes php)

[bwoebi]

Also, can you please put the generated merged stub file in the $packages_build_dir directly rather than inside the .tar.gz? That way it'll also appear in the artifacts directly, for easy download directly from the artifacts page.

[bwoebi]

php -l datadog-tracer.stubs.php 
Parse error: syntax error, unexpected character 0x1B, expecting "{" in datadog-tracer.stubs.php on line 1484

Somehow the string sequence \e got re-interpreted as a literal escape character in the output.

namespace DDTrace\exceptions;

becomes

6e 616d 6573 7061 6365 2044 4454 7261 6365 1b78 6365 7074 696f 6e73 3b

(note the 1b in the hex output)

[bwoebi]

Nice! Thanks Alexandre :-)