Modernize PHP support from PHP 7.1+ to PHP 8.2+

.github/workflows/build.yml

@@ -119,7 +119,7 @@ jobs:
     runs-on: ubuntu-24.04
     strategy:
       matrix:
-        php-version: [7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3]
+        php-version: ['8.2', '8.3', '8.4', '8.5']
       fail-fast: false
     steps:
       - uses: actions/checkout@v6
@@ -128,12 +128,19 @@ jobs:
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php-version }}
-          extensions: mbstring, intl, xml, curl
+          extensions: mbstring, intl, xml, curl, sockets
           ini-values: "error_reporting=E_ALL"
 
       - name: Install Dependencies
         run: composer install
 
+      - name: Run Phan static analysis
+        if: matrix.php-version == '8.2'
+        continue-on-error: true
+        run: |
+          cd lib/php
+          ../../vendor/bin/phan --allow-polyfill-parser --minimum-severity 10 --config-file .phan/config.php
+
       - name: Run bootstrap
         run: ./bootstrap.sh
 
@@ -164,9 +171,32 @@ jobs:
           compiler/cpp/thrift --gen php:json,nsglobal="Json" -r --out ./lib/php/test/Resources/packages/phpjs lib/php/test/Resources/ThriftTest.thrift
           compiler/cpp/thrift --gen php:classmap,server,rest,nsglobal="Classmap" -r --out ./lib/php/test/Resources/packages/phpcm lib/php/test/Resources/ThriftTest.thrift
 
+      - name: Build PHP C extension
+        run: make -C lib/php
+
+      - name: Verify PHP C extension loads
+        run: |
+          php -d extension=lib/php/src/ext/thrift_protocol/modules/thrift_protocol.so \
+            -r 'exit(function_exists("thrift_protocol_write_binary") ? 0 : 1);'
+
       - name: Run Tests
         run: vendor/bin/phpunit -c lib/php/phpunit.xml
 
+      - name: Prepare PHP precross artifacts
+        if: matrix.php-version == '8.2'
+        run: make -C test/php precross
+
+      - name: Upload PHP precross artifacts
+        if: matrix.php-version == '8.2'
+        uses: actions/upload-artifact@v6
+        with:
+          name: php-precross
+          if-no-files-found: error
+          path: |
+            test/php/gen-*
+            lib/php/src/ext/thrift_protocol/modules/thrift_protocol.so
+          retention-days: 3
+
   lib-go:
     needs: compiler
     runs-on: ubuntu-24.04
@@ -799,14 +829,22 @@ jobs:
       - lib-go
       - lib-python
       - lib-cpp
+      - lib-php
     runs-on: ubuntu-24.04
     strategy:
       matrix:
         # swift is currently broken and no maintainers around -> see THRIFT-5864
         # kotlin cross test are failing -> see THRIFT-5879
-        server_lang: ['java', 'go', 'rs', 'cpp']
+        server_lang: ['java', 'go', 'rs', 'cpp', 'php']
         # we always use comma join as many client langs as possible, to reduce the number of jobs
-        client_lang: ['java,kotlin', 'go,rs,cpp']
+        client_lang: ['java,kotlin', 'go,rs,cpp', 'php']
+        exclude:
+          # PHP cross test fixtures currently track v0.16 IDL and are not wire-compatible
+          # with modern java/kotlin/go/rs/cpp client suites in this matrix.
+          - server_lang: 'php'
+            client_lang: 'java,kotlin'
+          - server_lang: 'php'
+            client_lang: 'go,rs,cpp'
       fail-fast: false
     steps:
       - uses: actions/checkout@v6
@@ -822,6 +860,16 @@ jobs:
           java-version: 8
           cache: "gradle"
 
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.2'
+          extensions: mbstring, intl, xml, curl, sockets
+          ini-values: "error_reporting=E_ALL"
+
+      - name: Install PHP dependencies
+        run: composer install
+
       - name: Install openssl and certificates (for SSL tests)
         run: |
           sudo apt-get update -yq
@@ -868,6 +916,19 @@ jobs:
           name: cpp-precross
           path: .
 
+      - name: Download php precross artifacts
+        uses: actions/download-artifact@v7
+        with:
+          name: php-precross
+          path: .
+
+      - name: Recreate php_ext_dir for this runner
+        run: |
+          mkdir -p test/php/php_ext_dir
+          ln -sf ../../../lib/php/src/ext/thrift_protocol/modules/thrift_protocol.so test/php/php_ext_dir/
+          ln -sf "$(php-config --extension-dir)/json.so" test/php/php_ext_dir/
+          ln -sf "$(php-config --extension-dir)/sockets.so" test/php/php_ext_dir/
+
       - name: Set back executable flags
         run: |
           chmod a+x lib/java/build/run*

CHANGES.md

@@ -2,6 +2,19 @@
 
 ## 0.22.0
 
+### PHP
+
+- Modernized PHP library for PHP 8.2+ with full type declarations
+- Added typed properties and method signatures throughout the library
+- Updated code generator to emit typed PHP 8.2+ code
+- Enum constants now use `public const NAME = value;` syntax with explicit visibility
+- Generated struct properties use nullable types (e.g., `?string $name = null`)
+- Constructor parameters are now typed (`?array $vals = null`)
+- `read()` and `write()` methods now have `: int` return types
+- Updated PHPUnit to 10.5+, using PHP 8 attributes for data providers
+- Added Phan static analysis configuration
+- Added PHP to cross-test integration matrix
+
 ### Build Process
 
 - [THRIFT-5836](https://issues.apache.org/jira/browse/THRIFT-5836) - 0.21.0 fails to build from sources at Arch Linux: No rule to make target 'Thrift5272.thrift', needed by 'gen-cpp/Thrift5272_types.h'

compiler/cpp/src/thrift/generate/t_php_generator.cc

@@ -231,6 +231,7 @@ class t_php_generator : public t_oop_generator {
   std::string type_to_cast(t_type* ttype);
   std::string type_to_enum(t_type* ttype);
   std::string type_to_phpdoc(t_type* ttype);
+  std::string php_type_declaration(t_type* ttype);
 
   bool php_is_scalar(t_type *ttype) {
     ttype = ttype->get_true_type();
@@ -563,7 +564,7 @@ void t_php_generator::generate_enum(t_enum* tenum) {
   for (c_iter = constants.begin(); c_iter != constants.end(); ++c_iter) {
     int value = (*c_iter)->get_value();
     generate_php_doc(f_enum, *c_iter);
-    indent(f_enum) << "const " << (*c_iter)->get_name() << " = " << value << ";" << '\n'
+    indent(f_enum) << "public const " << (*c_iter)->get_name() << " = " << value << ";" << '\n'
                    << '\n';
   }
 
@@ -957,13 +958,23 @@ void t_php_generator::generate_php_struct_definition(ostream& out,
     }
     generate_php_doc(out, *m_iter);
     string access = (getters_setters_) ? "private" : "public";
-    indent(out) << access << " $" << (*m_iter)->get_name() << " = " << dval << ";" << '\n';
+    string field_name = (*m_iter)->get_name();
+    // Skip type declarations for inherited exception properties (message, code, file, line)
+    // as PHP doesn't allow redeclaring them with types
+    bool skip_type = is_exception && (field_name == "message" || field_name == "code" ||
+                                       field_name == "file" || field_name == "line");
+    if (skip_type) {
+      indent(out) << access << " $" << field_name << " = " << dval << ";" << '\n';
+    } else {
+      string php_type = php_type_declaration(t);
+      indent(out) << access << " ?" << php_type << " $" << field_name << " = " << dval << ";" << '\n';
+    }
   }
 
   out << '\n';
 
   // Generate constructor from array
-  string param = (members.size() > 0) ? "$vals = null" : "";
+  string param = (members.size() > 0) ? "?array $vals = null" : "";
   out << indent() << "public function __construct(" << param << ")"<< '\n'
       << indent() << "{" << '\n';
   indent_up();
@@ -1038,7 +1049,7 @@ void t_php_generator::generate_php_struct_reader(ostream& out, t_struct* tstruct
   const vector<t_field*>& fields = tstruct->get_members();
   vector<t_field*>::const_iterator f_iter;
 
-  indent(out) << "public function read($input)" << '\n';
+  indent(out) << "public function read($input): int" << '\n';
   scope_up(out);
 
   if (oop_) {
@@ -1160,9 +1171,9 @@ void t_php_generator::generate_php_struct_writer(ostream& out, t_struct* tstruct
   vector<t_field*>::const_iterator f_iter;
 
   if (binary_inline_) {
-    indent(out) << "public function write(&$output)" << '\n';
+    indent(out) << "public function write(&$output): int" << '\n';
   } else {
-    indent(out) << "public function write($output)" << '\n';
+    indent(out) << "public function write($output): int" << '\n';
   }
   indent(out) << "{" << '\n';
   indent_up();
@@ -2779,7 +2790,7 @@ string t_php_generator::type_to_cast(t_type* type) {
     case t_base_type::TYPE_I64:
       return "(int)";
     case t_base_type::TYPE_DOUBLE:
-      return "(double)";
+      return "(float)";
     case t_base_type::TYPE_STRING:
       return "(string)";
     default:
@@ -2791,6 +2802,47 @@ string t_php_generator::type_to_cast(t_type* type) {
   return "";
 }
 
+/**
+ * Converts the parse type to a PHP 8.2+ type declaration string.
+ */
+string t_php_generator::php_type_declaration(t_type* type) {
+  type = get_true_type(type);
+
+  if (type->is_base_type()) {
+    t_base_type::t_base tbase = ((t_base_type*)type)->get_base();
+    switch (tbase) {
+    case t_base_type::TYPE_VOID:
+      return "mixed";
+    case t_base_type::TYPE_STRING:
+      return "string";
+    case t_base_type::TYPE_BOOL:
+      return "bool";
+    case t_base_type::TYPE_I8:
+    case t_base_type::TYPE_I16:
+    case t_base_type::TYPE_I32:
+    case t_base_type::TYPE_I64:
+      return "int";
+    case t_base_type::TYPE_DOUBLE:
+      return "float";
+    default:
+      return "mixed";
+    }
+  } else if (type->is_enum()) {
+    return "int";
+  } else if (type->is_struct() || type->is_xception()) {
+    string ns = php_namespace(type->get_program());
+    // If namespace already starts with \, don't add another one
+    if (ns.empty() || ns[0] != '\\') {
+      ns = "\\" + ns;
+    }
+    return ns + type->get_name();
+  } else if (type->is_map() || type->is_set() || type->is_list()) {
+    return "array";
+  }
+
+  return "mixed";
+}
+
 /**
  * Converts the parse type to a C++ enum string for the given type.
  */

composer.json

@@ -18,12 +18,14 @@
         "issues": "https://issues.apache.org/jira/browse/THRIFT"
     },
     "require": {
-        "php": "^7.1 || ^8.0"
+        "php": "^8.2",
+        "ext-sockets": "*"
     },
     "require-dev": {
-        "phpunit/phpunit": "^7.5 || ^8.5 || ^9.5",
+        "phpunit/phpunit": "^10.5 || ^11.0",
         "squizlabs/php_codesniffer": "3.*",
         "php-mock/php-mock-phpunit": "^2.10",
+        "phan/phan": "^5.4",
         "ext-json": "*",
         "ext-xml": "*",
         "ext-curl": "*",

lib/php/.phan/config.php

@@ -0,0 +1,90 @@
+<?php
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+return [
+    'target_php_version' => '8.2',
+
+    'directory_list' => [
+        'lib/',
+    ],
+
+    'exclude_analysis_directory_list' => [
+        'vendor/',
+    ],
+
+    'plugins' => [
+        'AlwaysReturnPlugin',
+        'DollarDollarPlugin',
+        'DuplicateArrayKeyPlugin',
+        'DuplicateExpressionPlugin',
+        'PregRegexCheckerPlugin',
+        'PrintfCheckerPlugin',
+        'SleepCheckerPlugin',
+        'UnreachableCodePlugin',
+        'UseReturnValuePlugin',
+        'EmptyStatementListPlugin',
+        'LoopVariableReusePlugin',
+    ],
+
+    // Relaxed checking for legacy code compatibility
+    'strict_method_checking' => false,
+    'strict_param_checking' => false,
+    'strict_property_checking' => false,
+    'strict_return_checking' => false,
+
+    'analyze_signature_compatibility' => true,
+    'allow_missing_properties' => false,
+    'null_casts_as_any_type' => true,
+    'null_casts_as_array' => false,
+    'array_casts_as_null' => false,
+    'scalar_implicit_cast' => false,
+
+    'dead_code_detection' => false,
+    'unused_variable_detection' => false,
+
+    // Minimum severity to report (0-10, higher = more severe)
+    // 5 = only report critical issues like syntax errors
+    'minimum_severity' => 5,
+
+    'suppress_issue_types' => [
+        // Suppress issues for pre-existing code patterns
+        'PhanUndeclaredProperty',
+        'PhanPossiblyUndeclaredVariable',
+        'PhanTypeMismatchArgument',
+        'PhanTypeMismatchArgumentNullable',
+        'PhanTypeMismatchArgumentReal',
+        'PhanTypeMismatchArgumentInternal',
+        'PhanTypeMismatchReturnNullable',
+        'PhanTypeMismatchDimAssignment',
+        'PhanTypeMismatchDeclaredParamNullable',
+        'PhanPartialTypeMismatchArgument',
+        'PhanPartialTypeMismatchArgumentInternal',
+        'PhanPartialTypeMismatchReturn',
+        'PhanPossiblyNonClassMethodCall',
+        'PhanPossiblyNullTypeArgumentInternal',
+        'PhanPossiblyFalseTypeArgumentInternal',
+        'PhanPossiblyFalseTypeArgument',
+        'PhanNonClassMethodCall',
+        'PhanTypePossiblyInvalidCallable',
+        'PhanParamTooMany',
+        'PhanUnreferencedUseNormal',
+        'PhanPluginDuplicateConditionalNullCoalescing',
+    ],
+];