refactor(php): dedup library-name resolution and simplify the SDK

domenkozar · claude · domenkozar · commit 3e3cc6f604da · 2026-07-14T08:41:27.000-06:00
Give Native one authority for the platform cdylib file name and have the
ext-ffi installer reuse it, so the downloaded copy and the loader can no
longer drift. Collapse the list-of-one library-name lookup, borrow the
request JSON as &amp;str across the native boundary, and factor the repeated
builder wiring and request-field setters into shared helpers.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/secretspec-php/native/lib.rs b/secretspec-php/native/lib.rs
@@ -18,8 +18,8 @@ use ext_php_rs::prelude::*;
 ///
 /// Exposed to PHP as the global function `secretspec_native_resolve()`.
 #[php_function]
-pub fn secretspec_native_resolve(request_json: String) -> String {
-    secretspec::resolve_json(&request_json)
+pub fn secretspec_native_resolve(request_json: &str) -> String {
+    secretspec::resolve_json(request_json)
 }
 
 /// The extension's version (tracks the crate version). Exposed to PHP as
diff --git a/secretspec-php/scripts/install-ffi-lib.php b/secretspec-php/scripts/install-ffi-lib.php
@@ -56,12 +56,17 @@ function note(string $message): never
     note('SECRETSPEC_FFI_LIB is set; skipping download.');
 }
 
-// Map the running platform to the release target triple + library file name.
-[$target, $libName] = secretspec_target();
+// Map the running platform to the release target triple; the library file name
+// comes from Native so the download target and the loader agree on one name.
+$target = secretspec_target();
 if ($target === null) {
     note('no prebuilt secretspec-ffi library for this platform; set '
         . 'SECRETSPEC_FFI_LIB or install the secretspec extension.');
 }
+if (!class_exists(\Secretspec\Native::class)) {
+    note('the Secretspec classes are not autoloadable; run `composer install` first.');
+}
+$libName = \Secretspec\Native::libraryFileName();
 
 $libDir = dirname(__DIR__) . '/lib';
 $dest = $libDir . '/' . $libName;
@@ -106,10 +111,10 @@ function note(string $message): never
 exit(0);
 
 /**
- * @return array{0: ?string, 1: string} the release target triple (or null if
- *   unsupported) and the platform library file name
+ * The release target triple for the running platform, or null if no prebuilt
+ * secretspec-ffi library is published for it.
  */
-function secretspec_target(): array
+function secretspec_target(): ?string
 {
     $machine = strtolower(php_uname('m'));
     $isArm = in_array($machine, ['arm64', 'aarch64'], true);
@@ -118,25 +123,25 @@ function secretspec_target(): array
     switch (PHP_OS_FAMILY) {
         case 'Linux':
             if ($isX64) {
-                return ['x86_64-unknown-linux-gnu', 'libsecretspec_ffi.so'];
+                return 'x86_64-unknown-linux-gnu';
             }
             if ($isArm) {
-                return ['aarch64-unknown-linux-gnu', 'libsecretspec_ffi.so'];
+                return 'aarch64-unknown-linux-gnu';
             }
             break;
         case 'Darwin':
             if ($isArm) {
-                return ['aarch64-apple-darwin', 'libsecretspec_ffi.dylib'];
+                return 'aarch64-apple-darwin';
             }
             break;
         case 'Windows':
             if ($isX64) {
-                return ['x86_64-pc-windows-msvc', 'secretspec_ffi.dll'];
+                return 'x86_64-pc-windows-msvc';
             }
             break;
     }
 
-    return [null, ''];
+    return null;
 }
 
 /** The installed version of this package, or null in a dev/path checkout. */
@@ -163,11 +168,11 @@ function secretspec_installed_version(): ?string
 /** GET a URL, returning the body or null on any failure. */
 function secretspec_fetch(string $url): ?string
 {
+    // PHP's HTTP stream wrapper reads its options from the 'http' key for both
+    // http:// and https:// URLs, so a single entry covers both.
     $context = stream_context_create([
         'http' => ['method' => 'GET', 'follow_location' => 1, 'timeout' => 30,
             'header' => 'User-Agent: secretspec-php-installer'],
-        'https' => ['method' => 'GET', 'follow_location' => 1, 'timeout' => 30,
-            'header' => 'User-Agent: secretspec-php-installer'],
     ]);
     $body = @file_get_contents($url, false, $context);
 
diff --git a/secretspec-php/src/Builder.php b/secretspec-php/src/Builder.php
@@ -29,38 +29,32 @@ final class Builder
     /** Path to a `secretspec.toml`; omit to walk up from the working directory. */
     public function withPath(?string $path): self
     {
-        if ($path !== null) {
-            $this->request['path'] = $path;
-        }
-
-        return $this;
+        return $this->set('path', $path);
     }
 
     /** Provider address, e.g. `keyring://` or `dotenv://.env.production`. */
     public function withProvider(?string $provider): self
     {
-        if ($provider !== null) {
-            $this->request['provider'] = $provider;
-        }
-
-        return $this;
+        return $this->set('provider', $provider);
     }
 
     /** Profile to resolve, e.g. `production`. */
     public function withProfile(?string $profile): self
     {
-        if ($profile !== null) {
-            $this->request['profile'] = $profile;
-        }
-
-        return $this;
+        return $this->set('profile', $profile);
     }
 
     /** Human-readable reason for the access, surfaced to reason-policy providers. */
     public function withReason(?string $reason): self
     {
-        if ($reason !== null) {
-            $this->request['reason'] = $reason;
+        return $this->set('reason', $reason);
+    }
+
+    /** Set a request field when the value is provided; a no-op for null. */
+    private function set(string $key, ?string $value): self
+    {
+        if ($value !== null) {
+            $this->request[$key] = $value;
         }
 
         return $this;
diff --git a/secretspec-php/src/Native.php b/secretspec-php/src/Native.php
@@ -125,14 +125,12 @@ private static function locateLibrary(): string
             return $env;
         }
 
-        $names = self::libraryNames();
+        $name = self::libraryFileName();
 
         // A copy bundled alongside the package (distribution layout).
-        foreach ($names as $name) {
-            $bundled = \dirname(__DIR__) . \DIRECTORY_SEPARATOR . 'lib' . \DIRECTORY_SEPARATOR . $name;
-            if (\is_file($bundled)) {
-                return $bundled;
-            }
+        $bundled = \dirname(__DIR__) . \DIRECTORY_SEPARATOR . 'lib' . \DIRECTORY_SEPARATOR . $name;
+        if (\is_file($bundled)) {
+            return $bundled;
         }
 
         // Walk up from the package looking for a Cargo target dir; pick the most
@@ -143,15 +141,13 @@ private static function locateLibrary(): string
             $best = null;
             $bestMtime = -1;
             foreach (['release', 'debug'] as $profile) {
-                foreach ($names as $name) {
-                    $candidate = $dir . \DIRECTORY_SEPARATOR . 'target'
-                        . \DIRECTORY_SEPARATOR . $profile . \DIRECTORY_SEPARATOR . $name;
-                    if (\is_file($candidate)) {
-                        $mtime = \filemtime($candidate);
-                        if ($mtime !== false && $mtime > $bestMtime) {
-                            $best = $candidate;
-                            $bestMtime = $mtime;
-                        }
+                $candidate = $dir . \DIRECTORY_SEPARATOR . 'target'
+                    . \DIRECTORY_SEPARATOR . $profile . \DIRECTORY_SEPARATOR . $name;
+                if (\is_file($candidate)) {
+                    $mtime = \filemtime($candidate);
+                    if ($mtime !== false && $mtime > $bestMtime) {
+                        $best = $candidate;
+                        $bestMtime = $mtime;
                     }
                 }
             }
@@ -171,13 +167,17 @@ private static function locateLibrary(): string
         );
     }
 
-    /** @return list<string> platform-specific shared-library file names. */
-    private static function libraryNames(): array
+    /**
+     * The platform-specific `libsecretspec_ffi` file name the loader looks for.
+     * Shared with the `secretspec-install-lib` script so the downloaded copy and
+     * the loader agree on one name.
+     */
+    public static function libraryFileName(): string
     {
         return match (\PHP_OS_FAMILY) {
-            'Darwin' => ['libsecretspec_ffi.dylib'],
-            'Windows' => ['secretspec_ffi.dll'],
-            default => ['libsecretspec_ffi.so'],
+            'Darwin' => 'libsecretspec_ffi.dylib',
+            'Windows' => 'secretspec_ffi.dll',
+            default => 'libsecretspec_ffi.so',
         };
     }
 }
diff --git a/secretspec-php/src/SecretSpec.php b/secretspec-php/src/SecretSpec.php
@@ -47,12 +47,7 @@ public static function resolve(
         ?string $profile = null,
         ?string $reason = null,
     ): Resolved {
-        return self::builder()
-            ->withPath($path)
-            ->withProvider($provider)
-            ->withProfile($profile)
-            ->withReason($reason)
-            ->load();
+        return self::configured($path, $provider, $profile, $reason)->load();
     }
 
     /**
@@ -67,12 +62,21 @@ public static function report(
         ?string $profile = null,
         ?string $reason = null,
     ): Report {
+        return self::configured($path, $provider, $profile, $reason)->report();
+    }
+
+    /** Build a {@see Builder} from the shared one-shot options. */
+    private static function configured(
+        ?string $path,
+        ?string $provider,
+        ?string $profile,
+        ?string $reason,
+    ): Builder {
         return self::builder()
             ->withPath($path)
             ->withProvider($provider)
             ->withProfile($profile)
-            ->withReason($reason)
-            ->report();
+            ->withReason($reason);
     }
 
     /** The ABI version reported by the loaded native library. */
