Wallet – Payment Processing Skeleton

This project is a Laravel-based payment processing skeleton that demonstrates a robust, production-ready architecture for:

• Accepting and validating inbound webhooks from multiple bank sources
• Creating and tracking payment requests
• Ensuring safe, idempotent transaction creation using distributed locks
• Strong static analysis and type-safety throughout the codebase

Tech Stack

• PHP 8.4
• Laravel 12
• Redis (optional, for distributed locking)
• Pest for tests, PHPStan (via Larastan) for static analysis, Rector for automated refactoring, Pint for formatting
• Scramble (OpenAPI/Swagger) for API documentation served at /docs/api

Requirements

• PHP 8.4+, Composer
• your preferred database (MySQL, PostgreSQL, SQLite, etc.)
• Optional: Redis server and the PhpRedis extension if you switch the lock backend to Redis

Quick Start

Clone the repository:

git clone git@github.com:Msalah11/wallet-application.git

Navigate to your project and complete the setup:

cd wallet-application

# Setup project
composer setup

# Start the development environment
composer dev

Running & Testing

Development

• composer dev — Starts Laravel server, queue worker, log monitoring (Pail), and Vite dev server concurrently.

Full Test Suite

Run the full suite (type coverage, unit tests, linting, static analysis):

composer test

Breakdown of the available commands:

• composer test:type-coverage — Ensures 100% type coverage with Pest.
• composer test:unit — Runs unit tests with coverage (threshold configured at 80%).
• composer test:lint — Rector dry-run and Pint test mode, plus Prettier check for JS/CSS.
• composer test:types — Runs PHPStan at level 9 (maximum strictness).

Code Quality

• composer lint — Runs Rector (refactoring), Pint (PHP formatting), and Prettier (JS/TS formatting).

Maintenance

• composer update:requirements — Updates all PHP and NPM dependencies to latest versions.

API Documentation

Interactive API documentation is available at:

• http://localhost:8000/docs/api

Docs are powered by the Scramble package and include a Stoplight Elements UI. By default, the API base path is /api, and the docs page is protected by middleware to restrict access. You can customize behavior in config/scramble.php.

Example API Structure

• Base path: /api
• Versioned routes: /api/v1/...
  • Webhooks: POST /api/v1/webhooks and POST /api/v1/webhooks/generate-signature
  • Payments: POST /api/v1/payments, GET /api/v1/payments, GET /api/v1/payments/{reference}

Configuration Highlights

Transaction Locking

Lock strategy is configurable at runtime:

• Config file: config/infrastructure.php
• Env var: INFRASTRUCTURE_LOCK_DEFAULT — options: database (default), redis

When redis is selected, the application uses PhpRedis to safely acquire and release locks. Ensure your Redis server and PhpRedis extension are available.

Webhook Secrets & Payment Signatures

Webhook verification and payment signature generation are configured in config/services.php and use environment variables:

• FOODICS_WEBHOOK_SECRET, ACME_WEBHOOK_SECRET
• FOODICS_PAYMENT_SECRET, ACME_PAYMENT_SECRET
• Optional API URLs and timeouts per provider

Packages Used

PHP (runtime)

• laravel/framework — Laravel application framework
• nunomaduro/essentials — Developer ergonomics helpers for Laravel

PHP (development)

• dedoc/scramble — API docs (OpenAPI/Swagger) rendered at /docs/api
• larastan/larastan — Laravel-specific PHPStan extensions for strict static analysis
• rector/rector + driftingly/rector-laravel — Automated refactoring with Laravel-aware rules
• laravel/pint — Opinionated PHP code formatter
• pestphp/pest — Testing framework
• pestphp/pest-plugin-laravel — Pest integration with Laravel
• pestphp/pest-plugin-type-coverage — Ensures strict type coverage targets
• pestphp/pest-plugin-browser — Browser testing support (Playwright)
• mockery/mockery — Mocks/stubs for tests
• nunomaduro/collision — Improved error reporting in CLI
• fakerphp/faker — Data factories/testing helpers
• laravel/pail — Colorful, interactive log viewer for local dev

Project Structure Highlights

• DTOs and Enums provide strong typing for requests and domain data.
• Repositories encapsulate data access and aggregate queries.
• Structured logging centralizes operational telemetry.
• Transaction locking ensures idempotency in concurrent environments.

You should see 100% type coverage, unit tests meeting the configured coverage threshold, and all quality checks passing.