fix: resolve FFI segfault caused by ext/curl symbol collision

When ext/curl is loaded, PHP has standard libcurl symbols in memory.
Loading libcurl-impersonate via FFI::cdef() causes duplicate symbols
(both export curl_easy_perform, etc.), leading to ABI mismatch segfaults.

Fix: use dlopen() with RTLD_DEEPBIND flag on Linux, which makes
libcurl-impersonate prefer its own symbols over the already-loaded
standard libcurl. The dlopen handle is kept alive in FfiWrapper to
prevent the library from being unloaded.

Verified: FfiTransport now works with ext/curl loaded simultaneously.

Author: danielhe4rt

phpstan.neon.dist

@@ -10,3 +10,7 @@ parameters:
             identifier: method.notFound
             path: src/Transport/Ffi/FfiWrapper.php
             message: '#^Call to an undefined method FFI::#'
+        -
+            identifier: property.onlyWritten
+            path: src/Transport/Ffi/FfiWrapper.php
+            message: '#dlHandle#'

src/Transport/Ffi/FfiWrapper.php

@@ -10,8 +10,17 @@
 
 class FfiWrapper
 {
+    private const int RTLD_NOW = 2;
+
+    private const int RTLD_DEEPBIND = 8;
+
     private FFI $ffi;
 
+    /**
+     * @var CData|null dlopen handle — kept alive to prevent unloading
+     */
+    private ?CData $dlHandle = null;
+
     public function __construct(string $headerPath, string $libraryPath)
     {
         if (! extension_loaded('ffi')) {
@@ -28,7 +37,17 @@ public function __construct(string $headerPath, string $libraryPath)
             throw new FfiException('Could not read FFI header file: '.$headerPath);
         }
 
-        $this->ffi = FFI::cdef($header, $libraryPath);
+        // When ext/curl is loaded, PHP already has standard libcurl symbols in memory.
+        // Loading libcurl-impersonate via FFI::cdef() causes symbol collision (both
+        // export curl_easy_init, curl_easy_perform, etc.), leading to segfaults.
+        //
+        // Fix: use dlopen() with RTLD_DEEPBIND to make libcurl-impersonate prefer
+        // its own symbols over the already-loaded standard libcurl.
+        if (extension_loaded('curl') && PHP_OS_FAMILY === 'Linux') {
+            $this->loadWithDeepbind($header, $libraryPath);
+        } else {
+            $this->ffi = FFI::cdef($header, $libraryPath);
+        }
     }
 
     public function easyInit(): CData
@@ -84,4 +103,34 @@ public function slistFreeAll(?CData $list): void
             $this->ffi->curl_slist_free_all($list);
         }
     }
+
+    /**
+     * Load libcurl-impersonate with RTLD_DEEPBIND to avoid symbol collision
+     * with PHP's ext/curl (which loads standard libcurl).
+     */
+    private function loadWithDeepbind(string $header, string $libraryPath): void
+    {
+        $dl = FFI::cdef('
+            void *dlopen(const char *filename, int flags);
+            char *dlerror(void);
+        ');
+
+        /** @var CData|null $handle */
+        $handle = $dl->dlopen($libraryPath, self::RTLD_NOW | self::RTLD_DEEPBIND);
+
+        if ($handle === null) {
+            /** @var CData $errorPtr */
+            $errorPtr = $dl->dlerror();
+            $error = FFI::string($errorPtr);
+
+            throw new FfiException('Failed to dlopen libcurl-impersonate: '.$error);
+        }
+
+        // Keep the handle alive so the library stays loaded
+        $this->dlHandle = $handle;
+
+        // Create FFI interface without a library path — symbols are already loaded
+        // via dlopen with RTLD_DEEPBIND, so FFI resolves to the impersonate version
+        $this->ffi = FFI::cdef($header);
+    }
 }

src/Transport/TransportFactory.php

@@ -29,7 +29,6 @@ public static function create(): TransportInterface
             return new CurlTransport;
         }
 
-    
         throw new TransportException('No suitable transport available. Install ext-curl or curl-impersonate.');
     }
 }