BigQuery: ValueMapper::recordFromBigQuery() crashes with TypeError when STRUCT field contains NULL

[vojtabiberle]

Environment details

• OS: Linux (also reproducible on other platforms)
• PHP version: 8.1+
• Package name and version: google/cloud-bigquery v1.34.0 (also affects v1.35.0 and main branch)

Summary

When querying a BigQuery table that contains nullable STRUCT/RECORD columns with NULL values, the ValueMapper::fromBigQuery() method throws a TypeError because it passes null to recordFromBigQuery() which expects an array.

Steps to reproduce

1. Create a BigQuery table with a nullable STRUCT column:

CREATE TABLE `project.dataset.test_table` (
  id INT64,
  actor STRUCT<
    email STRING,
    profileId STRING
  >
);

INSERT INTO `project.dataset.test_table` VALUES (1, NULL);

2. Query the table using the PHP client:

  use Google\Cloud\BigQuery\BigQueryClient;

  $bigQuery = new BigQueryClient();
  $dataset = $bigQuery->dataset('dataset');
  $table = $dataset->table('test_table');

  // This crashes when a row has NULL STRUCT value
  foreach ($table->rows() as $row) {
      print_r($row);
  }

Expected behavior

NULL STRUCT values should be returned as null in PHP, similar to how other nullable types are handled.

Actual behavior

TypeError: Google\Cloud\BigQuery\ValueMapper::recordFromBigQuery():
Argument #1 ($value) must be of type array, null given,
called in vendor/google/cloud-bigquery/src/ValueMapper.php on line 124

Root cause

In ValueMapper::fromBigQuery() (line 79-137), there's a null check for NULLABLE mode at lines 88-90, but it only works if $schema['mode'] is set. For TYPE_RECORD at line 123-124, the code directly calls recordFromBigQuery($value, $schema['fields']) without checking if $value is null first.

Suggested fix

Add a null check before calling recordFromBigQuery():

  case self::TYPE_RECORD:
      if ($value === null) {
          return null;
      }
      return $this->recordFromBigQuery($value, $schema['fields']);

Related issues

• BigQuery: improve handling of null records in structLoader google-cloud-go#735 - Similar issue was fixed in the Go client library for null STRUCT handling

Impact

This bug prevents reading any BigQuery table that has:

• STRUCT columns that allow NULL values
• Rows where those STRUCT columns contain NULL

This is a common pattern for audit logs, nested data structures, and optional complex fields.