impact-factoring/documents-client

Laravel client for consuming Impact Factoring Documents Server

1.0.1 2025-08-01 09:00 UTC

Requires

• illuminate/cookie: ^11.0 || ^12.0
• illuminate/http: ^11.0 || ^12.0
• illuminate/support: ^11.0 || ^12.0

Requires (Dev)

• ext-http: *
• orchestra/testbench: ^9.0 || 10.0
• phpunit/phpunit: ^10.0

MIT

• Daniel van der Wal

README

This package provides a custom Laravel Storage disk named impact-factoring-documents, which integrates with the League\Flysystem abstraction.

Once installed, the adapter is registered automatically and ready to use — no setup required.

Accounts Context Middleware

The package registers a middleware (SetUserContext) that automatically sets the current accounts_id based on the authenticated user or request input.

This context is required for all API interactions and is injected during the Laravel request lifecycle.

How It Works

Under the hood, this driver communicates with the Impact Factoring Documents Server via API requests. It does not store or retrieve documents by file path, but by a document ID returned by the API.

Usage

⚠️ Important: All operations are based on document IDs, not paths or filenames. The document ID is returned when a file is uploaded via the client.

Get a document (contents or stream)

use Illuminate\Support\Facades\Storage;

$content = Storage::disk('impact-factoring-documents')->get($documentId);
$stream = Storage::disk('impact-factoring-documents')->readStream($documentId);

Check if a document exists

use Illuminate\Support\Facades\Storage;

$exists = Storage::disk('impact-factoring-documents')->exists($documentId);

Upload a document

use ImpactFactoring\Documents\Helper\DocumentsStorage

/**
* @var \Illuminate\Http\UploadedFile $file
 */
$documentId = DocumentsStorage::upload($file)

Update a document

use ImpactFactoring\Documents\Helper\DocumentsStorage

/**
* @var \Illuminate\Http\UploadedFile $file
 */
$documentId = DocumentsStorage::upload($file, $existingDocumentId)

Get metadata (size, mime type, last modified)

These methods depend on the document server returning standard HTTP headers:

• Content-Length
• Content-Type
• Last-Modified

use Illuminate\Support\Facades\Storage;

Storage::disk('impact-factoring-documents')->size($documentId);
Storage::disk('impact-factoring-documents')->mimeType($documentId);
Storage::disk('impact-factoring-documents')->lastModified($documentId);

If any required header is missing, an exception will be thrown (e.g., UnableToRetrieveMetadata).

Delete a document

use Illuminate\Support\Facades\Storage;

Storage::disk('impact-factoring-documents')->delete($documentId);

Not Supported

The following operations are not supported by this adapter and will throw a RuntimeException if used:

• put(), write(), writeStream() – > Uploading is only possible via the ImpactFactoring\Documents\Helper\DocumentsStorage::upload() method.

• createDirectory(), deleteDirectory()

• listContents()
• move(), copy()
• visibility() or setVisibility()

Why Use This Storage Adapter?

This adapter allows you to treat the Documents API as a file system in a limited, read-focused way. You can inject it wherever Laravel expects a Storage disk — for example, in controllers, jobs, or services — and read/delete documents by ID.

For full upload/update functionality, use the provided helper (ImpactFactoring\Documents\Helper\DocumentsStorage::upload())

Impact Factoring Documents Client

⚠️ It's not recommended to use this client directly. The preferred way is to use the storage driver together with the helper service.

A Laravel client package for interacting with the Impact Factoring Documents Server API.
Supports uploading, downloading, updating, and deleting documents using OAuth2 client credentials authentication.

Installation

Install via Composer:

composer require impact-factoring/documents-client

(Optional) Publish the config file if you want to customize the defaults:

php artisan vendor:publish --provider="ImpactFactoring\Documents\DocumentsClientServiceProvider" --tag="config"

Configuration

Configure the package by setting the following variables in your .env:

IMPACT_FACTORING_DOCUMENTS_BASE_URL=your-local-documents-server
IMPACT_FACTORING_DOCUMENTS_CLIENT_ID=your-client-id
IMPACT_FACTORING_DOCUMENTS_CLIENT_SECRET=your-client-secret
IMPACT_FACTORING_DOCUMENTS_APP_SCOPE=your-app-scope

Usage

You can resolve the client via dependency injection or instantiate it directly:

use ImpactFactoring\Documents\Client\ImpactFactoringDocumentsClient;

$client = new ImpactFactoringDocumentsClient();

Upload a document

use \ImpactFactoring\Documents\Client\ImpactFactoringDocumentsClient;

/**
 * @var Illuminate\Http\UploadedFile $file
 */
$response = new ImpactFactoringDocumentsClient()->upload(accountsId: 'accounts-id', file: $file);

if ($response->successful()) {
    $documentId = $response->json('id');
    // Handle success
}

Download a document

use \ImpactFactoring\Documents\Client\ImpactFactoringDocumentsClient;

$response = new ImpactFactoringDocumentsClient()->download(id: 'document-id');

// Returns a StreamedResponse, which you can return directly from your controller
return $response;

Update a document

use \ImpactFactoring\Documents\Client\ImpactFactoringDocumentsClient;

/**
 * @var Illuminate\Http\UploadedFile $file
 */
$response = new ImpactFactoringDocumentsClient()->update(documentId: 'document-id', accountsId: 'accounts-id', file: $file);

if ($response->successful()) {
    $documentId = $response->json('id');
    // Handle success
}

Deleting a document

use \ImpactFactoring\Documents\Client\ImpactFactoringDocumentsClient;

$response = new ImpactFactoringDocumentsClient()->delete(documentId: 'document-id', accountsId: 'accounts-id');

if ($response->successful()) {
    // Handle success
}

Testing

This package uses PHPUnit and Orchestra Testbench for testing. Run tests with:

composer test