groove/Part-DB-server
1
0
Fork 0
mirror of https://github.com/Part-DB/Part-DB-server.git synced 2026-01-12 21:29:33 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Create BuerklinProvider based on LCSCProvider

Browse source
This commit is contained in:
Marc Kreidler 2025-02-21 09:32:54 +01:00
parent c2e346ca1a
commit a57d46d57b
3 changed files with 386 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1
.docker/symfony.conf
View file

@ -46,6 +46,7 @@
PassEnv PROVIDER_OEMSECRETS_KEY PROVIDER_OEMSECRETS_COUNTRY_CODE PROVIDER_OEMSECRETS_CURRENCY PROVIDER_OEMSECRETS_ZERO_PRICE PROVIDER_OEMSECRETS_SET_PARAM PROVIDER_OEMSECRETS_SORT_CRITERIA
PassEnv PROVIDER_REICHELT_ENABLED PROVIDER_REICHELT_CURRENCY PROVIDER_REICHELT_COUNTRY PROVIDER_REICHELT_LANGUAGE PROVIDER_REICHELT_INCLUDE_VAT
PassEnv PROVIDER_POLLIN_ENABLED
PassEnv PROVIDER_BUERKLIN_CLIENT_ID PROVIDER_BUERKLIN_SECRET PROVIDER_BUERKLIN_USERNAME PROVIDER_BUERKLIN_PASSWORD PROVIDER_BUERKLIN_CURRENCY PROVIDER_BUERKLIN_LANGUAGE
PassEnv EDA_KICAD_CATEGORY_DEPTH
# For most configuration files from conf-available/, which are

19
docs/usage/information_provider_system.md
View file

@ -255,6 +255,25 @@ This is not an official API and could break at any time. So use it at your own r
The following env configuration options are available:
* `PROVIDER_POLLIN_ENABLED`: Set this to `1` to enable the Pollin provider
### Buerklin
The Buerklin provider uses the [Buerklin API](https://www.buerklin.com/en/services/eprocurement/) to search for parts and get information.
To use it you have to request access to the API.
You will get an e-mail with the client ID and client secret, which you have to put in the Part-DB env configuration (see below).
Please note that the Buerklin API is limited to 100 requests/minute per IP address and
access to the Authentication server is limited to 10 requests/minute per IP address
The following env configuration options are available:
* `PROVIDER_BUERKLIN_CLIENT_ID`: The client ID you got from Buerklin (mandatory)
* `PROVIDER_BUERKLIN_SECRET`: The client secret you got from Buerklin (mandatory)
* `PROVIDER_BUERKLIN_USERNAME`: The username you got from Buerklin (mandatory)
* `PROVIDER_BUERKLIN_PASSWORD`: The password you got from Buerklin (mandatory)
* `PROVIDER_BUERKLIN_CURRENCY`: The currency you want to get prices in if available (optional, 3 letter ISO-code,
default: `EUR`).
* `PROVIDER_BUERKLIN_LANGUAGE`: The language you want to get the descriptions in. Possible values: `de` = German, `en` = English. (optional, default: `de`)
### Custom provider
To create a custom provider, you have to create a new class implementing the `InfoProviderInterface` interface. As long

366
src/Services/InfoProviderSystem/Providers/BuerklinProvider.php Normal file
View file

@ -0,0 +1,366 @@
<?php
/*
* This file is part of Part-DB (https://github.com/Part-DB/Part-DB-symfony).
*
* Copyright (C) 2019 - 2023 Jan Böhmer (https://github.com/jbtronics)
* Copyright (C) 2025 Marc Kreidler (https://github.com/mkne)
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as published
* by the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
namespace App\Services\InfoProviderSystem\Providers;
use App\Services\InfoProviderSystem\DTOs\FileDTO;
use App\Services\InfoProviderSystem\DTOs\ParameterDTO;
use App\Services\InfoProviderSystem\DTOs\PartDetailDTO;
use App\Services\InfoProviderSystem\DTOs\PriceDTO;
use App\Services\InfoProviderSystem\DTOs\PurchaseInfoDTO;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Contracts\HttpClient\HttpClientInterface;
class BuerklinProvider implements InfoProviderInterface
{
private const ENDPOINT_URL = 'https://buerklin.com/buerklinws/v2/buerklin/';
public const DISTRIBUTOR_NAME = 'Buerklin';
public function __construct(private readonly HttpClientInterface $buerklinClient, private readonly string $currency, private readonly bool $enabled = true)
{
}
public function getProviderInfo(): array
{
return [
'name' => 'Buerklin',
'description' => 'This provider uses the Buerklin API to search for parts.',
'url' => 'https://www.buerklin.com/',
'disabled_help' => 'Set PROVIDER_BUERKLIN_ENABLED to 1 (or true) in your environment variable config.'
];
}
public function getProviderKey(): string
{
return 'buerklin';
}
// This provider is always active
public function isActive(): bool
{
return $this->enabled;
}
/**
* @param string $id
* @return PartDetailDTO
*/
private function queryDetail(string $id): PartDetailDTO
{
$response = $this->buerklinClient->request('GET', self::ENDPOINT_URL . "/products", [
'headers' => [
'Cookie' => new Cookie('currencyCode', $this->currency)
],
'query' => [
'sku' => $id,
],
]);
$arr = $response->toArray();
$product = $arr['result'] ?? null;
if ($product === null) {
throw new \RuntimeException('Could not find product code: ' . $id);
}
return $this->getPartDetail($product);
}
/**
* @param string $url
* @return String
*/
private function getRealDatasheetUrl(?string $url): string
{
if ($url !== null && trim($url) !== '' && preg_match("/^https:\/\/(datasheet\.buerklin\.com|www\.buerklin\.com\/datasheet)\/.*(C\d+)\.pdf$/", $url, $matches) > 0) {
if (preg_match("/^https:\/\/datasheet\.buerklin\.com\/buerklin\/(.*\.pdf)$/", $url, $rewriteMatches) > 0) {
$url = 'https://www.buerklin.com/datasheet/buerklin_datasheet_' . $rewriteMatches[1];
}
$response = $this->buerklinClient->request('GET', $url, [
'headers' => [
'Referer' => 'https://www.buerklin.com/product-detail/_' . $matches[2] . '.html'
],
]);
if (preg_match('/(previewPdfUrl): ?("[^"]+wmsc\.buerklin\.com[^"]+\.pdf")/', $response->getContent(), $matches) > 0) {
//HACKY: The URL string contains escaped characters like \u002F, etc. To decode it, the JSON decoding is reused
//See https://github.com/Part-DB/Part-DB-server/pull/582#issuecomment-2033125934
$jsonObj = json_decode('{"' . $matches[1] . '": ' . $matches[2] . '}');
$url = $jsonObj->previewPdfUrl;
}
}
return $url;
}
/**
* @param string $term
* @return PartDetailDTO[]
*/
private function queryByTerm(string $term): array
{
$response = $this->buerklinClient->request('GET', self::ENDPOINT_URL . "/search/global", [
'headers' => [
'Cookie' => new Cookie('currencyCode', $this->currency)
],
'query' => [
'keyword' => $term,
],
]);
$arr = $response->toArray();
// Get products list
$products = $arr['result']['productSearchResultVO']['productList'] ?? [];
// Get product tip
$tipProductCode = $arr['result']['tipProductDetailUrlVO']['productCode'] ?? null;
$result = [];
// Buerklin does not display Buerklin codes in the search, instead taking you directly to the
// detailed product listing. It does so utilizing a product tip field.
// If product tip exists and there are no products in the product list try a detail query
if (count($products) === 0 && $tipProductCode !== null) {
$result[] = $this->queryDetail($tipProductCode);
}
foreach ($products as $product) {
$result[] = $this->getPartDetail($product);
}
return $result;
}
/**
* Sanitizes a field by removing any HTML tags and other unwanted characters
* @param string|null $field
* @return string|null
*/
private function sanitizeField(?string $field): ?string
{
if ($field === null) {
return null;
}
return strip_tags($field);
}
/**
* Takes a deserialized json object of the product and returns a PartDetailDTO
* @param array $product
* @return PartDetailDTO
*/
private function getPartDetail(array $product): PartDetailDTO
{
// Get product images in advance
$product_images = $this->getProductImages($product['productImages'] ?? null);
$product['productImageUrl'] ??= null;
// If the product does not have a product image but otherwise has attached images, use the first one.
if (count($product_images) > 0) {
$product['productImageUrl'] ??= $product_images[0]->url;
}
// Buerklin puts HTML in footprints and descriptions sometimes randomly
$footprint = $product["encapStandard"] ?? null;
//If the footprint just consists of a dash, we'll assume it's empty
if ($footprint === '-') {
$footprint = null;
}
//Build category by concatenating the catalogName and parentCatalogName
$category = $product['parentCatalogName'] ?? null;
if (isset($product['catalogName'])) {
$category = ($category ?? '') . ' -> ' . $product['catalogName'];
// Replace the / with a -> for better readability
$category = str_replace('/', ' -> ', $category);
}
return new PartDetailDTO(
provider_key: $this->getProviderKey(),
provider_id: $product['productCode'],
name: $product['productModel'],
description: $this->sanitizeField($product['productIntroEn']),
category: $this->sanitizeField($category ?? null),
manufacturer: $this->sanitizeField($product['brandNameEn'] ?? null),
mpn: $this->sanitizeField($product['productModel'] ?? null),
preview_image_url: $product['productImageUrl'],
manufacturing_status: null,
provider_url: $this->getProductShortURL($product['productCode']),
footprint: $this->sanitizeField($footprint),
datasheets: $this->getProductDatasheets($product['pdfUrl'] ?? null),
images: $product_images,
parameters: $this->attributesToParameters($product['paramVOList'] ?? []),
vendor_infos: $this->pricesToVendorInfo($product['productCode'], $this->getProductShortURL($product['productCode']), $product['productPriceList'] ?? []),
mass: $product['weight'] ?? null,
);
}
/**
* Converts the price array to a VendorInfoDTO array to be used in the PartDetailDTO
* @param string $sku
* @param string $url
* @param array $prices
* @return array
*/
private function pricesToVendorInfo(string $sku, string $url, array $prices): array
{
$price_dtos = [];
foreach ($prices as $price) {
$price_dtos[] = new PriceDTO(
minimum_discount_amount: $price['ladder'],
price: $price['productPrice'],
currency_iso_code: $this->getUsedCurrency($price['currencySymbol']),
includes_tax: false,
);
}
return [
new PurchaseInfoDTO(
distributor_name: self::DISTRIBUTOR_NAME,
order_number: $sku,
prices: $price_dtos,
product_url: $url,
)
];
}
/**
* Converts Buerklin currency symbol to an ISO code.
* @param string $currency
* @return string
*/
private function getUsedCurrency(string $currency): string
{
//Decide based on the currency symbol
return match ($currency) {
'US$', '$' => 'USD',
'€' => 'EUR',
'A$' => 'AUD',
'C$' => 'CAD',
'£' => 'GBP',
'HK$' => 'HKD',
'JP¥' => 'JPY',
'RM' => 'MYR',
'S$' => 'SGD',
'₽' => 'RUB',
'kr' => 'SEK',
'kr.' => 'DKK',
'₹' => 'INR',
//Fallback to the configured currency
default => $this->currency,
};
}
/**
* Returns a valid Buerklin product short URL from product code
* @param string $product_code
* @return string
*/
private function getProductShortURL(string $product_code): string
{
return 'https://www.buerklin.com/product-detail/' . $product_code .'.html';
}
/**
* Returns a product datasheet FileDTO array from a single pdf url
* @param string $url
* @return FileDTO[]
*/
private function getProductDatasheets(?string $url): array
{
if ($url === null) {
return [];
}
$realUrl = $this->getRealDatasheetUrl($url);
return [new FileDTO($realUrl, null)];
}
/**
* Returns a FileDTO array with a list of product images
* @param array|null $images
* @return FileDTO[]
*/
private function getProductImages(?array $images): array
{
return array_map(static fn($image) => new FileDTO($image), $images ?? []);
}
/**
* @param array|null $attributes
* @return ParameterDTO[]
*/
private function attributesToParameters(?array $attributes): array
{
$result = [];
foreach ($attributes as $attribute) {
//Skip this attribute if it's empty
if (in_array(trim((string) $attribute['paramValueEn']), ['', '-'], true)) {
continue;
}
$result[] = ParameterDTO::parseValueIncludingUnit(name: $attribute['paramNameEn'], value: $attribute['paramValueEn'], group: null);
}
return $result;
}
public function searchByKeyword(string $keyword): array
{
return $this->queryByTerm($keyword);
}
public function getDetails(string $id): PartDetailDTO
{
$tmp = $this->queryByTerm($id);
if (count($tmp) === 0) {
throw new \RuntimeException('No part found with ID ' . $id);
}
if (count($tmp) > 1) {
throw new \RuntimeException('Multiple parts found with ID ' . $id);
}
return $tmp[0];
}
public function getCapabilities(): array
{
return [
ProviderCapabilities::BASIC,
ProviderCapabilities::PICTURE,
ProviderCapabilities::DATASHEET,
ProviderCapabilities::PRICE,
ProviderCapabilities::FOOTPRINT,
];
}
}