# pingencom/pingen2-sdk-php architecture

> Architecture diagram of the GitHub repository pingencom/pingen2-sdk-php, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pingencom/pingen2-sdk-php
- Repository: https://github.com/pingencom/pingen2-sdk-php

## Overview

This is a PHP client SDK for Pingen’s document-delivery API. A typical integration obtains an OAuth access token, configures a resource endpoint for an organisation and environment, then submits documents or manages delivery resources; the SDK sends authenticated JSON:API requests and maps responses into typed DTOs. The API surface also covers batches, letters, email, e-bills, events, uploads, organisations, users, and webhooks. Source excerpts show the shared request layer and webhook handling; most endpoint implementations are unsampled, so their detailed call relationships are not asserted.

Main entry points: [`src/ResourceEndpoint.php`](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/ResourceEndpoint.php) (HTTP request layer), [`src/Endpoints/WebhooksEndpoint.php`](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/WebhooksEndpoint.php) (Webhook management), [`src/IncomingWebhook/IncomingWebhook.php`](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/IncomingWebhook/IncomingWebhook.php) (Incoming webhook parser), [`src/Provider/Pingen.php`](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Provider/Pingen.php) (OAuth provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_auth["Authentication"]
  node_provider["OAuth provider<br/>[Pingen.php]"]
  node_resource_owner["Resource owner<br/>[ResourceOwner.php]"]
end

subgraph group_api["API resources"]
  node_resource_endpoints["Resource endpoints"]
  node_letters["Letters"]
  node_batches["Batches"]
  node_emails["Email delivery<br/>[EmailsEndpoint.php]"]
  node_ebills["E-bill delivery<br/>[EbillsEndpoint.php]"]
  node_uploads["File uploads"]
  node_events["Delivery events"]
  node_org_users["Organisation and users"]
  node_webhook_admin["Webhook management"]
end

subgraph group_models["Data mapping"]
  node_dto["Response DTOs"]
  node_input["Request inputs<br/>[Input.php]"]
  node_dto_engine["DTO engine"]
end

subgraph group_webhooks["Webhook handling"]
  node_incoming["Incoming webhook parser"]
  node_incoming_dto["Incoming event DTOs"]
end

subgraph group_core["SDK core"]
  node_http_layer["HTTP request layer"]
  node_collection_params["Collection parameters"]
  node_api_errors["API error handling"]
end

node_developer(("SDK user"))
node_pingen_identity(("Pingen identity"))
node_pingen_api(("Pingen API"))

node_developer -->|"configures"| node_provider
node_provider -->|"requests tokens"| node_pingen_identity
node_developer -->|"creates endpoint"| node_letters
node_letters -.->|"uploads document"| node_uploads
node_resource_endpoints -->|"uses requests"| node_http_layer
node_webhook_admin -->|"performs requests"| node_http_layer
node_http_layer -->|"sends authenticated requests"| node_pingen_api
node_http_layer -->|"raises API errors"| node_api_errors
node_webhook_admin -->|"passes filters"| node_collection_params
node_webhook_admin -->|"constructs responses"| node_dto
node_developer -.->|"processes webhook"| node_incoming
node_incoming -->|"builds details"| node_incoming_dto
node_incoming -.->|"verifies signed payload"| node_pingen_api
node_dto -->|"maps response data"| node_dto_engine
node_input -->|"serializes request body"| node_http_layer
node_http_layer -->|"selects staging or production"| node_pingen_api

click node_provider "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Provider/Pingen.php"
click node_resource_owner "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/ResourceOwner.php"
click node_resource_endpoints "https://github.com/pingencom/pingen2-sdk-php/tree/main/src/Endpoints"
click node_letters "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/LettersEndpoint.php"
click node_batches "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/BatchesEndpoint.php"
click node_emails "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/EmailsEndpoint.php"
click node_ebills "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/EbillsEndpoint.php"
click node_uploads "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/FileUploadEndpoint.php"
click node_events "https://github.com/pingencom/pingen2-sdk-php/tree/main/src/Endpoints"
click node_org_users "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/OrganisationsEndpoint.php"
click node_webhook_admin "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/WebhooksEndpoint.php"
click node_dto "https://github.com/pingencom/pingen2-sdk-php/tree/main/src/Endpoints/DataTransferObjects"
click node_input "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Support/Input.php"
click node_dto_engine "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Support/DataTransferObject/DataTransferObject.php"
click node_http_layer "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/ResourceEndpoint.php"
click node_collection_params "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Support/CollectionParameterBag.php"
click node_incoming "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/IncomingWebhook/IncomingWebhook.php"
click node_incoming_dto "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/IncomingWebhook/DataTransferObjects/IncomingWebhookDetails.php"
click node_api_errors "https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Exceptions/JsonApiException.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_provider,node_resource_owner,node_developer toneBlue
class node_resource_endpoints,node_letters,node_batches,node_emails,node_ebills,node_uploads,node_events,node_org_users,node_webhook_admin toneAmber
class node_dto,node_input,node_dto_engine,node_pingen_api toneMint
class node_incoming,node_incoming_dto toneRose
class node_http_layer,node_collection_params,node_api_errors,node_pingen_identity toneIndigo
```

## Components

### Authentication

- [OAuth provider](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Provider/Pingen.php): `src/Provider/Pingen.php`
- [Resource owner](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/ResourceOwner.php): `src/ResourceOwner.php`

### API resources

- [Resource endpoints](https://github.com/pingencom/pingen2-sdk-php/tree/main/src/Endpoints): `src/Endpoints`
- [Letters](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/LettersEndpoint.php): `src/Endpoints/LettersEndpoint.php`
- [Batches](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/BatchesEndpoint.php): `src/Endpoints/BatchesEndpoint.php`
- [Email delivery](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/EmailsEndpoint.php): `src/Endpoints/EmailsEndpoint.php`
- [E-bill delivery](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/EbillsEndpoint.php): `src/Endpoints/EbillsEndpoint.php`
- [File uploads](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/FileUploadEndpoint.php): `src/Endpoints/FileUploadEndpoint.php`
- [Delivery events](https://github.com/pingencom/pingen2-sdk-php/tree/main/src/Endpoints): `src/Endpoints`
- [Organisation and users](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/OrganisationsEndpoint.php): `src/Endpoints/OrganisationsEndpoint.php`
- [Webhook management](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Endpoints/WebhooksEndpoint.php): `src/Endpoints/WebhooksEndpoint.php`

### Data mapping

- [Response DTOs](https://github.com/pingencom/pingen2-sdk-php/tree/main/src/Endpoints/DataTransferObjects): `src/Endpoints/DataTransferObjects`
- [Request inputs](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Support/Input.php): `src/Support/Input.php`
- [DTO engine](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Support/DataTransferObject/DataTransferObject.php): `src/Support/DataTransferObject/DataTransferObject.php`

### Webhook handling

- [Incoming webhook parser](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/IncomingWebhook/IncomingWebhook.php): `src/IncomingWebhook/IncomingWebhook.php`
- [Incoming event DTOs](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/IncomingWebhook/DataTransferObjects/IncomingWebhookDetails.php): `src/IncomingWebhook/DataTransferObjects/IncomingWebhookDetails.php`

### SDK core

- [HTTP request layer](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/ResourceEndpoint.php): `src/ResourceEndpoint.php`
- [Collection parameters](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Support/CollectionParameterBag.php): `src/Support/CollectionParameterBag.php`
- [API error handling](https://github.com/pingencom/pingen2-sdk-php/blob/main/src/Exceptions/JsonApiException.php): `src/Exceptions/JsonApiException.php`

### Other components

- **SDK user**
- **Pingen identity**
- **Pingen API**

## Connections

- SDK user → OAuth provider: configures (evidence: `README.md`)
- OAuth provider → Pingen identity: requests tokens (evidence: `src/Provider/Pingen.php`)
- SDK user → Letters: creates endpoint (evidence: `README.md`)
- Letters → File uploads: uploads document
- Resource endpoints → HTTP request layer: uses requests (evidence: `src/Endpoints/WebhooksEndpoint.php`)
- Webhook management → HTTP request layer: performs requests (evidence: `src/Endpoints/WebhooksEndpoint.php`)
- HTTP request layer → Pingen API: sends authenticated requests (evidence: `src/ResourceEndpoint.php`)
- HTTP request layer → API error handling: raises API errors (evidence: `src/ResourceEndpoint.php`)
- Webhook management → Collection parameters: passes filters (evidence: `src/Endpoints/WebhooksEndpoint.php`)
- Webhook management → Response DTOs: constructs responses (evidence: `src/Endpoints/WebhooksEndpoint.php`)
- SDK user → Incoming webhook parser: processes webhook
- Incoming webhook parser → Incoming event DTOs: builds details (evidence: `src/IncomingWebhook/IncomingWebhook.php`)
- Incoming webhook parser → Pingen API: verifies signed payload
- Response DTOs → DTO engine: maps response data (evidence: `src/Endpoints/DataTransferObjects/Webhook/WebhookCollection.php`)
- Request inputs → HTTP request layer: serializes request body (evidence: `src/ResourceEndpoint.php`)
- HTTP request layer → Pingen API: selects staging or production (evidence: `src/ResourceEndpoint.php`)