Merge pull request #126 from scoutapp/research-for-compiling-with-curl

Documentation and info for libcurl requirements

.github/test-curl-compilation/Dockerfile

@@ -0,0 +1,29 @@
+FROM ubuntu:22.04
+RUN apt-get update && apt-get -y upgrade \
+  && apt-get -y install software-properties-common \
+  && add-apt-repository ppa:ondrej/php \
+  && apt-get update \
+  && DEBIAN_FRONTEND=noninteractive apt-get -y install php8.0 php8.0-xml php8.0-dev
+
+ARG WITH_CURL_EXT=no
+RUN if [ "$WITH_CURL_EXT" = "yes" ]; then apt-get -y install php8.0-curl; fi
+
+ARG WITH_LIBCURL=no
+RUN if [ "$WITH_LIBCURL" = "yes" ]; then apt-get -y install libcurl4-openssl-dev; fi
+
+ADD *.c *.h config.m4 /scoutapm/
+
+RUN cd /scoutapm/ \
+    && ls -l \
+    && phpize \
+    && ./configure --enable-scoutapm \
+    && cat config.h \
+    && make \
+    && make install \
+    && echo "zend_extension=scoutapm" > /etc/php/8.0/mods-available/scoutapm.ini \
+    && phpenmod scoutapm
+
+ADD .github/test-curl-compilation/analyse-curl.php /scoutapm/analyse-curl.php
+
+ENTRYPOINT ["/usr/bin/php"]
+CMD ["/scoutapm/analyse-curl.php"]

.github/test-curl-compilation/analyse-curl.php

@@ -0,0 +1,40 @@
+<?php
+
+ob_start();
+phpinfo(INFO_MODULES);
+$phpinfo = array_column(array_map(
+  static function ($s) {
+    return explode(' => ', str_replace('scoutapm curl ', '', $s));
+  },
+  array_values(array_filter(
+    explode("\n", ob_get_contents()),
+    static function ($s) {
+      return str_contains($s, 'scoutapm curl');
+    }
+  ))
+), 1, 0);
+ob_end_clean();
+
+echo sprintf("HAVE_CURL: %s\n", $phpinfo['HAVE_CURL']);
+echo sprintf("HAVE_SCOUT_CURL: %s\n", $phpinfo['HAVE_SCOUT_CURL']);
+echo sprintf("curl instrumented: %s\n", $phpinfo['enabled']);
+echo sprintf("curl_exec function exists: %s\n", function_exists('curl_exec') ? 'Yes' : 'No');
+echo sprintf("curl_exec is in instrumented list: %s\n", in_array('curl_exec', scoutapm_list_instrumented_functions()) ? 'Yes' : 'No');
+
+scoutapm_enable_instrumentation(true);
+
+if (function_exists('curl_exec')) {
+  $ch = curl_init();
+  curl_setopt($ch, CURLOPT_URL, "file://" . __FILE__);
+  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
+  curl_exec($ch);
+}
+
+$calls = scoutapm_get_calls();
+
+if (! array_key_exists(0, $calls)) {
+  echo "curl_exec call recorded: No\n";
+  exit;
+}
+
+echo sprintf("%s call recorded: Yes\n", $calls[0]['function']);

.github/test-curl-compilation/expected-curlext-no-libcurl-no.txt

@@ -0,0 +1,6 @@
+HAVE_CURL: No
+HAVE_SCOUT_CURL: No
+curl instrumented: No
+curl_exec function exists: No
+curl_exec is in instrumented list: No
+curl_exec call recorded: No

.github/test-curl-compilation/expected-curlext-no-libcurl-yes.txt

@@ -0,0 +1,6 @@
+HAVE_CURL: No
+HAVE_SCOUT_CURL: Yes
+curl instrumented: No
+curl_exec function exists: No
+curl_exec is in instrumented list: No
+curl_exec call recorded: No

.github/test-curl-compilation/expected-curlext-yes-libcurl-no.txt

@@ -0,0 +1,6 @@
+HAVE_CURL: No
+HAVE_SCOUT_CURL: No
+curl instrumented: No
+curl_exec function exists: Yes
+curl_exec is in instrumented list: No
+curl_exec call recorded: No

.github/test-curl-compilation/expected-curlext-yes-libcurl-yes.txt

@@ -0,0 +1,6 @@
+HAVE_CURL: No
+HAVE_SCOUT_CURL: Yes
+curl instrumented: Yes
+curl_exec function exists: Yes
+curl_exec is in instrumented list: Yes
+curl_exec call recorded: Yes

.github/workflows/ci-build.yaml

@@ -5,6 +5,31 @@ on:
   pull_request:
 
 jobs:
+  curl-compilation-test:
+    name: "Curl Compile"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        with_curl_ext: ["yes", "no"]
+        with_libcurl: ["yes", "no"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Build the tester tool
+        run: |
+          docker build \
+            --build-arg WITH_CURL_EXT=${{ matrix.with_curl_ext }} \
+            --build-arg WITH_LIBCURL=${{ matrix.with_libcurl }} \
+            --file .github/test-curl-compilation/Dockerfile \
+            --tag scoutapm_ext_test \
+            .
+      - name: Run the tool
+        run: |
+          docker run scoutapm_ext_test > results.txt
+          cat results.txt
+      - name: Check the output
+        run: |
+          diff .github/test-curl-compilation/expected-curlext-${{ matrix.with_curl_ext }}-libcurl-${{ matrix.with_libcurl }}.txt results.txt
   windows-test:
     name: "Win PHPT"
     defaults:
@@ -26,7 +51,7 @@ jobs:
           - { os: windows-2022, php: "7.1" }
     runs-on: ${{matrix.os}}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Setup PHP SDK
         id: setup-php
         uses: cmb69/[email protected]
@@ -123,7 +148,7 @@ jobs:
           - "--with-curl"
           - ""
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: "Set ZTS mode, PHP 8+"
         if: ${{ matrix.zts-mode == 'zts' && startsWith(matrix.php-version, '8.') }}
@@ -184,7 +209,7 @@ jobs:
         php-version:
           - "8.0"
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Setup PHP with PECL extension
         uses: shivammathur/setup-php@v2
         with:

.github/workflows/release-on-milestone-closed-triggering-release-event.yml

@@ -18,7 +18,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v2"
+        uses: actions/checkout@v3
 
       #####################################################
       ################ RELEASE PREPARATION ################

README.md

@@ -32,6 +32,40 @@ The following functions are exposed when the extension is enabled:
  * `scoutapm_list_instrumented_functions(): array`
    - Returns a list of the functions the extension will instrument if called.
 
+## Prerequisites for cURL
+
+In order to have instrumentation for cURL functions enabled, you MUST have `libcurl` available when building or
+installing from `pecl`.
+
+For example, if you are using the `ppa:ondrej/php` PPA on Ubuntu, you must install `libcurl` before building `scoutapm`
+extension, e.g.:
+
+```bash
+$ apt-get -y install libcurl4-openssl-dev
+$ pecl install scoutapm
+```
+
+To confirm if cURL instrumentation is working, check `php -i`:
+
+```
+scoutapm
+
+scoutapm support => enabled
+scoutapm Version => 1.8.3
+scoutapm curl HAVE_CURL => No
+scoutapm curl HAVE_SCOUT_CURL => Yes
+scoutapm curl enabled => Yes
+```
+
+* `scoutapm curl HAVE_CURL` was PHP itself compiled with cURL. This will not always be `Yes`, for example when using
+  pre-packaged binaries where `curl` extension is separate.
+* `scoutapm curl HAVE_SCOUT_CURL` was the `scoutapm` extension compiled and `libcurl` available? If this is `No`, then
+  cURL instrumentation will not be available at all.
+* `scoutapm curl enabled` tells you if `scoutapm` has enabled monitoring (i.e. `curl` extension was available at
+  runtime, and `libcurl` was available when `scoutapm` was compiled). _If this value is `No` and you think it
+  should be `Yes`, check that `libcurl` was available when `scoutapm` was compiled, and that you have the `curl` PHP
+  extension enabled._
+
 ## Installing from PECL
 
 The Scout APM extension is available to install using

package.xml

@@ -25,19 +25,19 @@
     </lead>
 
     <!-- Current Release -->
-    <date>2022-08-26</date>
-    <time>10:30:00</time>
+    <date>2022-10-18</date>
+    <time>07:30:00</time>
     <version>
-        <release>1.8.2</release>
-        <api>1.8.2</api>
+        <release>1.8.3</release>
+        <api>1.8.3</api>
     </version>
     <stability>
         <release>stable</release>
         <api>stable</api>
     </stability>
     <license uri="https://opensource.org/licenses/MIT">MIT</license>
     <notes>
-        - Enable HAVE_SCOUT_CURL if it is available in the Windows builds (#121)
+        - Improved MINFO output for curl availability (#126)
     </notes>
     <!-- End Current Release -->
 
@@ -115,6 +115,22 @@
     <zendextsrcrelease />
 
     <changelog>
+        <release>
+            <date>2022-08-26</date>
+            <time>10:30:00</time>
+            <version>
+                <release>1.8.2</release>
+                <api>1.8.2</api>
+            </version>
+            <stability>
+                <release>stable</release>
+                <api>stable</api>
+            </stability>
+            <license uri="https://opensource.org/licenses/MIT">MIT</license>
+            <notes>
+                - Enable HAVE_SCOUT_CURL if it is available in the Windows builds (#121)
+            </notes>
+        </release>
         <release>
             <date>2022-07-11</date>
             <time>14:30:00</time>

zend_scoutapm.c

@@ -7,6 +7,7 @@
 
 #include "zend_scoutapm.h"
 #include "ext/standard/info.h"
+#include <stdbool.h>
 
 static PHP_GINIT_FUNCTION(scoutapm);
 static PHP_RINIT_FUNCTION(scoutapm);
@@ -45,21 +46,32 @@ static const zend_function_entry scoutapm_functions[] = {
 
 PHP_MINFO_FUNCTION(scoutapm)
 {
-	php_info_print_table_start();
-	php_info_print_table_header(2, "scoutapm support", "enabled");
-	php_info_print_table_row(2, "Version", PHP_SCOUTAPM_VERSION);
+    bool have_scout_curl = false, found_curl_exec = false;
+
+    php_info_print_table_start();
+    php_info_print_table_header(2, "scoutapm support", "enabled");
+    php_info_print_table_row(2, "scoutapm Version", PHP_SCOUTAPM_VERSION);
+
 #if HAVE_CURL
-  #if HAVE_SCOUT_CURL
-	php_info_print_table_row(2, "curl functions", "Yes");
-  #else
-	php_info_print_table_row(2, "curl functions", "Not instrumented");
-  #endif
+    php_info_print_table_row(2, "scoutapm curl HAVE_CURL", "Yes");
+#else
+    php_info_print_table_row(2, "scoutapm curl HAVE_CURL", "No");
+#endif
+
+#if HAVE_SCOUT_CURL
+    have_scout_curl = true;
+    php_info_print_table_row(2, "scoutapm curl HAVE_SCOUT_CURL", "Yes");
 #else
-	php_info_print_table_row(2, "curl functions", "No");
+    php_info_print_table_row(2, "scoutapm curl HAVE_SCOUT_CURL", "No");
 #endif
-	php_info_print_table_row(2, "file functions", "Yes");
-	php_info_print_table_row(2, "pdo functions", "Yes");
-	php_info_print_table_end();
+
+    if (zend_hash_str_find_ptr(EG(function_table), "curl_exec", sizeof("curl_exec") - 1) != NULL) {
+        found_curl_exec = true;
+    }
+
+    php_info_print_table_row(2, "scoutapm curl enabled", (have_scout_curl && found_curl_exec) ? "Yes" : "No");
+
+    php_info_print_table_end();
 }
 
 /* scoutapm_module_entry provides the metadata/information for PHP about this PHP module */

zend_scoutapm.h

@@ -23,7 +23,7 @@
 #include "scout_execute_ex.h"
 
 #define PHP_SCOUTAPM_NAME "scoutapm"
-#define PHP_SCOUTAPM_VERSION "1.8.2"
+#define PHP_SCOUTAPM_VERSION "1.8.3"
 
 /* Extreme amounts of debugging, set to 1 to enable it and `make clean && make` (tests will fail...) */
 #define SCOUT_APM_EXT_DEBUGGING 0