PHPackages                             taxora/sdk-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. taxora/sdk-php

ActiveLibrary

taxora/sdk-php
==============

Official PHP SDK for the Taxora VAT API (sandbox & production).

v1.4.0(2mo ago)11.6k↓41.2%MITPHPPHP ^8.3 || ^8.4 || ^8.5CI passing

Since Oct 18Pushed 2mo agoCompare

[ Source](https://github.com/theconcept-technologies/taxora-sdk-php)[ Packagist](https://packagist.org/packages/taxora/sdk-php)[ RSS](/packages/taxora-sdk-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (11)Versions (12)Used By (0)

 [![Taxora Logo](https://camo.githubusercontent.com/f1392a64233958fa3bee04836862b99da683476f71d12d50578c4e43479eea49/68747470733a2f2f7461786f72612e696f2f6173736574732f6c6f676f2f7461786f72615f6c6f676f2e737667)](https://camo.githubusercontent.com/f1392a64233958fa3bee04836862b99da683476f71d12d50578c4e43479eea49/68747470733a2f2f7461786f72612e696f2f6173736574732f6c6f676f2f7461786f72615f6c6f676f2e737667)

Taxora PHP SDK
==============

[](#taxora-php-sdk)

> **Official PHP SDK for the [Taxora VAT Validation API](https://taxora.io)**Validate EU VAT numbers, generate compliance certificates, and integrate VAT checks seamlessly into your systems — all with clean, modern PHP.

[![Build](https://github.com/theconcept-technologies/taxora-sdk-php/actions/workflows/ci.yml/badge.svg)](https://github.com/theconcept-technologies/taxora-sdk-php/actions/workflows/ci.yml/badge.svg)
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

[](#)

🚀 Overview
----------

[](#-overview)

The **Taxora SDK** provides an elegant, PSR-compliant interface to the [Taxora API](https://taxora.io), supporting:

- ✅ Secure **API-Key** and **Bearer Token** authentication
- ✅ Single & multiple VAT validation with AI-based company matching
- ✅ VAT state history and search endpoints
- ✅ Certificate generation (PDF) and bulk/list exports (ZIP or PDF)
- ✅ Full test coverage & PSR-18 compatible HTTP client
- ✅ PHP 8.3, 8.4, and (soon) 8.5 ready

> 🔒 The SDK itself is free to use, but a **Taxora API subscription** is required. You can obtain your `x-api-key` from your [Taxora account developer settings](https://app.taxora.io).

---

🧮 Installation
--------------

[](#-installation)

Install via Composer:

```
composer require taxora/sdk-php
```

The package supports all PSR-18 clients (e.g. Guzzle, Symfony, Buzz) and PSR-17/PSR-7 factories.

Example dependencies for Guzzle:

```
composer require guzzlehttp/guzzle http-interop/http-factory-guzzle
```

---

⚙️ Quick Start
--------------

[](#️-quick-start)

```
use Taxora\Sdk\TaxoraClientFactory;
use Taxora\Sdk\Enums\Environment;

$client = TaxoraClientFactory::create(
    apiKey: 'YOUR_X_API_KEY',
    environment: Environment::SANDBOX // or PRODUCTION
);

// 1️⃣ Authenticate
$client->auth()->login('user@example.com', 'superSecret');

// 2️⃣ Validate a VAT number
$vat = $client->vat()->validate('ATU12345678', 'Example GmbH');
echo $vat->state->value;        // valid / invalid
echo $vat->company_name; // Official company name
echo $vat->score;        // Overall confidence score (float)

foreach ($vat->breakdown ?? [] as $step) {
    echo $step->stepName.' gave '.$step->scoreContribution.PHP_EOL;
}

// Optional typed address input for fallback name scoring
$addressInput = new \Taxora\Sdk\ValueObjects\VatValidationAddressInput(
    addressLine1: 'Example GmbH',
    addressLine2: '2nd Floor',
    postalCode: '1010',
    city: 'Vienna',
    countryCode: 'AT'
);
$vatWithAddress = $client->vat()->validate('ATU12345678', 'John Doe', 'vies', $addressInput);

// 3️⃣ Access company info
$company = $client->company()->get();

// 4️⃣ Export certificates (returns a VatCertificateExport object)
$export = $client->vat()->certificatesBulkExport('2024-01-01', '2024-12-31');
$pdfZip = $client->vat()->downloadBulkExport($export->exportId);
file_put_contents('certificates.zip', $pdfZip);
```

`vat()->validate()` returns a `VatResource` object that includes the canonical VAT number, status, requested company name echo, and optional scoring data. The `score` reflects the overall confidence (higher is better), while `breakdown` provides an array of `ScoreBreakdown` objects describing every validation step, its score contribution, and any metadata (e.g. matched addresses or mismatched fields).

Need to plug in your own PSR-18 client or PSR-17 factories (e.g. to add logging or retries)? Call the constructor directly or pass them as optional overrides to the factory:

```
use GuzzleHttp\Client as GuzzleAdapter;
use Http\Factory\Guzzle\RequestFactory;
use Http\Factory\Guzzle\StreamFactory;
use Taxora\Sdk\TaxoraClientFactory;

$client = TaxoraClientFactory::create(
    apiKey: 'YOUR_X_API_KEY',
    http: new GuzzleAdapter(),
    requestFactory: new RequestFactory(),
    streamFactory: new StreamFactory()
);
```

---

🧩 Architecture
--------------

[](#-architecture)

The SDK follows clean separation of concerns:

```
TaxoraClient
 ├── auth()     → AuthEndpoint     (login, refresh)
 ├── company()  → CompanyEndpoint  (company info)
 └── vat()      → VatEndpoint      (validate, history, search, certificate)

```

Each endpoint handles:

- Request signing with `x-api-key`
- Bearer token refresh if expired or unauthorized
- PSR-7 response parsing into DTOs

---

📦 DTOs
------

[](#-dtos)

ClassDescription`VatResource`Represents a single VAT validation result (normalized VAT UID, state, score, breakdown, company data)`ScoreBreakdown`Scoring fragment with validation step name, score contribution, and metadata context for the decision`VatCollection`Iterable list of `VatResource` objects`Token`Auth token with expiry & typeExample:

```
$dto = $client->vat()->validate('ATU12345678');
print_r($dto->toArray());
```

---

🔄 Authentication Flow
---------------------

[](#-authentication-flow)

1. **Login**

    ```
    $client->auth()->login('email', 'password', device: 'my-server-01');
    // Passing device is optional; omitted value falls back to a generated host-based identifier.
    ```

    Need to authenticate with a technical `client_id` instead of an email?

    ```
    $client->auth()->loginWithClientId('client_abc123', 'client-secret', device: 'integration-box');
    ```

    > Advanced: you can still pass `loginIdentifier: LoginIdentifier::CLIENT_ID` into `login()` if you prefer an explicit enum instead of the helper.

    → Stores and returns a `Token` DTO (valid for ~3600 seconds).
2. **Auto-refresh**The client automatically refreshes the token on `401` responses.
3. **Manual refresh (optional)**

    ```
    $client->auth()->refresh();
    ```
4. **Token storage**By default, tokens are stored in memory. You can provide a PSR-16 cache adapter for persistence:

    ```
    use Symfony\Component\Cache\Adapter\FilesystemAdapter;
    use Symfony\Component\Cache\Psr16Cache;
    use Taxora\Sdk\Http\Psr16TokenStorage;

    $cache = new Psr16Cache(new FilesystemAdapter());
    $storage = new Psr16TokenStorage($cache);
    $client = new TaxoraClient($http, $reqF, $strF, 'YOUR_KEY', $storage);
    ```

---

🤪 Testing
---------

[](#-testing)

Run the test suite locally:

```
composer test
```

CI runs on **PHP 8.3**, **8.4**, and (soon) **8.5**, verifying:

- PHPUnit 12
- Psalm static analysis
- Code style checks

---

🗟️ Environments
---------------

[](#️-environments)

EnvironmentBase URLSandbox`https://sandbox.taxora.io/v1`Production`https://api.taxora.io/v1`Need sandbox sample data? Known VAT UIDs with deterministic responses live in `tests/Fixtures/SandboxVatFixtures.php`.

Switch easily via the constructor:

```
$client = new TaxoraClient(..., environment: Environment::PRODUCTION);
```

---

⚠️ Deprecations
---------------

[](#️-deprecations)

So fresh there aren't even any deprecated features yet. Check back in a few months when we're on v47 and have made some regrettable decisions. 🎉

---

🪪 License
---------

[](#-license)

Licensed under the **MIT License** © 2025 [theconcept technologies](https://www.theconcept-technologies.com). The SDK is open-source, but API usage requires a valid **Taxora subscription**.

---

🤝 Contributing
--------------

[](#-contributing)

Contributions and pull requests are welcome!

- Follow PSR-12 coding style (`composer fix`).
- Run `composer test` before submitting a PR.
- Ensure new endpoints include DTOs + tests.

---

💬 Support
---------

[](#-support)

Need help or enterprise support? 📧 ****🌐

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance83

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 94.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~12 days

Recently: every ~27 days

Total

11

Last Release

85d ago

Major Versions

v0.2.2 → v1.0.02025-11-05

PHP version history (2 changes)v0.1.0PHP ^8.3 || ^8.4

v1.3.0PHP ^8.3 || ^8.4 || ^8.5

### Community

Maintainers

![](https://www.gravatar.com/avatar/663c8817a6ebfe9a009d21fa10e30ce12ed270777f2fd2cf91bdf89523426448?d=identicon)[theconcept-technologies](/maintainers/theconcept-technologies)

---

Top Contributors

[![TCT-CodingWizard](https://avatars.githubusercontent.com/u/39767624?v=4)](https://github.com/TCT-CodingWizard "TCT-CodingWizard (18 commits)")[![theconcept-technologies](https://avatars.githubusercontent.com/u/184284872?v=4)](https://github.com/theconcept-technologies "theconcept-technologies (1 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/taxora-sdk-php/health.svg)

```
[![Health](https://phpackages.com/badges/taxora-sdk-php/health.svg)](https://phpackages.com/packages/taxora-sdk-php)
```

###  Alternatives

[cakephp/cakephp

The CakePHP framework

8.8k18.5M1.6k](/packages/cakephp-cakephp)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

81733.7k](/packages/flow-php-flow)[laudis/neo4j-php-client

Neo4j-PHP-Client is the most advanced PHP Client for Neo4j

184616.9k31](/packages/laudis-neo4j-php-client)[opensearch-project/opensearch-php

PHP Client for OpenSearch

15024.3M65](/packages/opensearch-project-opensearch-php)[wordpress/php-ai-client

A provider agnostic PHP AI client SDK to communicate with any generative AI models of various capabilities using a uniform API.

26236.6k14](/packages/wordpress-php-ai-client)[growthbook/growthbook

PHP SDK for GrowthBook, the feature flagging and A/B testing platform

202.9M3](/packages/growthbook-growthbook)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)