From 42d11a67db2eded6841fbadd6d241c533e11f39a Mon Sep 17 00:00:00 2001 From: armensanoyan Date: Wed, 3 Jun 2026 13:36:05 +0400 Subject: [PATCH 1/2] Add 'Get Sound By Id' functionality to SOUNDS_API and examples - Introduced a new method `getSoundById` in the ApiClient to retrieve a single sound by its ID. - Updated SOUNDS_API documentation to include the new endpoint. - Modified example scripts to demonstrate usage of the new method. - Removed unnecessary calls to fetch all sounds when retrieving a specific sound. --- doc/SOUNDS_API.md | 24 ++++++++++ examples/project-data/update-project-data.php | 3 +- examples/sounds/get-sound-by-id.php | 19 ++++++++ src/ApiClient.php | 48 +++++++++++++++++++ 4 files changed, 92 insertions(+), 2 deletions(-) create mode 100644 examples/sounds/get-sound-by-id.php diff --git a/doc/SOUNDS_API.md b/doc/SOUNDS_API.md index 71a660d..fd603c9 100644 --- a/doc/SOUNDS_API.md +++ b/doc/SOUNDS_API.md @@ -3,6 +3,7 @@ **For detailed usage please see examples for each method.** - [Get All Sounds](#get-all-sounds) +- [Get Sound By Id](#get-sound-by-id) - [Get Company's Library Sounds](#get-companys-library-sounds) - [Get Recommended Sounds](#get-recommended-sounds) @@ -28,6 +29,29 @@ $sounds = $renderforestClient->getAllSounds(15); [See get all sounds example](/examples/sounds/get-all-sounds.php) +### Get Sound By Id + +Retrieves a single library sound by its id (authorization is required). + +Resolves the sound directly by id, so — unlike fetching the whole list with +`getAllSounds` and looking the sound up locally — it is not affected by the +paginated sounds listing and works for any library sound id. + +```php +getSoundById(1980240); +``` + +[See get sound by id example](/examples/sounds/get-sound-by-id.php) + ### Get Company's Library Sounds Retrieves company's library sounds for given duration (authorization is not required). diff --git a/examples/project-data/update-project-data.php b/examples/project-data/update-project-data.php index 1b80a2b..0ffe830 100644 --- a/examples/project-data/update-project-data.php +++ b/examples/project-data/update-project-data.php @@ -15,8 +15,7 @@ ->setValue('https://sample-videos.com/video123/mp4/720/big_buck_bunny_720p_1mb.mp4'); // add sound -$allSounds = $renderforestClient->getAllSounds(100); -$sound = $allSounds->getSoundById(1980240); +$sound = $renderforestClient->getSoundById(1980240); $projectData ->getSounds() ->add($sound); diff --git a/examples/sounds/get-sound-by-id.php b/examples/sounds/get-sound-by-id.php new file mode 100644 index 0000000..b8d32a3 --- /dev/null +++ b/examples/sounds/get-sound-by-id.php @@ -0,0 +1,19 @@ +getSoundById($soundId); + +echo 'ID - ' . $sound->getId() . PHP_EOL; +echo 'Duration - ' . $sound->getDuration() . PHP_EOL; +echo 'Title - ' . $sound->getTitle() . PHP_EOL; +echo 'Path - ' . $sound->getPath() . PHP_EOL; +echo 'Low Quality Path - ' . $sound->getLowQuality() . PHP_EOL; +echo 'Genre - ' . $sound->getGenre() . PHP_EOL; diff --git a/src/ApiClient.php b/src/ApiClient.php index 3e22f30..9fc4f5f 100644 --- a/src/ApiClient.php +++ b/src/ApiClient.php @@ -10,6 +10,7 @@ use Renderforest\ProjectData\ProjectData; use Renderforest\ProjectData\Screen\Entity\Screen; use Renderforest\Sound\Collection\SoundCollection; +use Renderforest\Sound\Sound; use Renderforest\Support\SupportTicket; use Renderforest\Support\SupportTicketResponse; use Renderforest\Template\Category\Category; @@ -90,6 +91,9 @@ class ApiClient const SOUNDS_API_PATH_PREFIX = '/api/v1'; const SOUNDS_API_PATH = self::SOUNDS_API_PATH_PREFIX . '/sounds'; + const SOUND_BY_ID_API_PATH_PREFIX = '/api/v1'; + const SOUND_BY_ID_API_PATH = self::SOUND_BY_ID_API_PATH_PREFIX . '/sounds/%d'; + const COMPANY_SOUNDS_API_PATH_PREFIX = '/api/v1'; const COMPANY_SOUNDS_API_PATH = self::COMPANY_SOUNDS_API_PATH_PREFIX . '/sounds/library'; @@ -1033,6 +1037,50 @@ public function getAllSounds(int $duration = null): SoundCollection return $SoundCollection; } + /** + * Retrieves a single library sound by its id (authorization is required). + * + * Unlike `getAllSounds`, this resolves the sound directly by id, so it is + * not affected by the paginated sounds listing and works for any library + * sound id. + * + * @param int $soundId + * @return Sound + * @throws GuzzleException + */ + public function getSoundById(int $soundId): Sound + { + $endpoint = self::SOUNDS_API_PATH; + $uri = self::API_ENDPOINT . sprintf(self::SOUND_BY_ID_API_PATH, $soundId); + + $options = [ + 'method' => 'GET', + 'headers' => [ + 'Accept' => 'application/json', + 'User-Agent' => self::USER_AGENT, + ], + 'endpoint' => $endpoint, + 'uri' => $uri, + ]; + + $options = $this->setAuthorization($options); + + $response = $this->httpClient->request( + $options['method'], + $options['uri'], + $options + ); + + $json = $response->getBody()->getContents(); + + $soundArrayData = json_decode($json, true)['data']; + + $sound = new Sound(); + $sound->exchangeArray($soundArrayData); + + return $sound; + } + /** * @param int $duration * @return SoundCollection From 0b3babc1de86ae8508994e757945eb275280b9b3 Mon Sep 17 00:00:00 2001 From: armensanoyan Date: Fri, 5 Jun 2026 15:52:50 +0400 Subject: [PATCH 2/2] Enhance getAllSounds method to support pagination - Updated the `getAllSounds` method in ApiClient to accept `limit` and `offset` parameters for paginated results. - Improved documentation to reflect the new parameters and their usage. --- src/ApiClient.php | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/src/ApiClient.php b/src/ApiClient.php index 9fc4f5f..daabb6e 100644 --- a/src/ApiClient.php +++ b/src/ApiClient.php @@ -993,23 +993,39 @@ public function getTemplateAvailableFonts(int $templateId): FontCollection } /** + * Retrieves sounds (authorization is required). + * + * The sounds endpoint is paginated — pass `$limit` (1-50) and `$offset` to + * page through the results. + * * @param int $duration + * @param int $limit Number of sounds to return (1-50). + * @param int $offset Number of sounds to skip. * @return SoundCollection * @throws GuzzleException */ - public function getAllSounds(int $duration = null): SoundCollection + public function getAllSounds(int $duration = null, int $limit = null, int $offset = null): SoundCollection { $endpoint = self::SOUNDS_API_PATH; $uri = self::API_ENDPOINT . self::SOUNDS_API_PATH; + $queryParams = []; + if (false === is_null($duration)) { - $queryParams = [ - 'duration' => $duration, - ]; - - $queryString = http_build_query($queryParams); - $uri .= '?' . $queryString; - } + $queryParams['duration'] = $duration; + } + + if (false === is_null($limit)) { + $queryParams['limit'] = $limit; + } + + if (false === is_null($offset)) { + $queryParams['offset'] = $offset; + } + + if (count($queryParams) > 0) { + $uri .= '?' . http_build_query($queryParams); + } $options = [ 'method' => 'GET',