docs(json-path): initiate doc for the component

Author: vinceAmstoutz

components/json_path.rst

@@ -0,0 +1,154 @@
+The JsonPath Component
+======================
+
+.. versionadded:: 7.3
+    The JsonPath component was introduced in Symfony 7.3.
+
+The JsonPath component provides a powerful way to query and extract data from
+JSON structures. It implements the `RFC 9535 (JSONPath) <https://datatracker.ietf.org/doc/html/rfc9535>`_
+standard, allowing you to navigate complex JSON data with ease.
+
+Think of it as :doc:`the DomCrawler component </components/dom_crawler>`, but for JSON.
+
+Installation
+------------
+
+You can install the component in your project using Composer:
+
+.. code-block:: terminal
+
+    $ composer require symfony/json-path
+
+.. include:: /components/require_autoload.rst.inc
+
+Basic Usage
+-----------
+
+To start querying a JSON document, you first need to create a :class:`Symfony\\Component\\JsonPath\\JsonCrawler`
+object from a JSON string:
+
+.. code-block:: php
+
+    use Symfony\Component\JsonPath\JsonCrawler;
+
+    $json = <<<'JSON'
+    {
+        "store": {
+            "book": [
+                {
+                    "category": "reference",
+                    "author": "Nigel Rees",
+                    "title": "Sayings",
+                    "price": 8.95
+                },
+                {
+                    "category": "fiction",
+                    "author": "Evelyn Waugh",
+                    "title": "Sword",
+                    "price": 12.99
+                }
+            ]
+        }
+    }
+    JSON;
+
+    $crawler = new JsonCrawler($json);
+
+Once you have the crawler instance, you can use its ``find()`` method to start
+querying the data.
+
+Querying with Expressions
+-------------------------
+
+The primary way to query the JSON is by passing a JSONPath expression string
+to the ``find()`` method. This method always returns an array of matching values.
+
+**Accessing a Specific Property**
+
+Use dot-notation for object keys and square brackets for array indices. The root
+of the document is represented by ``$``.
+
+.. code-block:: php
+
+    // Get the title of the first book in the store
+    $titles = $crawler->find('$.store.book[0].title');
+
+    // $titles is ['Sayings']
+
+**Searching with the Descendant Operator**
+
+The descendant operator (``..``) recursively searches for a given key, allowing
+you to find values without specifying the full path.
+
+.. code-block:: php
+
+    // Get all authors from anywhere in the document
+    $authors = $crawler->find('$..author');
+
+    // $authors is ['Nigel Rees', 'Evelyn Waugh']
+
+**Filtering Results**
+
+JSONPath includes a powerful filter syntax (``?(<expression>)``) to select items
+based on a condition. The current item within the filter is referenced by ``@``.
+
+.. code-block:: php
+
+    // Get all books with a price less than 10
+    $cheapBooks = $crawler->find('$.store.book[?(@.price < 10)]');
+
+    /*
+    $cheapBooks contains:
+    [
+        [
+            "category" => "reference",
+            "author" => "Nigel Rees",
+            "title" => "Sayings",
+            "price" => 8.95,
+        ],
+    ]
+    */
+
+**Using Functions in Filters**
+
+The filter expressions also support a set of built-in functions, such as
+``length()``, ``count()``, and ``match()``.
+
+.. code-block:: php
+
+    // Get books where the author's name is longer than 11 characters
+    $result = $crawler->find('$.store.book[?length(@.author) > 11]');
+
+    // $result contains the book by "Evelyn Waugh"
+
+    // Get books where the author's name matches a regular expression
+    $result = $crawler->find('$.store.book[?match(@.author, "[A-Z].*el.+")]');
+
+    // $result contains the book by "Nigel Rees"
+
+
+Building Queries Programmatically
+-------------------------------
+
+For more dynamic or complex query building, you can use the fluent API provided
+by the :class:`Symfony\\Component\\JsonPath\\JsonPath` class. This allows you
+to construct a query object step-by-step:
+
+.. code-block:: php
+
+    use Symfony\Component\JsonPath\JsonPath;
+
+    $path = (new JsonPath())
+        ->key('store')
+        ->key('book')
+        ->index(0)
+        ->key('author');
+
+    // The created $path object is equivalent to the string '$.store.book[0].author'
+
+    $authors = $crawler->find($path);
+
+    // $authors is ['Nigel Rees']
+
+You can pass either the expression string or the ``JsonPath`` object to the
+``find()`` method.