Allow to pass options to info providers

jbtronics · jbtronics · commit 4f67f21b33a6 · 2026-04-27T22:37:05.000+02:00
diff --git a/src/Services/InfoProviderSystem/Providers/AIInfoExtractor.php b/src/Services/InfoProviderSystem/Providers/AIInfoExtractor.php
@@ -86,7 +86,7 @@ public function isActive(): bool
         return $this->settings->platform !== null && $this->settings->model !== null && $this->settings->model !== '';
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         try {
             return [
@@ -96,7 +96,7 @@ public function searchByKeyword(string $keyword): array
         }
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         $url = $this->fixAndValidateURL($id);
 
diff --git a/src/Services/InfoProviderSystem/Providers/BatchInfoProviderInterface.php b/src/Services/InfoProviderSystem/Providers/BatchInfoProviderInterface.php
@@ -34,7 +34,8 @@ interface BatchInfoProviderInterface extends InfoProviderInterface
      * Search for multiple keywords in a single batch operation and return the results, ordered by the keywords.
      * This allows for a more efficient search compared to running multiple single searches.
      * @param  string[]  $keywords
+     * @param  array<string, mixed>  $options An associative array of options which can be used to modify the search behavior. The supported options depend on the provider and should be documented in the provider's documentation.
      * @return array<string, SearchResultDTO[]> An associative array where the key is the keyword and the value is the search results for that keyword
      */
-    public function searchByKeywordsBatch(array $keywords): array;
+    public function searchByKeywordsBatch(array $keywords, array $options = []): array;
 }
diff --git a/src/Services/InfoProviderSystem/Providers/BuerklinProvider.php b/src/Services/InfoProviderSystem/Providers/BuerklinProvider.php
@@ -461,9 +461,11 @@ private function attributesToParameters(array $features, ?string $group = null):
     }
 
     /**
+     * @param  string  $keyword
+     * @param  array  $options
      * @return PartDetailDTO[]
      */
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         $keyword = strtoupper(trim($keyword));
         if ($keyword === '') {
@@ -493,7 +495,7 @@ public function searchByKeyword(string $keyword): array
         }
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         // Detail endpoint is /products/{code}/
         $response = $this->getProduct($id);
@@ -588,10 +590,11 @@ private function complianceToParameters(array $product, ?string $group = 'Compli
     }
 
     /**
-     * @param string[] $keywords
+     * @param  array  $keywords
+     * @param  array  $options
      * @return array<string, SearchResultDTO[]>
      */
-    public function searchByKeywordsBatch(array $keywords): array
+    public function searchByKeywordsBatch(array $keywords, array $options = []): array
     {
         /** @var array<string, SearchResultDTO[]> $results */
         $results = [];
@@ -643,27 +646,27 @@ public function getHandledDomains(): array
 
     public function getIDFromURL(string $url): ?string
     {
-        //Inputs: 
-        //https://www.buerklin.com/de/p/bkl-electronic/niedervoltsteckverbinder/072341-l/40F1332/ 
+        //Inputs:
+        //https://www.buerklin.com/de/p/bkl-electronic/niedervoltsteckverbinder/072341-l/40F1332/
         //https://www.buerklin.com/de/p/40F1332/
         //https://www.buerklin.com/en/p/bkl-electronic/dc-connectors/072341-l/40F1332/
         //https://www.buerklin.com/en/p/40F1332/
         //The ID is the last part after the manufacturer/category/mpn segment and before the final slash
         //https://www.buerklin.com/de/p/bkl-electronic/niedervoltsteckverbinder/072341-l/40F1332/#download should also work
-        
+
         $path = parse_url($url, PHP_URL_PATH);
-    
+
         if (!$path) {
             return null;
         }
-    
+
         // Ensure it's actually a product URL
         if (strpos($path, '/p/') === false) {
             return null;
         }
-    
+
         $id = basename(rtrim($path, '/'));
-    
+
         return $id !== '' && $id !== 'p' ? $id : null;
     }
 
diff --git a/src/Services/InfoProviderSystem/Providers/CanopyProvider.php b/src/Services/InfoProviderSystem/Providers/CanopyProvider.php
@@ -111,7 +111,7 @@ private function getFromCache(string $id): ?PartDetailDTO
         return null;
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         $response = $this->httpClient->request('GET', self::SEARCH_API_URL, [
             'query' => [
@@ -177,7 +177,7 @@ private function priceToPurchaseInfo(?array $price, string $asin): PurchaseInfoD
         return new PurchaseInfoDTO(self::DISTRIBUTOR_NAME, order_number: $asin, prices: $priceDtos, product_url: $this->productPageFromASIN($asin));
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         //Check that the id is a valid ASIN (10 characters, letters and numbers)
         if (!preg_match('/^[A-Z0-9]{10}$/', $id)) {
diff --git a/src/Services/InfoProviderSystem/Providers/ConradProvider.php b/src/Services/InfoProviderSystem/Providers/ConradProvider.php
@@ -88,7 +88,7 @@ private function getFootprintFromTechnicalDetails(array $technicalDetails): ?str
         return null;
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         $url = $this->settings->shopID->getAPIRoot() . self::SEARCH_ENDPOINT . '/'
             . $this->settings->shopID->getDomainEnd() . '/' . $this->settings->shopID->getLanguage()
@@ -279,7 +279,7 @@ private function queryPrices(string $productId): PurchaseInfoDTO
         );
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         $productInfoURL = $this->settings->shopID->getAPIRoot() . '/product/1/service/' . $this->settings->shopID->getShopID()
             . '/product/' . $id;
diff --git a/src/Services/InfoProviderSystem/Providers/DigikeyProvider.php b/src/Services/InfoProviderSystem/Providers/DigikeyProvider.php
@@ -106,7 +106,7 @@ public function isActive(): bool
         return $this->settings->clientId !== null && $this->settings->clientId !== '' && $this->authTokenManager->hasToken(self::OAUTH_APP_NAME);
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         $request = [
             'Keywords' => $keyword,
@@ -159,7 +159,7 @@ public function searchByKeyword(string $keyword): array
         return $result;
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         try {
             $response = $this->digikeyClient->request('GET', '/products/v4/search/' . urlencode($id) . '/productdetails', [
diff --git a/src/Services/InfoProviderSystem/Providers/Element14Provider.php b/src/Services/InfoProviderSystem/Providers/Element14Provider.php
@@ -282,12 +282,12 @@ private function releaseStatusCodeToManufacturingStatus(?int $releaseStatusCode)
         };
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         return $this->queryByTerm('any:' . $keyword);
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         $tmp = $this->queryByTerm('id:' . $id);
         if (count($tmp) === 0) {
diff --git a/src/Services/InfoProviderSystem/Providers/EmptyProvider.php b/src/Services/InfoProviderSystem/Providers/EmptyProvider.php
@@ -54,7 +54,7 @@ public function isActive(): bool
         return true;
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         return [
 
@@ -69,7 +69,7 @@ public function getCapabilities(): array
         ];
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         throw new \RuntimeException('No part details available');
     }
diff --git a/src/Services/InfoProviderSystem/Providers/GenericWebProvider.php b/src/Services/InfoProviderSystem/Providers/GenericWebProvider.php
@@ -87,7 +87,7 @@ public function isActive(): bool
         return $this->settings->enabled;
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         $url = $this->fixAndValidateURL($keyword);
 
diff --git a/src/Services/InfoProviderSystem/Providers/InfoProviderInterface.php b/src/Services/InfoProviderSystem/Providers/InfoProviderInterface.php
@@ -61,16 +61,18 @@ public function isActive(): bool;
     /**
      * Searches for a keyword and returns a list of search results
      * @param  string  $keyword The keyword to search for
+     * @param  array   $options  An associative array of options for the search, which can be used to pass additional parameters to the provider (e.g. filters, pagination, etc.). The content of this array is provider specific and not defined by the interface
      * @return SearchResultDTO[] A list of search results
      */
-    public function searchByKeyword(string $keyword): array;
+    public function searchByKeyword(string $keyword, array $options = []): array;
 
     /**
      * Returns detailed information about the part with the given id
      * @param  string  $id
+     * @param  array   $options  An associative array of options for the search, which can be used to pass additional parameters to the provider (e.g. filters, pagination, etc.). The content of this array is provider specific and not defined by the interface
      * @return PartDetailDTO
      */
-    public function getDetails(string $id): PartDetailDTO;
+    public function getDetails(string $id, array $options = []): PartDetailDTO;
 
     /**
      * A list of capabilities this provider supports (which kind of data it can provide).
diff --git a/src/Services/InfoProviderSystem/Providers/LCSCProvider.php b/src/Services/InfoProviderSystem/Providers/LCSCProvider.php
@@ -349,17 +349,18 @@ private function attributesToParameters(?array $attributes): array
         return $result;
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         return $this->queryByTerm($keyword, true); // Use lightweight mode for search
     }
 
     /**
      * Batch search multiple keywords asynchronously (like JavaScript Promise.all)
-     * @param array $keywords Array of keywords to search
+     * @param  array  $keywords
+     * @param  array  $options
      * @return array Results indexed by keyword
      */
-    public function searchByKeywordsBatch(array $keywords): array
+    public function searchByKeywordsBatch(array $keywords, array $options = []): array
     {
         if (empty($keywords)) {
             return [];
@@ -428,7 +429,7 @@ private function processSearchResponse(array $arr, string $keyword): array
         return $result;
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         $tmp = $this->queryByTerm($id, false);
         if (count($tmp) === 0) {
diff --git a/src/Services/InfoProviderSystem/Providers/OEMSecretsProvider.php b/src/Services/InfoProviderSystem/Providers/OEMSecretsProvider.php
@@ -278,12 +278,13 @@ public function isActive(): bool
      * and debugging with local JSON files. The results are processed, cached, and then sorted based
      * on the keyword and specified criteria.
      *
-     * @param  string  $keyword The part number to search for
+     * @param  string  $keyword
+     * @param  array  $options
      * @return array An array of processed product details, sorted by relevance and additional criteria.
      *
      * @throws \Exception If the JSON file used for debugging is not found or contains errors.
      */
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         /*
         oemsecrets Part Search API  3.0.1
@@ -414,12 +415,13 @@ private function getCacheKey(string $provider_id): string {
      * found in the cache, they are returned. If not, an exception is thrown indicating that
      * the details could not be found.
      *
-     * @param string $id The unique identifier of the provider or part.
+     * @param  string  $id
+     * @param  array  $options
      * @return PartDetailDTO The detailed information about the part.
      *
      * @throws \Exception If no details are found for the given provider ID.
      */
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         $cacheKey = $this->getCacheKey($id);
         $cacheItem = $this->partInfoCache->getItem($cacheKey);
diff --git a/src/Services/InfoProviderSystem/Providers/OctopartProvider.php b/src/Services/InfoProviderSystem/Providers/OctopartProvider.php
@@ -326,7 +326,7 @@ private function partResultToDTO(array $part): PartDetailDTO
         );
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         $graphQL = sprintf(<<<'GRAPHQL'
             query partSearch($keyword: String, $limit: Int, $currency: String!, $country: String!, $authorizedOnly: Boolean!) {
@@ -367,7 +367,7 @@ public function searchByKeyword(string $keyword): array
         return $tmp;
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         //Check if we have the part cached
         $cached = $this->getFromCache($id);
diff --git a/src/Services/InfoProviderSystem/Providers/PollinProvider.php b/src/Services/InfoProviderSystem/Providers/PollinProvider.php
@@ -66,7 +66,7 @@ public function isActive(): bool
         return $this->settings->enabled;
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         $response = $this->client->request('GET', 'https://www.pollin.de/search', [
             'query' => [
@@ -110,7 +110,7 @@ private function mapAvailability(string $availabilityURI): ManufacturingStatus
         };
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         //Ensure that $id is numeric
         if (!is_numeric($id)) {
diff --git a/src/Services/InfoProviderSystem/Providers/ReicheltProvider.php b/src/Services/InfoProviderSystem/Providers/ReicheltProvider.php
@@ -69,7 +69,7 @@ public function isActive(): bool
         return $this->settings->enabled;
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         $response = $this->client->request('GET', sprintf($this->getBaseURL() . '/shop/search/%s', $keyword));
         $html = $response->getContent();
@@ -108,7 +108,7 @@ public function searchByKeyword(string $keyword): array
         return $results;
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         //Check that the ID is a number
         if (!is_numeric($id)) {
diff --git a/src/Services/InfoProviderSystem/Providers/TMEProvider.php b/src/Services/InfoProviderSystem/Providers/TMEProvider.php
@@ -69,7 +69,7 @@ public function isActive(): bool
         return $this->tmeClient->isUsable();
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         $response = $this->tmeClient->makeRequest('Products/Search', [
             'Country' => $this->settings->country,
@@ -99,7 +99,7 @@ public function searchByKeyword(string $keyword): array
         return $result;
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         $response = $this->tmeClient->makeRequest('Products/GetProducts', [
             'Country' => $this->settings->country,
diff --git a/src/Services/InfoProviderSystem/Providers/TestProvider.php b/src/Services/InfoProviderSystem/Providers/TestProvider.php
@@ -55,7 +55,7 @@ public function isActive(): bool
         return true;
     }
 
-    public function searchByKeyword(string $keyword): array
+    public function searchByKeyword(string $keyword, array $options = []): array
     {
         return [
             new SearchResultDTO(provider_key: $this->getProviderKey(), provider_id: 'element1', name: 'Element 1', description: 'fd'),
@@ -72,7 +72,7 @@ public function getCapabilities(): array
         ];
     }
 
-    public function getDetails(string $id): PartDetailDTO
+    public function getDetails(string $id, array $options = []): PartDetailDTO
     {
         return new PartDetailDTO(
             provider_key: $this->getProviderKey(),
@@ -92,4 +92,4 @@ public function getDetails(string $id): PartDetailDTO
             ]
         );
     }
-}
+}

Original file line number	Diff line number	Diff line change
`@@ -86,7 +86,7 @@ public function isActive(): bool`
`86`	`86`	`return $this->settings->platform !== null && $this->settings->model !== null && $this->settings->model !== '';`
`87`	`87`	`}`
`88`	`88`
`89`		`- public function searchByKeyword(string $keyword): array`
	`89`	`+ public function searchByKeyword(string $keyword, array $options = []): array`
`90`	`90`	`{`
`91`	`91`	`try {`
`92`	`92`	`return [`
`@@ -96,7 +96,7 @@ public function searchByKeyword(string $keyword): array`
`96`	`96`	`}`
`97`	`97`	`}`
`98`	`98`
`99`		`- public function getDetails(string $id): PartDetailDTO`
	`99`	`+ public function getDetails(string $id, array $options = []): PartDetailDTO`
`100`	`100`	`{`
`101`	`101`	`$url = $this->fixAndValidateURL($id);`
`102`	`102`
Original file line number	Diff line number	Diff line change
`@@ -111,7 +111,7 @@ private function getFromCache(string $id): ?PartDetailDTO`
`111`	`111`	`return null;`
`112`	`112`	`}`
`113`	`113`
`114`		`- public function searchByKeyword(string $keyword): array`
	`114`	`+ public function searchByKeyword(string $keyword, array $options = []): array`
`115`	`115`	`{`
`116`	`116`	`$response = $this->httpClient->request('GET', self::SEARCH_API_URL, [`
`117`	`117`	`'query' => [`
`@@ -177,7 +177,7 @@ private function priceToPurchaseInfo(?array $price, string $asin): PurchaseInfoD`
`177`	`177`	`return new PurchaseInfoDTO(self::DISTRIBUTOR_NAME, order_number: $asin, prices: $priceDtos, product_url: $this->productPageFromASIN($asin));`
`178`	`178`	`}`
`179`	`179`
`180`		`- public function getDetails(string $id): PartDetailDTO`
	`180`	`+ public function getDetails(string $id, array $options = []): PartDetailDTO`
`181`	`181`	`{`
`182`	`182`	`//Check that the id is a valid ASIN (10 characters, letters and numbers)`
`183`	`183`	`if (!preg_match('/^[A-Z0-9]{10}$/', $id)) {`
Original file line number	Diff line number	Diff line change
`@@ -88,7 +88,7 @@ private function getFootprintFromTechnicalDetails(array $technicalDetails): ?str`
`88`	`88`	`return null;`
`89`	`89`	`}`
`90`	`90`
`91`		`- public function searchByKeyword(string $keyword): array`
	`91`	`+ public function searchByKeyword(string $keyword, array $options = []): array`
`92`	`92`	`{`
`93`	`93`	`$url = $this->settings->shopID->getAPIRoot() . self::SEARCH_ENDPOINT . '/'`
`94`	`94`	`. $this->settings->shopID->getDomainEnd() . '/' . $this->settings->shopID->getLanguage()`
`@@ -279,7 +279,7 @@ private function queryPrices(string $productId): PurchaseInfoDTO`
`279`	`279`	`);`
`280`	`280`	`}`
`281`	`281`
`282`		`- public function getDetails(string $id): PartDetailDTO`
	`282`	`+ public function getDetails(string $id, array $options = []): PartDetailDTO`
`283`	`283`	`{`
`284`	`284`	`$productInfoURL = $this->settings->shopID->getAPIRoot() . '/product/1/service/' . $this->settings->shopID->getShopID()`
`285`	`285`	`. '/product/' . $id;`
Original file line number	Diff line number	Diff line change
`@@ -106,7 +106,7 @@ public function isActive(): bool`
`106`	`106`	`return $this->settings->clientId !== null && $this->settings->clientId !== '' && $this->authTokenManager->hasToken(self::OAUTH_APP_NAME);`
`107`	`107`	`}`
`108`	`108`
`109`		`- public function searchByKeyword(string $keyword): array`
	`109`	`+ public function searchByKeyword(string $keyword, array $options = []): array`
`110`	`110`	`{`
`111`	`111`	`$request = [`
`112`	`112`	`'Keywords' => $keyword,`
`@@ -159,7 +159,7 @@ public function searchByKeyword(string $keyword): array`
`159`	`159`	`return $result;`
`160`	`160`	`}`
`161`	`161`
`162`		`- public function getDetails(string $id): PartDetailDTO`
	`162`	`+ public function getDetails(string $id, array $options = []): PartDetailDTO`
`163`	`163`	`{`
`164`	`164`	`try {`
`165`	`165`	`$response = $this->digikeyClient->request('GET', '/products/v4/search/' . urlencode($id) . '/productdetails', [`
Original file line number	Diff line number	Diff line change
`@@ -282,12 +282,12 @@ private function releaseStatusCodeToManufacturingStatus(?int $releaseStatusCode)`
`282`	`282`	`};`
`283`	`283`	`}`
`284`	`284`
`285`		`- public function searchByKeyword(string $keyword): array`
	`285`	`+ public function searchByKeyword(string $keyword, array $options = []): array`
`286`	`286`	`{`
`287`	`287`	`return $this->queryByTerm('any:' . $keyword);`
`288`	`288`	`}`
`289`	`289`
`290`		`- public function getDetails(string $id): PartDetailDTO`
	`290`	`+ public function getDetails(string $id, array $options = []): PartDetailDTO`
`291`	`291`	`{`
`292`	`292`	`$tmp = $this->queryByTerm('id:' . $id);`
`293`	`293`	`if (count($tmp) === 0) {`
Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,7 @@ public function isActive(): bool`
`54`	`54`	`return true;`
`55`	`55`	`}`
`56`	`56`
`57`		`- public function searchByKeyword(string $keyword): array`
	`57`	`+ public function searchByKeyword(string $keyword, array $options = []): array`
`58`	`58`	`{`
`59`	`59`	`return [`
`60`	`60`
`@@ -69,7 +69,7 @@ public function getCapabilities(): array`
`69`	`69`	`];`
`70`	`70`	`}`
`71`	`71`
`72`		`- public function getDetails(string $id): PartDetailDTO`
	`72`	`+ public function getDetails(string $id, array $options = []): PartDetailDTO`
`73`	`73`	`{`
`74`	`74`	`throw new \RuntimeException('No part details available');`
`75`	`75`	`}`
Original file line number	Diff line number	Diff line change
`@@ -87,7 +87,7 @@ public function isActive(): bool`
`87`	`87`	`return $this->settings->enabled;`
`88`	`88`	`}`
`89`	`89`
`90`		`- public function searchByKeyword(string $keyword): array`
	`90`	`+ public function searchByKeyword(string $keyword, array $options = []): array`
`91`	`91`	`{`
`92`	`92`	`$url = $this->fixAndValidateURL($keyword);`
`93`	`93`