Download the PHP package izzudin96/billplz-laravel without Composer

izzudin96/billplz-laravel

A lightweight Billplz package for Laravel 11/12/13.

It returns typed DTOs for bills, redirects, and webhooks so developers can use property access and IDE autocomplete instead of fragile array keys.

It provides a small Billplz client for common payment flow tasks:

• create bills
• fetch bill status
• verify callback/webhook signatures (strict mode)
• parse callback/webhook payloads (best-effort mode)
• use DTO return objects with property access
• configurable HTTP timeout/retry behavior
• safe input/config guards with clear exceptions

Features

• Create bill
• Get bill
• Verify redirect signature
• Verify webhook signature
• Best-effort redirect parsing
• Best-effort webhook parsing
• DTO return objects for autocomplete-friendly access

When to use which method

• verifyRedirect() and verifyWebhook(): Use when you want hard security checks and prefer exceptions on invalid signatures. Both return typed payload objects.
• parseRedirect(): Use when redirect/callback is for UX only and webhook is your source of truth. The returned DTO exposes signature_valid.
• parseWebhook(): Use when you want null-on-failure behavior instead of exceptions. The returned DTO exposes signature_valid.

Installation

Configuration

Publish config:

Or set env variables directly:

Config supports both x-signature and x_signature keys for compatibility.

Optional config/services.php style usage is also supported:

HTTP behavior defaults

• Timeout: 10 seconds
• Retries: 1
• Retry backoff: 200ms

This applies to bill create/get requests.

Usage

How BillplzClient is resolved in Laravel

BillplzClient::class is only a class name string. To call client methods, you need an instance resolved by Laravel's service container.

Preferred patterns:

1. Method injection (clean and explicit)

2. Constructor injection (good when used in multiple methods)

3. Facade usage (shortest call style)

4. app helper (works, but usually less preferred than DI)

Why DI/facade is friendlier:

• Better readability in controllers/services
• Easier testing and mocking
• No repeated container lookup calls

1) Create a bill

2) Get bill status

3) Strict signature verification

Use this when you want invalid signature payloads to fail immediately.

4) Best-effort redirect (recommended for UX callback)

Use this when callback/redirect is only for showing payment result to user. Process fulfillment from webhook instead.

5) Best-effort webhook parser

Use this when you prefer null checks over exception handling.

End-to-end controller example

Suggested routes

Use cases

• Marketplace checkout: create bill per order and reconcile payment on webhook.
• Booking system: attach booking reference via reference_1 and mark booking paid after webhook.
• Membership/fees: use best-effort redirect for user messaging, strict webhook for state changes.
• Legacy migration: keep old callback behavior with parseRedirect(), then gradually move to strict verification.

Notes

• Amount is in cents/sen. Example: RM12.34 = 1234.
• Prefer webhook as the authoritative source for payment completion.
• Redirect callback can be delayed, interrupted, or tampered; treat it as user-facing signal only.
• If BILLPLZ_X_SIGNATURE is not configured, signature checks are skipped and signature_valid is null in parse methods.
• createBill() throws InvalidArgumentException when required config or inputs are missing/invalid. Example checks: empty API key, empty collection ID, invalid email, amount <= 0.

Working with DTOs

Serializing to array/JSON

All DTOs implement JsonSerializable and expose a toArray() method:

Unknown fields returned by Billplz are preserved in $bill->extra and included in both toArray() and json_encode() output. Known keys always take precedence over extra.

Converting to BillResponse

Redirect and webhook payloads can be normalized into a BillResponse for consistent storage:

WebhookPayload::toBillResponse() casts amount from string to int automatically. Fields not present in the source payload (e.g., description, redirect_url) will be null.

Merging bills

Combine a stored bill with an incoming webhook update — non-null incoming values override existing values:

Eloquent cast

Store bill data in a JSON column without writing a custom cast:

The cast also accepts plain arrays on assignment ($order->billplz_data = ['id' => '...', ...]) and converts them into a BillResponse.

Testing

The package includes PHPUnit + Orchestra Testbench tests.

Run tests locally:

Current test coverage includes:

• createBill() request payload and response handling.
• Input validation exceptions for invalid payloads.
• Strict signature verification failure behavior.
• Best-effort parsing behavior for redirect and webhook.
• URL encoding behavior in getBill().

GitHub Actions CI

CI workflow is available at .github/workflows/tests.yml and runs on:

• push to main
• pull requests

Matrix:

• PHP 8.2
• PHP 8.3
• PHP 8.4

Pipeline steps:

• composer validate --strict
• composer install
• composer test

Automated versioning and tagging

This repository now uses Conventional Commits + semantic-release on main.

When commits are merged to main, GitHub Actions will:

• run package checks (composer validate, install, tests)
• analyze commit messages since the last tag
• calculate the next semantic version
• create a Git tag and GitHub Release automatically

Commit types and version bumps

• fix: -> patch bump (for example 1.2.3 -> 1.2.4)
• feat: -> minor bump (for example 1.2.3 -> 1.3.0)
• feat!: or BREAKING CHANGE: in commit body -> major bump (for example 1.2.3 -> 2.0.0)
• other types (docs:, chore:, test: etc.) -> no release by default

Examples:

Best practice workflow

• Use PR titles in Conventional Commit format (checked by CI).
• Keep PRs focused so release notes are clean.
• Use ! only for real breaking API changes.
• Include migration notes in PR description when breaking changes are introduced.

One-time repository setup

No extra secret is needed for basic releases. The workflow uses GitHub's built-in GITHUB_TOKEN.

If this is the first release, create your first baseline tag so the next bump has a reference point:

Workflows added:

• .github/workflows/tests.yml -> test matrix
• .github/workflows/commitlint.yml -> enforce Conventional Commit style on PR titles
• .github/workflows/release.yml -> compute next version and publish tag/release
• .releaserc.json -> semantic-release rules