zahidaramai/laravel-myinvois-middleware

Laravel client SDK for the MyInvois Middleware Gateway (MyInvois API 1.0). Provides clean PHP integration layer for submitting e-invoices, sessions, submissions, status polling, and TIN validation via Zahid Aramai's MyInvois Middleware.

dev-main 2025-12-27 14:51 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0
• illuminate/support: ^10.0|^11.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Zahid Aramai

• sdk
• middleware
• laravel
• Malaysia
• E-Invoice
• lhdn
• myinvois

README

Laravel client SDK for the MyInvois Middleware Gateway (MyInvois API 1.0). Provides a clean PHP integration layer for submitting e-invoices, managing sessions, tracking submissions, polling status, and validating TINs via Zahid Aramai's MyInvois Middleware.

Features

• Simple and intuitive API for MyInvois operations
• Facade and dependency injection support
• Configurable via environment variables
• Zero business logic duplication - purely a middleware client
• Full support for Laravel 10 and 11
• Auto-discovery ready

Requirements

• PHP 8.1 or higher
• Laravel 10.x or 11.x
• Guzzle HTTP 7.x

Installation

Install the package via Composer:

composer require zahidaramai/laravel-myinvois-middleware

The package will auto-register its service provider and facade.

Publish Configuration

Publish the configuration file:

php artisan vendor:publish --tag=myinvois-config

This will create a config/myinvois.php file in your application.

Configuration

Add the following environment variables to your .env file:

MYINVOIS_MIDDLEWARE_BASE_URL=https://your-middleware-server.com
MYINVOIS_MIDDLEWARE_API_KEY=your-api-key-here
MYINVOIS_MIDDLEWARE_TIMEOUT=30
MYINVOIS_MIDDLEWARE_CONNECT_TIMEOUT=10
MYINVOIS_MIDDLEWARE_VERIFY_SSL=true

Configuration Options

Variable	Description	Default
MYINVOIS_MIDDLEWARE_BASE_URL	Base URL of your MyInvois Middleware Gateway	http://localhost:8000
MYINVOIS_MIDDLEWARE_API_KEY	API key for authentication	null
MYINVOIS_MIDDLEWARE_TIMEOUT	Request timeout in seconds	30
MYINVOIS_MIDDLEWARE_CONNECT_TIMEOUT	Connection timeout in seconds	10
MYINVOIS_MIDDLEWARE_VERIFY_SSL	Verify SSL certificates	true

Usage

Using the Facade

use ZahidAramai\MyInvoisMiddleware\Facades\MyInvois;

// Create a session
$session = MyInvois::createSession();

// Submit documents (e-invoices)
$documents = [
    [
        'type' => 'invoice',
        'data' => [
            'invoiceNumber' => 'INV-001',
            'amount' => 1000.00,
            // ... other invoice fields
        ],
    ],
];

$submission = MyInvois::submitDocuments($documents);

// Get submission status
$status = MyInvois::getSubmission($submission['submission_id']);

// Validate a TIN
$validation = MyInvois::validateTin(
    tin: 'C12345678901',
    idType: 'BRN',
    idValue: '202001012345'
);

// Get all submissions with filters
$submissions = MyInvois::getSubmissions([
    'status' => 'completed',
    'page' => 1,
]);

// Cancel a document
$result = MyInvois::cancelDocument('document-uuid', 'Customer requested cancellation');

Using Dependency Injection

use ZahidAramai\MyInvoisMiddleware\MyInvoisClient;

class InvoiceController extends Controller
{
    public function __construct(
        protected MyInvoisClient $myInvois
    ) {}

    public function submit(Request $request)
    {
        $documents = $this->prepareDocuments($request);

        $result = $this->myInvois->submitDocuments($documents);

        return response()->json([
            'submission_id' => $result['submission_id'],
            'status' => $result['status'],
        ]);
    }

    public function status(string $submissionId)
    {
        $status = $this->myInvois->getSubmission($submissionId);

        return response()->json($status);
    }
}

Available Methods

Method	Description
createSession(array $params = [])	Create a new session with the middleware
submitDocuments(array $documents, array $options = [])	Submit e-invoices for processing
getSubmission(string $submissionId, array $queryParams = [])	Get status of a specific submission
getSubmissions(array $filters = [])	List submissions with optional filters
validateTin(string $tin, string $idType, string $idValue)	Validate a Tax Identification Number
getDocument(string $submissionId, string $documentId)	Get a specific document details
cancelDocument(string $documentId, string $reason)	Cancel a submitted document
getHttpClient()	Get the underlying Guzzle HTTP client

Error Handling

The client throws Guzzle exceptions for HTTP errors. Handle them appropriately:

use GuzzleHttp\Exception\ClientException;
use GuzzleHttp\Exception\ServerException;
use ZahidAramai\MyInvoisMiddleware\Facades\MyInvois;

try {
    $result = MyInvois::submitDocuments($documents);
} catch (ClientException $e) {
    // 4xx errors - client-side issue
    $response = $e->getResponse();
    $body = json_decode($response->getBody()->getContents(), true);

    Log::error('MyInvois client error', [
        'status' => $response->getStatusCode(),
        'body' => $body,
    ]);
} catch (ServerException $e) {
    // 5xx errors - server-side issue
    Log::error('MyInvois server error', [
        'message' => $e->getMessage(),
    ]);
}

Testing

Run the test suite:

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Zahid Aramai
• All Contributors

License

The MIT License (MIT). Please see License File for more information.