feature KnpLabs#1031 adding code_with_match (KnpLabs#1024) (QuentinRa)

This PR was squashed before being merged into the 3.4.x-dev branch.

Discussion
----------

Hi! As described in KnpLabs#1024, I added a function `code_with_match`.

Commits
-------

32acac4 adding code_with_match (KnpLabs#1024)
179532a adding a new line
c3be951 changes requested
f89811e removing the whole phpdoc comment

Author: QuentinRa

doc/search.md

@@ -13,13 +13,19 @@ $repos = $client->api('search')->repositories('github language:php');
 Returns a list of repositories found by such criteria.
 
 ### Search code
- 
+
 ```php
 $files = $client->api('search')->code('@todo language:php');
 ```
 
 Returns a list of files found by such criteria (containing "@todo" and language==php).
 
+```php
+$files = $client->api('search')->codeWithMatch('@todo language:php');
+```
+
+Same as code, with additional data to highlight the matching fragments (see [Text match metadata](https://docs.github.com/en/rest/reference/search#text-match-metadata)).
+
 ### Search issues
 
 ```php

lib/Github/Api/Search.php

@@ -61,6 +61,21 @@ public function code($q, $sort = 'updated', $order = 'desc')
         return $this->get('/search/code', ['q' => $q, 'sort' => $sort, 'order' => $order]);
     }
 
+    /**
+     * Search code by filter (q), but will return additional data to highlight
+     * the matched results.
+     *
+     * @link https://docs.github.com/en/rest/reference/search#text-match-metadata
+     *
+     * @return array list of code found
+     */
+    public function codeWithMatch(string $q, string $sort = 'updated', string $order = 'desc'): array
+    {
+        $this->acceptHeaderValue = 'application/vnd.github.v3.text-match+json';
+
+        return $this->code($q, $sort, $order);
+    }
+
     /**
      * Search users by filter (q).
      *

test/Github/Tests/Api/SearchTest.php

@@ -133,6 +133,49 @@ public function shouldSearchCodeRegardingSortAndOrder()
         );
     }
 
+    /**
+     * @test
+     */
+    public function shouldSearchCodeWithMatchByQuery()
+    {
+        $expectedArray = [['total_count' => '0']];
+
+        $api = $this->getApiMock();
+
+        $api->expects($this->once())
+            ->method('get')
+            ->with(
+                '/search/code',
+                ['q' => 'query text', 'sort' => 'updated', 'order' => 'desc']
+            )
+            ->will($this->returnValue($expectedArray));
+
+        $this->assertEquals($expectedArray, $api->codeWithMatch('query text'));
+    }
+
+    /**
+     * @test
+     */
+    public function shouldSearchCodeWithMatchRegardingSortAndOrder()
+    {
+        $expectedArray = [['total_count' => '0']];
+
+        $api = $this->getApiMock();
+
+        $api->expects($this->once())
+            ->method('get')
+            ->with(
+                '/search/code',
+                ['q' => 'query text', 'sort' => 'created', 'order' => 'asc']
+            )
+            ->will($this->returnValue($expectedArray));
+
+        $this->assertEquals(
+            $expectedArray,
+            $api->codeWithMatch('query text', 'created', 'asc')
+        );
+    }
+
     /**
      * @test
      */