feat: Add tooling to generate stubs for the Public PHP API (#2933)

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

* chore: Merge all stubs into one single file during artifact generation

* fix: typo

* fix: language

* Rename `/home/circleci/app` to `/home/circleci/datadog`

* feat: Use PROJECT_ROOT as third argument

* ci: Rename `cbindgen up-to-date` to `generated files up-to-date`

* feat: Regenerate PHP stubs and compare them

* style: Put generated artifact directly in the artifacts

* fix: generated files up-to-date

* fix: buster image name

* fix: src dir

* fix: src dir

* style: Rename merged stubs file

* fix: offset

* fix: Sort by name

* chore: Update ddtrace_php_api.stubs.php

* style: naming consistency

* fix: string interpretation

Co-authored-by: Bob Weinand <[email protected]>

* fix: Don't use semicolon namespaces

* fix: Type mixed cannot be marked as nullable

* fix: Type mixed cannot be marked as nullable

* fix: Bracket mix issues

---------

Co-authored-by: Bob Weinand <[email protected]>

.circleci/continue_config.yml

@@ -3891,10 +3891,10 @@ jobs:
               phpize
               php run-tests.php -p $(which php) -d datadog.remote_config_enabled=false --show-diff -g "FAIL,XFAIL,BORK,WARN,LEAK,XLEAK,SKIP" tests/ext/profiling
 
-  "cbindgen up-to-date":
+  "generated files up-to-date":
     working_directory: ~/datadog
     docker:
-      - image: datadog/dd-trace-ci:buster
+      - image: datadog/dd-trace-ci:php-8.3_buster
     steps:
       - restore_cache:
           keys:
@@ -3909,6 +3909,12 @@ jobs:
             set -eu
             make cbindgen
             git diff --exit-code components-rs
+      - run:
+          name: Regenerate PHP stubs and compare them
+          command: |
+            set -eu
+            make generate_stubs
+            git diff --exit-code src/ddtrace_php_api.stubs.php
       - run:
           name: Ensure no non-bundled rust git dependencies are used
           command: |
@@ -5747,7 +5753,7 @@ workflows:
           name: "Static Analysis 80"
           docker_image: datadog/dd-trace-ci:php-8.0_buster
           scenario: opentracing10
-      - "cbindgen up-to-date"
+      - "generated files up-to-date"
       - "Post-Install Hook":
           requires: [ 'Prepare Code' ]
 

Makefile

@@ -478,7 +478,8 @@ $(PACKAGES_BUILD_DIR):
 bundle.tar.gz: $(PACKAGES_BUILD_DIR)
 	bash ./tooling/bin/generate-final-artifact.sh \
 		$(VERSION) \
-		$(PACKAGES_BUILD_DIR)
+		$(PACKAGES_BUILD_DIR) \
+		$(PROJECT_ROOT)
 
 $(PACKAGES_BUILD_DIR)/datadog-setup.php: $(PACKAGES_BUILD_DIR)
 	bash ./tooling/bin/generate-installers.sh \
@@ -512,6 +513,11 @@ generate:
 	@composer -dtooling/generation generate
 	@composer -dtooling/generation verify
 
+# Generates the stubs file for the public API
+generate_stubs:
+	@composer -dtooling/stubs update
+	@composer -dtooling/stubs generate
+
 # Find all generated core dumps, sorted by date descending
 cores:
 	find . -path "./*/vendor" -prune -false -o \( -type f -regex ".*\/core\.?[0-9]*" \) -printf "%T@ %Tc %p\n" | sort -n -r

ext/ddtrace.stub.php

@@ -62,7 +62,7 @@ class ExceptionSpanEvent extends SpanEvent {
          * @param array $attributes Optional attributes for the event.
          */
         public function __construct(\Throwable $exception, array $attributes = []) {}
-        
+
         /**
          * @var \Throwable
          */
@@ -798,7 +798,7 @@ function has_listeners(): bool {}
      * @param string|resource|null $body the body of the request (a string or a seekable resource)
      * @return array|null an array with the keys 'status', 'headers' and 'body', or null
      */
-    function notify_start(\DDTrace\RootSpanData $span, array $data, ?mixed $body = null): ?array {}
+    function notify_start(\DDTrace\RootSpanData $span, array $data, mixed $body = null): ?array {}
 
     /**
      * Notifies the user request listeners of the imminence of a commit, and allows for the replacement of the response.
@@ -808,7 +808,7 @@ function notify_start(\DDTrace\RootSpanData $span, array $data, ?mixed $body = n
      * @param string|resource|null $body the body of the response (a string or a seekable resource)
      * @return array|null an array with the keys 'status', 'headers' and 'body', or null
      */
-    function notify_commit(\DDTrace\RootSpanData $span, int $status, array $headers, ?mixed $body = null): ?array {}
+    function notify_commit(\DDTrace\RootSpanData $span, int $status, array $headers, mixed $body = null): ?array {}
 
     /**
      * Sets a function to be called when blocking a request midway.

ext/ddtrace_arginfo.h

@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: fa4bda312fa3b405b09e09c6bc81a05d2a8e3372 */
+ * Stub hash: 5eb7dd922aab52cab793bd947871d8ee8ee0c284 */
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_DDTrace_trace_method, 0, 3, _IS_BOOL, 0)
 	ZEND_ARG_TYPE_INFO(0, className, IS_STRING, 0)
@@ -163,14 +163,14 @@ ZEND_END_ARG_INFO()
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_DDTrace_UserRequest_notify_start, 0, 2, IS_ARRAY, 1)
 	ZEND_ARG_OBJ_INFO(0, span, DDTrace\\RootSpanData, 0)
 	ZEND_ARG_TYPE_INFO(0, data, IS_ARRAY, 0)
-	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, body, IS_MIXED, 1, "null")
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, body, IS_MIXED, 0, "null")
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_DDTrace_UserRequest_notify_commit, 0, 3, IS_ARRAY, 1)
 	ZEND_ARG_OBJ_INFO(0, span, DDTrace\\RootSpanData, 0)
 	ZEND_ARG_TYPE_INFO(0, status, IS_LONG, 0)
 	ZEND_ARG_TYPE_INFO(0, headers, IS_ARRAY, 0)
-	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, body, IS_MIXED, 1, "null")
+	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, body, IS_MIXED, 0, "null")
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_DDTrace_UserRequest_set_blocking_function, 0, 2, IS_VOID, 0)