feat(platform): add macOS Homebrew search paths support

- Add HOMEBREW_INCLUDE_PATHS and HOMEBREW_LIBRARY_PATHS constants to Macos class
- Implement buildPhpIncludePaths method to include Homebrew prefixes after PHP installation paths
- Implement buildPhpLibPaths method to add Homebrew library prefixes to native link commands
- Add test case for macOS native build options including Homebrew search paths
- Add comprehensive test for macOS Homebrew search paths functionality
- Import Macos platform class in CompilerBaseApiTest

phpunit/src/CompilerBaseApiTest.php

@@ -7,6 +7,7 @@ use TypePhp\CompilerTest;
 use TypePhp\CompilerBase;
 use TypePhp\Type;
 use TypePhp\Exception\TestError;
+use TypePhp\Platform\Macos;
 use TypePhp\Platform\Windows;
 
 class CompilerBaseApiTest extends TestCase
@@ -791,6 +792,19 @@ YAML);
         $this->assertArrayNotHasKey('cxxflags', $options);
     }
 
+    public function testMacosNativeBuildOptionsIncludeHomebrewSearchPaths(): void
+    {
+        $this->setPropertyValue('platform', new Macos());
+
+        $includePaths = $this->invokeMethod('getIncludePaths');
+        $this->assertContains('/opt/homebrew/include', $includePaths);
+        $this->assertContains('/usr/local/include', $includePaths);
+
+        $libraryPaths = $this->invokeMethod('getLibraryPaths');
+        $this->assertContains('/opt/homebrew/lib', $libraryPaths);
+        $this->assertContains('/usr/local/lib', $libraryPaths);
+    }
+
     public function testExtensionCleanClearsRuntimeMapsWithValidCpp(): void
     {
         global $translator;

phpunit/src/Platform/PlatformTest.php

@@ -299,6 +299,28 @@ class PlatformTest extends TestCase
         $this->assertEquals('-dynamiclib', $platform->getSharedLinkFlag());
     }
 
+    public function testMacosHomebrewSearchPaths(): void
+    {
+        $platform = new Macos();
+
+        $includePaths = $platform->buildPhpIncludePaths('/path/that/does/not/exist');
+        $this->assertContains('/opt/homebrew/include', $includePaths);
+        $this->assertContains('/usr/local/include', $includePaths);
+
+        $libraryPaths = $platform->buildPhpLibPaths('/path/that/does/not/exist');
+        $this->assertContains('/opt/homebrew/lib', $libraryPaths);
+        $this->assertContains('/usr/local/lib', $libraryPaths);
+
+        $this->assertStringContainsString(
+            '-I' . escapeshellarg('/opt/homebrew/include'),
+            $platform->getIncludeFlags($includePaths),
+        );
+        $this->assertStringContainsString(
+            '-L' . escapeshellarg('/opt/homebrew/lib'),
+            $platform->getLibraryPathFlags($libraryPaths),
+        );
+    }
+
     /**
      * 测试空数组处理
      */

src/Platform/Macos.php

@@ -7,6 +7,16 @@ namespace TypePhp\Platform;
  */
 class Macos extends UnixPlatform
 {
+    private const array HOMEBREW_INCLUDE_PATHS = [
+        '/opt/homebrew/include',
+        '/usr/local/include',
+    ];
+
+    private const array HOMEBREW_LIBRARY_PATHS = [
+        '/opt/homebrew/lib',
+        '/usr/local/lib',
+    ];
+
     public function getName(): string
     {
         return 'macOS';
@@ -43,6 +53,30 @@ class Macos extends UnixPlatform
         return '-install_name ' . escapeshellarg($path);
     }
 
+    /**
+     * Add the standard Apple Silicon and Intel Homebrew prefixes after the
+     * selected PHP installation's include paths.
+     */
+    public function buildPhpIncludePaths(string $phpDir): array
+    {
+        return array_values(array_unique(array_merge(
+            parent::buildPhpIncludePaths($phpDir),
+            self::HOMEBREW_INCLUDE_PATHS,
+        )));
+    }
+
+    /**
+     * Add the standard Apple Silicon and Intel Homebrew library prefixes to
+     * every native link command.
+     */
+    public function buildPhpLibPaths(string $phpDir): array
+    {
+        return array_values(array_unique(array_merge(
+            parent::buildPhpLibPaths($phpDir),
+            self::HOMEBREW_LIBRARY_PATHS,
+        )));
+    }
+
     /**
      * 获取默认的 RPATH 路径列表（macOS 需要）
      */