Download the PHP package slimad/colnect-api without Composer

Colnect API – PHP SDK

A lightweight, fully typed PHP SDK for the Colnect REST API, built on top of Saloon v3. It ships with first-class support for HMAC request signing, request mocking, PHPStan level 9 static analysis and mutation testing via Infection.

Table of contents

• Features
• Requirements
• Installation
• Quick start
• Authentication
• Available requests
• Working with categories
• Filtering lists
• Items and pictures
• Marketplace
• Image search
• Error handling
• Mocking & testing your integration
• Development
  • Running the test suite
  • Static analysis
  • Mutation testing
• Documentation
• Versioning
• Contributing
• Security
• License
• Attribution required by Colnect
• Credits

Features

• Full CAPI coverage - general, collector, category, search, image search and marketplace actions.
• Saloon v3 connector with a clean, request-per-endpoint architecture.
• Built-in HMAC-SHA256 signing of every outgoing request (Capi-Timestamp + Capi-Hash headers).
• HTTP/2 by default - CAPI rejects HTTP/1.x with 426 Upgrade Required, so the connector asks Guzzle for HTTP/2.
• Locale aware - the connector automatically routes requests through the localized Colnect endpoint (/en, /pl, /fr, ...).
• Composable filters - the documented common list filters (and the undocumented ones) through an immutable Filters object.
• Picture URL builder - turns picture IDs into thumbnail or full size image URLs, including the urlize() slug rules.
• Strongly typed with declare(strict_types=1) everywhere and an enum-driven catalog of collectable categories (CategoryType).
• Fails fast - malformed IDs, categories, page numbers or user agents throw before anything reaches the wire.
• Mock-friendly - integrates seamlessly with Saloon's MockClient / MockResponse for unit testing your own application.
• Quality-first:
  • PHPUnit 10
  • PHPStan level 9
  • Infection MSI (@default mutators) with pcov coverage
• PSR-4 autoloaded library with zero runtime dependencies beyond Saloon.

Requirements

CAPI is served exclusively over HTTP/2, so the cURL build used by Guzzle has to support it (curl --version must list HTTP2).

Installation

Install the package via Composer:

The package is distributed under the slimad/colnect-api name. The autoload root is Slimad\ColnectApi\ and maps to src/.

Quick start

Authentication

Colnect uses an appId + appSecret pair that must be requested from Colnect. Every request is signed with an HMAC-SHA256 hash:

The signing logic lives in ColnectConnector::boot() and is applied automatically to every request - you never have to touch it yourself.

Never commit your appSecret to version control. Load it from environment variables, a secrets manager, or your framework's configuration layer. If a secret leaks, revoke it and generate a new one - Colnect accepts both secrets for a short grace period while you rotate.

Available requests

General actions

Collector actions

Privacy settings may make Colnect answer private instead of the data.

Category actions

Not every action exists in every category - ask GetCategoryActionsRequest when in doubt.

Search

Marketplace

All request classes follow the same pattern:

Working with categories

The CategoryType enum provides a typed list of the collectable categories supported by Colnect, using the very module names Colnect expects in the cat filter:

Each category-aware request accepts either the enum or a raw string, so you can interoperate with values coming from forms, configs, or HTTP input:

Colnect names the producer differently per category ("company" for phonecards, "brand" for teabags, the country itself for stamps). The enum knows the mapping:

Categories are edited continuously on Colnect, so treat the enum as a convenience and GetCategoriesRequest as the source of truth.

Filtering lists

Filters is an immutable collection rendering the documented common list filters as path segments, in the order you add them:

Named helpers exist for country, producer, series, year, theme, catalog, currency, face_value, system, sort and page. Colnect exposes more filters while you navigate the site; reach them with with():

Filter IDs are Colnect-internal and change over time - the API documentation asks you not to cache them for more than 24 hours.

Items and pictures

GetItemRequest returns the fields listed by GetFieldTitlesRequest, in the same order. The fields differ per category and may change, so read them at runtime instead of hard-coding offsets:

Picture IDs become URLs through PictureUrl:

The item name is slugged with Str::urlize(), the port of the function published in the API specification.

Marketplace

Image search

Image search is disabled by default and billed per call, so it has to be enabled for your application first. Because image recognition is imperfect, narrowing the search down with a category and filters is recommended.

A target can also be built from base64 data (ImageSearchTarget::fromBase64()) or from a local file (ImageSearchTarget::fromFile()), each with a withBack*() counterpart. The response carries distances and best_matches, where c_id is the item ID and p_id the picture ID.

Error handling

Every malformed argument throws Slimad\ColnectApi\Exceptions\InvalidArgumentException, which extends the SPL \InvalidArgumentException:

HTTP errors are handled by Saloon as usual - use $response->failed(), $response->status() or $connector->send() with ->throw().

Mocking & testing your integration

Because the SDK is built on Saloon, you can mock every response without hitting the network - ideal for fast, deterministic unit tests:

See tests/ColnectConnectorTest.php for end-to-end examples of asserting headers, payloads and the HMAC signature.

Development

Clone the repository and install dev dependencies:

Running the test suite

The test suite runs against:

• tests/ColnectConnectorTest.php – connector + auth flow
• tests/Requests/**/*Test.php – one test per request class

Static analysis

PHPStan is configured at level 9 for both src/ and tests/:

Mutation testing

Infection is configured with the @default mutator set and source-only coverage:

The pcov extension is required for coverage; it is already declared as a dev dependency in composer.json.

Documentation

• API reference – the source of truth for available endpoints is the official Colnect API documentation. This SDK is a thin, typed wrapper over those endpoints. Not every action exists in every category, and Colnect takes requests for missing actions on the CAPI forum.
• Saloon documentation – for advanced features such as request concurrency, retries, plugins, response DTOs, pagination, OAuth flows and caching, see the Saloon v3 docs.
• Source code – every public class is annotated with PHPDoc. The fastest way to discover the surface area of this library is to browse src/.
• Examples – tests under tests/ double as runnable usage examples for every request class.

Versioning

This project follows Semantic Versioning 2.0.0:

• MAJOR – incompatible API changes.
• MINOR – backwards-compatible feature additions (new requests, new enum cases, …).
• PATCH – backwards-compatible bug fixes and internal refactors.

Pin a major version in your composer.json to avoid unexpected breaking changes:

Contributing

Contributions are welcome and appreciated! To contribute:

1. Fork the repository and create a feature branch off main.
2. Add code and tests – PRs without tests will not be merged.

3. Make sure the full quality gate passes locally:

4. Follow the existing coding style – declare(strict_types=1), typed properties, PSR-12 formatting.
5. Open a pull request describing what changed and why.

Bug reports and feature requests can be filed via GitHub Issues. Please include a minimal reproducible example whenever possible.

Security

Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.

If you discover a security vulnerability in this package, report it privately so it can be addressed before public disclosure:

• Preferred channel: open a GitHub private security advisory for this repository.
• Alternative: email the maintainer directly at the address listed on the maintainer's GitHub profile. Use a clear subject such as [SECURITY] Colnect-api – <short summary>.

When reporting, please include:

1. A description of the vulnerability and the impact you believe it may have.
2. Step-by-step instructions to reproduce the issue (proof of concept code is ideal).
3. The affected version(s) of the package.
4. Any suggested remediation, if known.

You can expect:

• An initial acknowledgement within 72 hours.
• A status update at least every 7 days until the issue is resolved.
• Public disclosure (CVE if applicable) coordinated with you after a fix is released.

Please act in good faith and avoid:

• Exploiting the vulnerability beyond what is necessary to demonstrate it.
• Disclosing the issue publicly before a fix is available.
• Accessing data that is not yours.

License

This package is open-sourced software licensed under the MIT License.

See the LICENSE file for the full text. In short, you are free to use, copy, modify, merge, publish, distribute, sublicense and/or sell copies of the software, provided the original copyright notice and the license text are included in all copies or substantial portions of the software. The software is provided "as is", without warranty of any kind.

Credits

• Author / Maintainer: Maciej Kosiedowski

If this package is useful to you, please consider starring the repository on GitHub ⭐.