[FrameworkBundle][JsonPath] Add support for custom JsonPath functions #61517

alexandre-daubois · 2025-08-25T09:22:09Z

Q	A
Branch?	7.4
Bug fix?	no
New feature?	yes
Deprecations?	no
Issues	-
License	MIT

Requires #61132. Only second commit (1927fa4) should be reviewed.

This PR allows to create custom JsonPath functions thanks to the #[AsJsonPathFunction] attribute:

<?php

namespace App\JsonPath;

use Symfony\Component\JsonPath\Functions\AbstractJsonPathFunction;
use Symfony\Component\JsonPath\Functions\AsJsonPathFunction;
use Symfony\Component\JsonPath\Functions\JsonPathFunctionArgumentTrait;

#[AsJsonPathFunction(name: 'upper')]
final class UpperFunction extends AbstractJsonPathFunction
{
    use JsonPathFunctionArgumentTrait;

    public function __invoke(array $args, mixed $context): ?string
    {
        $results = $args[0] ?? [];
        $value = \is_array($results) ? ($results[0] ?? null) : $results;

        return \is_string($value) ? strtoupper($value) : null;
    }

    public function validate(array $args): void
    {
        self::assertArgumentsCount($args, 1);
    }
}

Then, it's used like this:

<?php

namespace App\Command;

// ...

#[AsCommand(name: 'cmd', description: 'Hello PhpStorm')]
class MyCommand extends Command
{
    public function __construct(
        private JsonPathFunctionsProviderInterface $jsonPathFunctionsProvider,
    ) {
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $crawler = new JsonCrawler(<<<JSON
            {"name": "test", "items": [{"title": "hello"}, {"title": "world"}]}
        JSON, $this->jsonPathFunctionsProvider); // <-- provide the functions provider

        $result = $crawler->find('$.items[?upper(@.title) == "HELLO"]');

        dump($result);

        return Command::SUCCESS;
    }
}

All RFC built-in functions are converted to use the new AbstractJsonPathFunction to avoid special case handling in the crawler code. This uses the approach detailed here: #60624 (comment). What's also nice is that built-in functions now have their very own unit tests as well.

stof · 2025-08-25T10:12:06Z

src/Symfony/Component/JsonPath/Functions/AbstractJsonPathFunction.php

+abstract class AbstractJsonPathFunction implements JsonPathFunctionInterface
+{
+    public function __construct(
+        private ?string $name = null,


This should not use a promoted property, to decouple the parameter type (nullable) from the private property type (not nullable)

stof · 2025-08-25T10:14:29Z

src/Symfony/Component/JsonPath/Functions/JsonPathFunctionArgumentTrait.php

+ */
+trait JsonPathFunctionArgumentTrait
+{
+    public static function assertArgumentsCount(array $args, int $expectedCount): void


why making the public static methods if this is in a trait ?

Either we should have public static utilities in a dedicated class expected to be called statically, or we should have a trait defining private instance methods (so that using the trait does not expend the public API of the class implementing a function)

stof · 2025-08-25T10:15:17Z

src/Symfony/Component/JsonPath/Functions/JsonPathFunctionInterface.php

+interface JsonPathFunctionInterface
+{
+    /**
+     * @param array<string> $args    Array of argument strings as they appear in the expression


I would even be list<string> to be more precise, as they are always provided as a list.

stof · 2025-08-25T10:15:36Z

src/Symfony/Component/JsonPath/Functions/JsonPathFunctionInterface.php

+     *
+     * @param array<string> $args Array of argument strings as they appear in the expression
+     *
+     * @throws \InvalidArgumentException When arguments are invalid


shouldn't this use an exception class of the component instead ?

stof · 2025-08-25T10:18:10Z

src/Symfony/Component/JsonPath/Functions/JsonPathFunctionsProvider.php

+    public function __construct(iterable $functions = [])
+    {
+        foreach ($functions as $function) {
+            $this->addFunction($function);


instead of injecting an iterable that is used in the constructor (breaking any lazy-loading of the iterator argument provided by the DI component), I suggest injecting a service locator instead (which would require knowing the name statically, which could be done by always specifying the name in the attribute instead of the getName method in the instance)

stof · 2025-08-25T10:22:42Z

src/Symfony/Component/JsonPath/Functions/CountFunction.php

+ * @author Alexandre Daubois <alex.daubois@gmail.com>
+ */
+#[AsJsonPathFunction(name: 'count')]
+final class CountFunction extends AbstractJsonPathFunction implements JsonPathComparableFunctionInterface


should these core functions be tagged as @internal as the JsonCrawler is registering them on its own and so there is no reason for ever accessing them directly outside the component ?

stof · 2025-08-25T10:24:26Z

src/Symfony/Component/JsonPath/Functions/JsonPathFunctionArgumentTrait.php

+ */
+trait JsonPathFunctionArgumentTrait
+{
+    public static function assertArgumentsCount(array $args, int $expectedCount): void


The type of $args must be specified in phpdoc

stof · 2025-08-25T10:26:16Z

src/Symfony/Component/JsonPath/Tokenizer/JsonPathTokenizer.php

@@ -28,7 +27,7 @@ final class JsonPathTokenizer
    /**
     * @return JsonPathToken[]
     */
-    public static function tokenize(JsonPath $query): array
+    public static function tokenize(JsonPath $query, ?callable $functionValidator = null): array


I suggest documenting the signature of that callable. It will make it easier to contributors reading that code in the future (same in other methods where it is forwarded).

stof · 2025-08-25T10:26:55Z

src/Symfony/Component/JsonPath/Tokenizer/JsonPathTokenizer.php

+                try {
+                    $functionValidator($functionName, $args);
+                } catch (\InvalidArgumentException $e) {
+                    throw new InvalidJsonPathException($e->getMessage(), $position);


$e should be attached as previous exception.

stof · 2025-08-25T10:29:08Z

src/Symfony/Component/JsonPath/Functions/ValueFunction.php

+        }
+
+        $nodelistSize = \count($results);
+        if (1 < $nodelistSize) {


we could remove this check, using only return 1 === $nodelistSize ? $results[0] : null; for the same result.

[JsonPath] Make the component RFC compliant

88fc853

carsonbot added Status: Needs Review Feature FrameworkBundle JsonPath labels Aug 25, 2025

carsonbot added this to the 7.4 milestone Aug 25, 2025

alexandre-daubois force-pushed the jp-functions-provider branch 3 times, most recently from b5a68b4 to 42a26ef Compare August 25, 2025 09:26

[FrameworkBundle][JsonPath] Add support for custom JsonPath functions

1927fa4

alexandre-daubois force-pushed the jp-functions-provider branch from 42a26ef to 1927fa4 Compare August 25, 2025 09:27

stof reviewed Aug 25, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[FrameworkBundle][JsonPath] Add support for custom JsonPath functions #61517

[FrameworkBundle][JsonPath] Add support for custom JsonPath functions #61517

alexandre-daubois commented Aug 25, 2025 •

edited

Loading

Uh oh!

stof Aug 25, 2025

Uh oh!

stof Aug 25, 2025

Uh oh!

stof Aug 25, 2025

Uh oh!

stof Aug 25, 2025

Uh oh!

stof Aug 25, 2025

Uh oh!

stof Aug 25, 2025

Uh oh!

stof Aug 25, 2025

Uh oh!

stof Aug 25, 2025

Uh oh!

stof Aug 25, 2025

Uh oh!

stof Aug 25, 2025

Uh oh!

Uh oh!

Uh oh!

[FrameworkBundle][JsonPath] Add support for custom JsonPath functions #61517

Are you sure you want to change the base?

[FrameworkBundle][JsonPath] Add support for custom JsonPath functions #61517

Conversation

alexandre-daubois commented Aug 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alexandre-daubois commented Aug 25, 2025 •

edited

Loading