{"id":36425018,"url":"https://github.com/znojil/heureka","last_synced_at":"2026-01-13T21:50:19.813Z","repository":{"id":331915643,"uuid":"1127238301","full_name":"znojil/heureka","owner":"znojil","description":"📦 A simple and modern PHP library for communicating with the Heureka API.","archived":false,"fork":false,"pushed_at":"2026-01-03T13:27:35.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T19:34:34.414Z","etag":null,"topics":["api","heureka","http","overeno-zakazniky","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/znojil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-03T13:25:45.000Z","updated_at":"2026-01-03T13:48:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/znojil/heureka","commit_stats":null,"previous_names":["znojil/heureka"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/znojil/heureka","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znojil%2Fheureka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znojil%2Fheureka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znojil%2Fheureka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znojil%2Fheureka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/znojil","download_url":"https://codeload.github.com/znojil/heureka/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/znojil%2Fheureka/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28401367,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","heureka","http","overeno-zakazniky","php"],"created_at":"2026-01-11T17:59:12.029Z","updated_at":"2026-01-13T21:50:19.808Z","avatar_url":"https://github.com/znojil.png","language":"PHP","readme":"# Znojil Heureka\n\n[![Latest Stable Version](https://poser.pugx.org/znojil/heureka/v/stable)](https://github.com/znojil/heureka/releases)\n[![PHP Version Require](https://poser.pugx.org/znojil/heureka/require/php)](https://packagist.org/packages/znojil/heureka)\n[![License](https://poser.pugx.org/znojil/heureka/license)](LICENSE)\n[![Tests](https://github.com/znojil/heureka/actions/workflows/tests.yml/badge.svg)](https://github.com/znojil/heureka/actions)\n\nA simple and modern PHP library for communicating with the Heureka API.\n\nThe library covers services for fetching reviews, the category tree, and the `Verified by Customers` (Ověřeno zákazníky) service.\n\n## 🌐 Supported Regions\n\nThis library supports the following regions:\n- Heureka.cz\n- Heureka.sk\n\n## 🔑 Service Activation\n\nTo use the `Verified by Customers` (Ověřeno zákazníky) service, you must first [activate it here](https://sluzby.heureka.cz/napoveda/overeno-jak-aktivovat/).\n\n## 🚀 Installation\n\nInstall the library using Composer:\n\n```bash\ncomposer require znojil/heureka\n```\n\n## 📖 Usage\n\n### 1. Client Initialization\n\nFirst, you need to create a client instance. The client requires a region (`.cz` or `.sk`) and an [API key](https://sluzby.heureka.cz/sluzby/certifikat-spokojenosti/) for services that need authentication.\n\n```php\nuse Znojil\\Heureka\\Client;\nuse Znojil\\Heureka\\Enum\\Region;\n\n// For Heureka.cz\n$clientCz = new Client(Region::Cz, 'YOUR_API_KEY_FOR_CZ');\n\n// For Heureka.sk\n$clientSk = new Client(Region::Sk, 'YOUR_API_KEY_FOR_SK');\n```\n\n### 2. Using a Custom HTTP Client\n\nYou can inject your own HTTP client implementation by passing it as the third argument to the `Client` constructor. This is useful for testing or for integrating with your application's existing HTTP layer (e.g., Guzzle, Symfony HTTP Client).\n\nYour client must implement the `Znojil\\Heureka\\Http\\Client` interface.\n\n```php\nuse Znojil\\Heureka\\Client;\nuse Znojil\\Heureka\\Enum\\Region;\nuse Znojil\\Heureka\\Http\\Client as HeurekaHttpClient;\nuse Psr\\Http\\Message\\ResponseInterface;\nuse Psr\\Http\\Message\\UriInterface;\n\n// A custom HTTP client implementation example\nclass MyCustomHttpClient implements HeurekaHttpClient{\n\tpublic function send(string $method, UriInterface|string $uri, array $headers = [], mixed $data = null, array $options = []): ResponseInterface{\n\t\t// Your logic to send the request...\n\t\t// For example, using Guzzle:\n\t\t// $guzzleClient = new \\GuzzleHttp\\Client;\n\t\t// return $guzzleClient-\u003erequest($method, $uri, [...]);\n\t}\n}\n\n$customHttpClient = new MyCustomHttpClient;\n$client = new Client(Region::Cz, 'YOUR_API_KEY', $customHttpClient);\n```\n\n### 3. Fetching the Category Tree\n\nThis service does not require an API key.\n\n```php\nuse Znojil\\Heureka\\Feed\\Request\\GetCategoryTreeRequest;\n\n$request = new GetCategoryTreeRequest;\n$categoryTreeCollection = $clientCz-\u003esend($request);\n\nforeach($categoryTreeCollection as $tree){\n\t$tree; // CategoryTreeDTO\n}\n```\n\n### 4. Fetching Shop Reviews\n\nThis service requires an API key. The response is an array of `ShopReviewDTO` objects.\n\n```php\nuse Znojil\\Heureka\\Feed\\Request\\GetShopReviewsRequest;\n\n$request = new GetShopReviewsRequest;\n$reviews = $clientCz-\u003esend($request);\n\nforeach($reviews as $review){\n\t$review; // ShopReviewDTO\n}\n```\n\n### 5. Fetching Product Reviews\n\nThis service requires an API key. You can optionally set a date from which to fetch the reviews. The response is an array of `ProductReviewDTO` objects.\n\n```php\nuse Znojil\\Heureka\\Feed\\Request\\GetProductReviewsRequest;\n\n// Without a date filter\n$requestAll = new GetProductReviewsRequest;\n$allReviews = $clientCz-\u003esend($requestAll);\n\n// Only reviews since yesterday\n$yesterday = new \\DateTimeImmutable('yesterday');\n$requestSince = new GetProductReviewsRequest($yesterday);\n$recentReviews = $clientCz-\u003esend($requestSince);\n```\n\n### 6. Sending an Order (Verified by Customers)\n\nThis service sends order information to the `Verified by Customers` (Ověřeno zákazníky) system. It requires an API key and uses the new v2 API.\n\n```php\nuse Znojil\\Heureka\\ShopCertification\\LogOrderDTO;\nuse Znojil\\Heureka\\ShopCertification\\OrderLogRequest;\n\n// 1. Create a DTO with the order data\n$orderDto = new LogOrderDTO(\n\temail: 'customer@email.com',\n\torderId: 'ORD2024001',\n\tproductItemIds: ['AB-123', 'CD-456']\n);\n\n// 2. Create the request and send it\n$request = new OrderLogRequest($orderDto);\n$response = $clientCz-\u003esend($request);\n\nif($response-\u003eisSuccessful()){\n\techo \"Order was successfully logged.\";\n}\n```\n\n\u003e For more details, see the official [Heureka 'Verified by Customers' documentation](https://github.com/heureka/overeno-zakazniky/blob/30eb6f7ab47ee3068f71efbdbde4a0d4b019a0a2/docs/api-documentation-en.md).\n\n## ⚠️ Error Handling\n\nThe client throws exceptions on failed HTTP requests to help you identify the issue:\n\n- `Znojil\\Heureka\\Exception\\ClientException`: For client-side errors (HTTP 4xx).\n- `Znojil\\Heureka\\Exception\\ServerException`: For server-side errors (HTTP 5xx).\n- `Znojil\\Heureka\\Exception\\ResponseException`: For other HTTP error codes.\n- `Znojil\\Heureka\\Exception\\LogicException`: If you try to call a service that requires an API key without one being set.\n\n## 📄 License\nThis library is open-source software licensed under the [MIT license](https://choosealicense.com/licenses/mit/).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fznojil%2Fheureka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fznojil%2Fheureka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fznojil%2Fheureka/lists"}