PHP向Firestore提交ArrayValue失败问题排查

Since there’s no official PHP SDK for Firestore 1 beta 1, working with the REST API means you have to strictly follow the API’s payload structure—especially for complex types like ArrayValue. From what you’ve described, the issue is almost certainly related to not formatting the array data correctly for the REST endpoint.

Correct Structure for ArrayValue #

Firestore’s REST API expects ArrayValue to be an object containing a values key, which holds an array of value objects. Each element in the array must explicitly declare its type (e.g., stringValue, integerValue, booleanValue). You can’t just pass a raw PHP array here—you need to wrap each element in its type-specific wrapper.

Example: Working PHP Code for ArrayValue #

Let’s say you want to create a document with an array of strings and numbers. Here’s how to construct the payload correctly, using cURL (adjust authentication details to match your project):

<?php
$projectId = 'your-project-id';
$collection = 'your-collection';
$documentId = 'your-document-id';

// Build the ArrayValue structure
$arrayValue = [
    'arrayValue' => [
        'values' => [
            ['stringValue' => 'First item'],
            ['integerValue' => 42],
            ['booleanValue' => true]
        ]
    ]
];

// Full document payload
$payload = [
    'fields' => [
        'myArray' => $arrayValue,
        'otherField' => ['stringValue' => 'Some text']
    ]
];

// Convert to JSON
$jsonPayload = json_encode($payload);

// Set up cURL request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://firestore.googleapis.com/v1beta1/projects/{$projectId}/databases/(default)/documents/{$collection}?documentId={$documentId}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonPayload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer YOUR_ACCESS_TOKEN' // Replace with valid token
]);

// Execute and handle response
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// Debug output
echo "HTTP Code: {$httpCode}\n";
echo "Response: {$response}\n";
?>

Common Mistakes to Avoid #

• Missing the values wrapper: Forgetting to nest your array elements under the values key inside arrayValue is the most common error. The API will reject payloads that don’t have this structure.
• Not specifying value types: Raw values (like 'First item' instead of ['stringValue' => 'First item']) will trigger validation errors. Every element in the array must have its type explicitly declared.
• Inconsistent value types: Make sure you’re using the correct type key for each value (e.g., use integerValue for numbers, not stringValue). Mixing these up can cause unexpected errors or data misrepresentation.

Troubleshooting Tips #

1. Log your JSON payload: Before sending the request, print out $jsonPayload to verify it matches Firestore’s expected structure. Compare it against the official Firestore REST API reference for beta 1.
2. Check the error response: Firestore’s REST API returns detailed error messages that usually point to exactly what’s wrong with your payload. Look for messages like "Invalid value for field 'fields.myArray.arrayValue': Missing required field 'values'."
3. Verify authentication: Ensure your access token is valid and has the necessary permissions to write to Firestore. A token issue might manifest as a generic error, but it’s worth ruling out.

By following this structure, you should be able to resolve the ArrayValue errors and interact with Firestore’s beta 1 API correctly in PHP.

内容的提问来源于stack exchange，提问作者gsposato