introducing OcUtils utility class,

fixes #33

Author: ferishili

CHANGELOG.md

@@ -53,3 +53,5 @@
 
 # 1.9.0
 - Allow passing additonal options to Guzzle #30
+- Added `OcUtils` class, a utility class providing additional functionality to simplify the integration and consumption of this library.
+  - Initially includes the `findValueByKey` function, which is meant to retrieve a specific value from the response body. [#33]

README.md

@@ -301,6 +301,26 @@ $baseResponse = $ocBaseApi->setRequestConnectionTimeout(10)->get();
 
 - `/sysinfo/bundles/version`: (v1.1.1) only bundle version endpoint is available. [Sysinfo Endpoint definitions WiKi](https://github.com/elan-ev/opencast-php-library/wiki/OcSysinfo)
 
+# Utility Class
+Starting from version **v1.9.0**, a new utility class has been introduced to provide additional functionality, making it easier to integrate and consume this library's output within applications.
+## How to use
+To use the utility class, initialize it directly via its namespace and start calling its functions:
+```php
+use OpencastApi\Opencast;
+use OpencastApi\Util\OcUtils;
+...
+$config = [...];
+$opencastApi = new Opencast($config);
+
+$params = [...];
+$response = $opencastApi->ocSearch->getEpisodes($params);
+
+// Use `findValueByKey` from the Utility class to extract the mediapackage from the response,
+// regardless of the response's structure.
+$mediapackage = OcUtils::findValueByKey($response['body'], 'mediapackage');
+...
+```
+
 # Mocking Responses
 In order to conduct proper testing, a mocking mechanism is provided.
 ## How to use

src/OpencastApi/Util/OcUtils.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace OpencastApi\Util;
+
+/**
+ * Opencast API Utility class.
+ *
+ * This class provides additional functionality to simplify the integration and consumption of this library's output within applications.
+ */
+class OcUtils
+{
+    /**
+     * This function searches for a specific key in a given object or array, including nested structures.
+     *
+     * @param object|array $object The object or array to search in.
+     * @param string $targetKey The key to search for.
+     *
+     * @return mixed|null The value of the found key, or null if the key is not found.
+     */
+    public static function findValueByKey(object|array $object, string $targetKey) {
+        if (is_object($object)) {
+            // Perform first-level type casting,
+            // to preserve the data types of child elements.
+            $object = (array) $object;
+        }
+
+        foreach ($object as $key => $value) {
+            if ($key === $targetKey) {
+                return $value;
+            } elseif (is_array($value) || is_object($value)) {
+                // Recursively search in nested structures.
+                $found = self::findValueByKey($value, $targetKey);
+                if ($found !== null) {
+                    return $found;
+                }
+            }
+        }
+
+        return null;
+    }
+}

tests/DataProvider/SearchDataProvider.php

@@ -7,7 +7,7 @@ public static function getEpisodeQueryCases(): array
     {
         return [
             [[], 'json'],
-            [['id' => 'fe0b45b0-7ed5-4944-8b0a-a0a283331791'], ''],
+            [['id' => 'ID-spring'], ''],
             [['sid' => '8010876e-1dce-4d38-ab8d-24b956e3d8b7'], ''],
             [['sname' => 'HUB_LOCAL_TEST'], ''],
             [['sort' => 'modified asc'], ''],
@@ -47,4 +47,4 @@ public static function getSeriesQueryCases(): array
         ];
     }
 }
-?>
+?>

tests/Unit/OcSearchTest.php

@@ -5,6 +5,7 @@
 
 use PHPUnit\Framework\TestCase;
 use OpencastApi\Opencast;
+use OpencastApi\Util\OcUtils;
 
 class OcSearchTest extends TestCase
 {
@@ -26,6 +27,17 @@ public function get_eposides($params, $format): void
         $this->assertSame(200, $response['code'], 'Failure to search episode');
     }
 
+    /**
+     * @test
+     */
+    public function find_mediapackage_using_ocutils() {
+        $params = ['id' => 'ID-spring'];
+        $response = $this->ocSearch->getEpisodes($params);
+        $this->assertSame(200, $response['code'], 'Failure to search episode for OcUtils');
+        $mediapackage = OcUtils::findValueByKey($response['body'], 'mediapackage');
+        $this->assertNotEmpty($mediapackage, 'Cannot extract mediapackage from response using "OcUtils::findValueByKey"');
+    }
+
     /**
      * @test
      * @dataProvider \Tests\DataProvider\SearchDataProvider::getSeriesQueryCases()