# izzudin96/billplz-laravel architecture

> Architecture diagram of the GitHub repository izzudin96/billplz-laravel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/izzudin96/billplz-laravel
- Repository: https://github.com/izzudin96/billplz-laravel

## Overview

This is a Laravel integration package that wraps Billplz bill creation and status retrieval, and handles redirect and webhook payloads through strict verification or best-effort parsing. The main workflow is an application resolving the client, making bill API calls, and receiving typed bill DTOs; callbacks and webhooks are parsed separately into typed payload DTOs. Laravel configuration and the facade support client setup and access, while an Eloquent cast converts bill values to and from DTOs. Client internals and some wiring are only partially sampled, so uncertain implementation links are omitted.

Main entry points: [`src/BillplzClient.php`](https://github.com/izzudin96/billplz-laravel/blob/main/src/BillplzClient.php) (Billplz client), [`src/DTOs/BillResponse.php`](https://github.com/izzudin96/billplz-laravel/blob/main/src/DTOs/BillResponse.php) (Bill response), [`src/BillplzServiceProvider.php`](https://github.com/izzudin96/billplz-laravel/blob/main/src/BillplzServiceProvider.php) (Service provider), [`src/DTOs/WebhookPayload.php`](https://github.com/izzudin96/billplz-laravel/blob/main/src/DTOs/WebhookPayload.php) (Webhook payload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Laravel integration"]
  node_provider["Service provider"]
  node_config["Client configuration<br/>[billplz.php]"]
  node_facade["Billplz facade<br/>[Billplz.php]"]
end

subgraph group_client["Billplz client"]
  node_client["Billplz client<br/>[BillplzClient.php]"]
  node_http["Laravel HTTP client"]
  node_signature["Signature checks<br/>[BillplzClient.php]"]
  node_signatureexception["Signature exception"]
end

subgraph group_payloads["Typed payloads"]
  node_billresponse["Bill response<br/>[BillResponse.php]"]
  node_redirect["Redirect payload"]
  node_webhook["Webhook payload<br/>[WebhookPayload.php]"]
end

subgraph group_mapping["Data mapping"]
  node_normalizers["Value normalizers"]
  node_eloquentcast["Bill Eloquent cast<br/>[BillplzBill.php]"]
end

node_application(("Laravel application"))
node_billplz(("Billplz API"))
node_eloquent[("Eloquent model")]

node_application -->|"resolves client"| node_provider
node_provider -->|"merges settings"| node_config
node_provider -->|"registers singleton"| node_client
node_application -->|"calls methods"| node_facade
node_facade -->|"resolves accessor"| node_client
node_application -->|"calls methods"| node_client
node_client -->|"configures requests"| node_http
node_client -->|"creates or fetches bills"| node_billplz
node_billplz -->|"returns responses"| node_http
node_client -->|"maps bill data"| node_billresponse
node_client -->|"checks signatures"| node_signature
node_client -->|"parses redirect"| node_redirect
node_client -->|"parses webhook"| node_webhook
node_client -->|"throws on failure"| node_signatureexception
node_billresponse -->|"normalizes values"| node_normalizers
node_redirect -->|"normalizes values"| node_normalizers
node_webhook -->|"normalizes values"| node_normalizers
node_webhook -->|"converts payload"| node_billresponse
node_eloquent -->|"casts attributes"| node_eloquentcast
node_eloquentcast -->|"maps stored values"| node_billresponse

click node_provider "https://github.com/izzudin96/billplz-laravel/blob/main/src/BillplzServiceProvider.php"
click node_config "https://github.com/izzudin96/billplz-laravel/blob/main/config/billplz.php"
click node_facade "https://github.com/izzudin96/billplz-laravel/blob/main/src/Facades/Billplz.php"
click node_client "https://github.com/izzudin96/billplz-laravel/blob/main/src/BillplzClient.php"
click node_signature "https://github.com/izzudin96/billplz-laravel/blob/main/src/BillplzClient.php"
click node_billresponse "https://github.com/izzudin96/billplz-laravel/blob/main/src/DTOs/BillResponse.php"
click node_redirect "https://github.com/izzudin96/billplz-laravel/blob/main/src/DTOs/RedirectPayload.php"
click node_webhook "https://github.com/izzudin96/billplz-laravel/blob/main/src/DTOs/WebhookPayload.php"
click node_normalizers "https://github.com/izzudin96/billplz-laravel/tree/main/src/Concerns"
click node_eloquentcast "https://github.com/izzudin96/billplz-laravel/blob/main/src/Casts/BillplzBill.php"
click node_signatureexception "https://github.com/izzudin96/billplz-laravel/blob/main/src/Exceptions/FailedSignatureVerification.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_config,node_facade toneBlue
class node_client,node_http,node_signature,node_signatureexception,node_eloquent toneAmber
class node_billresponse,node_redirect,node_webhook,node_billplz toneMint
class node_normalizers,node_eloquentcast toneRose
class node_application toneIndigo
```

## Components

### Laravel integration

- [Service provider](https://github.com/izzudin96/billplz-laravel/blob/main/src/BillplzServiceProvider.php): `src/BillplzServiceProvider.php`
- [Client configuration](https://github.com/izzudin96/billplz-laravel/blob/main/config/billplz.php): `config/billplz.php`
- [Billplz facade](https://github.com/izzudin96/billplz-laravel/blob/main/src/Facades/Billplz.php): `src/Facades/Billplz.php`

### Billplz client

- [Billplz client](https://github.com/izzudin96/billplz-laravel/blob/main/src/BillplzClient.php): `src/BillplzClient.php`
- **Laravel HTTP client**
- [Signature checks](https://github.com/izzudin96/billplz-laravel/blob/main/src/BillplzClient.php): `src/BillplzClient.php`
- [Signature exception](https://github.com/izzudin96/billplz-laravel/blob/main/src/Exceptions/FailedSignatureVerification.php): `src/Exceptions/FailedSignatureVerification.php`

### Typed payloads

- [Bill response](https://github.com/izzudin96/billplz-laravel/blob/main/src/DTOs/BillResponse.php): `src/DTOs/BillResponse.php`
- [Redirect payload](https://github.com/izzudin96/billplz-laravel/blob/main/src/DTOs/RedirectPayload.php): `src/DTOs/RedirectPayload.php`
- [Webhook payload](https://github.com/izzudin96/billplz-laravel/blob/main/src/DTOs/WebhookPayload.php): `src/DTOs/WebhookPayload.php`

### Data mapping

- [Value normalizers](https://github.com/izzudin96/billplz-laravel/tree/main/src/Concerns): `src/Concerns`
- [Bill Eloquent cast](https://github.com/izzudin96/billplz-laravel/blob/main/src/Casts/BillplzBill.php): `src/Casts/BillplzBill.php`

### Other components

- **Laravel application**
- **Billplz API**
- **Eloquent model**

## Connections

- Laravel application → Service provider: resolves client
- Service provider → Client configuration: merges settings
- Service provider → Billplz client: registers singleton
- Laravel application → Billplz facade: calls methods
- Billplz facade → Billplz client: resolves accessor
- Laravel application → Billplz client: calls methods
- Billplz client → Laravel HTTP client: configures requests
- Billplz client → Billplz API: creates or fetches bills
- Billplz API → Laravel HTTP client: returns responses
- Billplz client → Bill response: maps bill data
- Billplz client → Signature checks: checks signatures
- Billplz client → Redirect payload: parses redirect
- Billplz client → Webhook payload: parses webhook
- Billplz client → Signature exception: throws on failure
- Bill response → Value normalizers: normalizes values
- Redirect payload → Value normalizers: normalizes values
- Webhook payload → Value normalizers: normalizes values
- Webhook payload → Bill response: converts payload
- Eloquent model → Bill Eloquent cast: casts attributes
- Bill Eloquent cast → Bill response: maps stored values