feat(#401): improve JSON field extraction by adding index support #402

martin-georgiev · 2025-07-31T08:01:18Z

Summary by CodeRabbit

New Features
- Enhanced JSON field retrieval functions to support both string keys and integer indices, enabling access to JSON object properties and array elements.
Bug Fixes
- Improved parsing logic for JSON field functions to ensure compatibility with various Doctrine ORM versions.
Tests
- Expanded test coverage with new unit and integration tests covering JSON extraction by key, array index, nested access, null values, and non-existent fields for thorough validation.

coderabbitai · 2025-07-31T08:03:22Z

Walkthrough

The changes update the JSON field extraction functions and their tests to support both string keys and integer indices, aligning with PostgreSQL's JSON operators. Parsing logic in the core classes is enhanced, inheritance hierarchies are adjusted, and test coverage is expanded with cases for array indices and nested JSON access.

Changes

Cohort / File(s)	Change Summary
Core JSON Field Function Parsing `src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetField.php`	Refactored parsing logic to support both string keys and integer indices for JSON field access; introduced `feedParserWithNodes` and removed fixed node mappings; adapted for different Doctrine ORM versions.
Integer JSON Field Extraction `src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldAsInteger.php`	Changed parent class from `BaseFunction` to `JsonGetField`; removed explicit node mappings; updated docblock to clarify support for both string and integer keys.
Text JSON Field Extraction `src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldAsText.php`	Changed parent class from `BaseFunction` to `JsonGetField`; removed explicit node mappings; updated docblock and usage examples for both key types.
Integer Extraction Unit Tests `tests/Unit/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldAsIntegerTest.php`	Added test cases for array indices and nested extraction; registered `JSON_GET_FIELD` for testing; expanded expected SQL/DQL scenarios and descriptions.
Text Extraction Unit Tests `tests/Unit/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldAsTextTest.php`	Added `JsonGetField` to registered functions; expanded tests to cover array indices, nested extraction, and more scenarios; labeled test cases for clarity.
Core JSON Field Unit Tests `tests/Unit/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldTest.php`	Added new test cases for array index extraction and nested field access; expanded SQL/DQL coverage for numeric and string keys.
Integer Extraction Integration Tests `tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldAsIntegerTest.php`	Added `JsonGetField` to registered functions; added new test for integer extraction by array index; renamed a test method for clarity.
Text Extraction Integration Tests `tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldAsTextTest.php`	New integration test class added; tests JSON extraction as text by property name, index, nested access, null values, and non-existent indices.
Core JSON Field Integration Tests `tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldTest.php`	New integration test class added; covers JSON property access by name, array index, nested access, empty arrays, and non-existent fields or indices.

Sequence Diagram(s)

sequenceDiagram
    participant DQL_User as DQL User
    participant Doctrine as Doctrine ORM
    participant JsonGetField as JsonGetField Function
    participant Database as PostgreSQL

    DQL_User->>Doctrine: Use JSON_GET_FIELD(column, key_or_index)
    Doctrine->>JsonGetField: Parse function call
    JsonGetField->>JsonGetField: Parse first arg as StringPrimary (column)
    JsonGetField->>JsonGetField: Try parse second arg as ArithmeticPrimary (index)
    alt If fails
        JsonGetField->>JsonGetField: Parse second arg as StringPrimary (key)
    end
    JsonGetField->>Doctrine: Return parsed AST
    Doctrine->>Database: Generate SQL with -> or ->> operator
    Database-->>Doctrine: Return result
    Doctrine-->>DQL_User: Return extracted value

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~18 minutes

Poem

In fields of JSON, keys and indices play,
Now rabbits can hop both string and integer way.
With parsing improved and tests that abound,
Nested arrays and objects are easily found.
PostgreSQL smiles, the queries run true—
A carrot for each, and a function anew! 🥕

Note

⚡️ Unit Test Generation is now available in beta!

Learn more here, or try it out under "Finishing Touches" below.

📜 Recent review details

Configuration used: .coderabbit.yaml
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9e70791 and 8cbd460.

📒 Files selected for processing (4)

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetField.php (2 hunks)
tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldAsIntegerTest.php (3 hunks)
tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldAsTextTest.php (1 hunks)
tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldTest.php (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetField.php

🧰 Additional context used

🧠 Learnings (4)

📓 Common learnings

Learnt from: martin-georgiev
PR: martin-georgiev/postgresql-for-doctrine#0
File: :0-0
Timestamp: 2025-03-11T17:02:51.971Z
Learning: The PostgreSQL-for-doctrine library implements the JSON array element existence check using the `RIGHT_EXISTS_ON_LEFT` DQL function, which maps to PostgreSQL's `?` operator. This is used for checking if a specific value exists in a JSONB array column.

Learnt from: martin-georgiev
PR: martin-georgiev/postgresql-for-doctrine#277
File: tests/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonValueTest.php:19-35
Timestamp: 2025-03-13T15:00:16.619Z
Learning: The JsonValue implementation in postgres-for-doctrine has documented limitations: it does not support RETURNING type, DEFAULT clause, ON ERROR clause, ON EMPTY clause, and other advanced PostgreSQL JSON_VALUE features due to DQL limitations.

Learnt from: martin-georgiev
PR: martin-georgiev/postgresql-for-doctrine#277
File: tests/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonExistsTest.php:10-0
Timestamp: 2025-03-13T15:04:55.052Z
Learning: The implementation of JSON_EXISTS in this library supports only the basic form with two parameters (target_json, path_text) and doesn't support additional features like strict mode (third boolean parameter), ON ERROR clause, or other advanced PostgreSQL JSON_EXISTS capabilities due to DQL limitations.

Learnt from: martin-georgiev
PR: martin-georgiev/postgresql-for-doctrine#366
File: tests/Unit/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/ArrayPositionsTest.php:1-36
Timestamp: 2025-05-03T00:18:09.078Z
Learning: Always check the current official PostgreSQL documentation at https://www.postgresql.org/docs/ to verify function signatures and behaviors before suggesting improvements or additional tests. The `array_positions` function specifically has a fixed signature with exactly two parameters (array and search value), while `array_position` is variadic with 2-3 parameters.

Learnt from: martin-georgiev
PR: martin-georgiev/postgresql-for-doctrine#366
File: tests/Unit/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/ArrayPositionsTest.php:1-36
Timestamp: 2025-05-03T00:18:09.078Z
Learning: Always check the current official PostgreSQL documentation at https://www.postgresql.org/docs/ to verify function signatures and behaviors before suggesting improvements or additional tests. The `array_positions` function specifically has a fixed signature with exactly two parameters (array and search value), while `array_position` is variadic with 2-3 parameters.

Learnt from: martin-georgiev
PR: martin-georgiev/postgresql-for-doctrine#357
File: tests/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/RegexpMatchTest.php:28-62
Timestamp: 2025-04-22T00:03:37.733Z
Learning: This project focuses on providing Doctrine ORM interfaces to PostgreSQL functions. Tests should validate correct DQL-to-SQL translation rather than PostgreSQL functionality itself. Test cases should focus on parameter passing and SQL generation, not on testing specific PostgreSQL regex pattern behaviors.

Learnt from: martin-georgiev
PR: martin-georgiev/postgresql-for-doctrine#263
File: src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/Numrange.php:19-21
Timestamp: 2025-03-11T12:32:10.726Z
Learning: In the postgresql-for-doctrine repository, PostgreSQL range functions have distinct implementations for different data types. The `Numrange` function works with numeric/decimal values and is tested using the `ContainsDecimals` fixture with properties typed as `float`. In contrast, the `Int4range` function works with 32-bit integers and is tested using the `ContainsIntegers` fixture with properties typed as `int`. While the PHP implementations share a similar structure (extending `BaseFunction`), they are semantically different as they handle different PostgreSQL data types.

Learnt from: martin-georgiev
PR: martin-georgiev/postgresql-for-doctrine#0
File: :0-0
Timestamp: 2025-03-26T02:46:12.804Z
Learning: The PR "preserve the type of floats and integers when transforming back and forth between PostgreSQL and PHP" improves type handling by ensuring that integers remain integers, floats remain floats, numeric strings stay as strings, and booleans are properly converted through the transformation process.

Learnt from: karpilin
PR: martin-georgiev/postgresql-for-doctrine#386
File: tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/ToTimestampTest.php:34-39
Timestamp: 2025-05-27T16:10:35.054Z
Learning: When reviewing PostgreSQL formatting function tests, the error handling behavior should match PostgreSQL's actual implementation rather than assuming consistency across all formatting functions, as different functions may handle invalid inputs differently.

Learnt from: martin-georgiev
PR: martin-georgiev/postgresql-for-doctrine#352
File: tests/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/RegexpInstrTest.php:1-67
Timestamp: 2025-04-20T11:24:18.300Z
Learning: This PostgreSQL-for-Doctrine project is a translation layer only, focusing on correctly converting Doctrine DQL to PostgreSQL SQL syntax. It ensures arguments are passed in the expected format but does not test or handle PostgreSQL's actual function behavior or data handling. Test cases should focus on DQL-to-SQL translation and argument validation, not on PostgreSQL-specific behaviors.

tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldTest.php (8)

Learnt from: martin-georgiev
PR: #383
File: tests/Unit/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/RadiansTest.php:1-9
Timestamp: 2025-05-23T11:11:57.951Z
Learning: Tests in the Tests\Unit\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions namespace extend a custom TestCase class from the same namespace (Tests\Unit\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\TestCase), rather than PHPUnit's TestCase directly, and therefore don't need an explicit import.

Learnt from: martin-georgiev
PR: #318
File: tests/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/XmlAggTest.php:1-9
Timestamp: 2025-03-29T03:31:17.114Z
Learning: Tests in the Tests\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions namespace extend a custom TestCase class from the same namespace (Tests\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\TestCase), rather than PHPUnit's TestCase, and therefore don't need an explicit import.

Learnt from: martin-georgiev
PR: #318
File: tests/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/XmlAggTest.php:1-9
Timestamp: 2025-03-29T03:31:17.114Z
Learning: Tests in the Tests\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions namespace extend a custom TestCase class from the same namespace (Tests\MartinGeorgiev\Doctrine\ORM\Query\AST\Functions\TestCase), not PHPUnit's TestCase, and therefore don't need an explicit import statement.

Learnt from: martin-georgiev
PR: #357
File: tests/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/RegexpMatchTest.php:28-62
Timestamp: 2025-04-22T00:03:37.733Z
Learning: This project focuses on providing Doctrine ORM interfaces to PostgreSQL functions. Tests should validate correct DQL-to-SQL translation rather than PostgreSQL functionality itself. Test cases should focus on parameter passing and SQL generation, not on testing specific PostgreSQL regex pattern behaviors.

Learnt from: martin-georgiev
PR: #340
File: tests/MartinGeorgiev/Doctrine/DBAL/Types/InetArrayTest.php:145-145
Timestamp: 2025-04-11T11:23:44.192Z
Learning: In the PostgreSQL for Doctrine test cases, methods that test database-to-PHP conversions should use mixed type for parameter and include non-string test cases in their data providers, following the pattern in classes like InetTest, CidrTest, and MacaddrTest.

Learnt from: martin-georgiev
PR: #263
File: src/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/Numrange.php:19-21
Timestamp: 2025-03-11T12:32:10.726Z
Learning: In the postgresql-for-doctrine repository, PostgreSQL range functions have distinct implementations for different data types. The Numrange function works with numeric/decimal values and is tested using the ContainsDecimals fixture with properties typed as float. In contrast, the Int4range function works with 32-bit integers and is tested using the ContainsIntegers fixture with properties typed as int. While the PHP implementations share a similar structure (extending BaseFunction), they are semantically different as they handle different PostgreSQL data types.

Learnt from: martin-georgiev
PR: #277
File: tests/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonValueTest.php:19-35
Timestamp: 2025-03-13T15:00:16.619Z
Learning: The JsonValue implementation in postgres-for-doctrine has documented limitations: it does not support RETURNING type, DEFAULT clause, ON ERROR clause, ON EMPTY clause, and other advanced PostgreSQL JSON_VALUE features due to DQL limitations.

Learnt from: martin-georgiev
PR: martin-georgiev/postgresql-for-doctrine#0
File: :0-0
Timestamp: 2025-03-11T17:02:51.971Z
Learning: The PostgreSQL-for-doctrine library implements the JSON array element existence check using the RIGHT_EXISTS_ON_LEFT DQL function, which maps to PostgreSQL's ? operator. This is used for checking if a specific value exists in a JSONB array column.

tests/Integration/MartinGeorgiev/Doctrine/ORM/Query/AST/Functions/JsonGetFieldAsIntegerTest.php (8)