KMP PHP API Reference

DocumentService
in package
uses LocatorAwareTrait

Centralized document management service for file uploads, storage, and retrieval.

Uses Flysystem to abstract storage operations across local filesystem, Azure Blob Storage, and S3. Configuration via 'Documents' key in config/app_local.php.

Tags
see
ServiceResult

Standard service result pattern

Table of Contents

Constants

STORAGE_BASE_PATH  = 'images/uploaded/'
Base storage path for uploaded documents (for local adapter)

Properties

$adapter  : string
Storage adapter type ('local', 'azure', or 's3')
$Documents  : DocumentsTable
Documents table instance
$filesystem  : Filesystem
Flysystem filesystem instance
$localBasePath  : string|null
Base path for local storage

Methods

__construct()  : mixed
Constructor - initializes Flysystem with configured adapter
createDocument()  : ServiceResult
Create a document from an uploaded file
deleteDocument()  : ServiceResult
Delete a document and its associated file
documentPreviewExists()  : bool
Determine whether a JPEG preview exists for the provided document.
getDocumentDownloadResponse()  : Response|null
Get a download response for a document
getDocumentInlineResponse()  : Response|null
Get an inline response for a document (suitable for iframe/object embedding).
getDocumentPreviewResponse()  : Response|null
Get an inline preview response for a document's generated JPEG preview.
updateDocumentEntityId()  : ServiceResult
Update the entity_id of an existing document
generateUniqueFilename()  : string
Generate a unique filename for storage
getFilesystemForAdapter()  : Filesystem|null
Get a filesystem instance for a specific storage adapter
handleUploadError()  : ServiceResult
Handle upload errors and return appropriate ServiceResult
initializeFilesystem()  : void
Initialize Flysystem with the configured storage adapter
initializeLocalAdapter()  : void
Initialize local filesystem adapter
sanitizePath()  : string
Sanitize file path to prevent directory traversal attacks
savePreviewFromTemp()  : ServiceResult
Persist a temporary preview image into the configured storage adapter.

Constants

STORAGE_BASE_PATH

Base storage path for uploaded documents (for local adapter)

private mixed STORAGE_BASE_PATH = 'images/uploaded/'

Properties

$adapter

Storage adapter type ('local', 'azure', or 's3')

private string $adapter

$filesystem

Flysystem filesystem instance

private Filesystem $filesystem

$localBasePath

Base path for local storage

private string|null $localBasePath = null

Methods

__construct()

Constructor - initializes Flysystem with configured adapter

public __construct() : mixed

createDocument()

Create a document from an uploaded file

public createDocument(UploadedFile $file, string $entityType, int $entityId, int $uploadedBy[, array<string|int, mixed> $metadata = [] ][, string $subDirectory = '' ][, array<string|int, mixed> $allowedExtensions = ['pdf'] ][, string|null $previewTempPath = null ]) : ServiceResult

This method handles the complete document creation workflow:

  1. Validates the uploaded file
  2. Generates a unique storage filename
  3. Stores the physical file
  4. Creates the document database record
  5. Returns the document ID
Parameters
$file : UploadedFile

The uploaded file object

$entityType : string

The entity type (e.g., 'Waivers.WaiverTypes')

$entityId : int

The entity ID this document belongs to

$uploadedBy : int

The member ID who uploaded the file

$metadata : array<string|int, mixed> = []

Optional metadata to store with the document

$subDirectory : string = ''

Optional subdirectory within storage base (e.g., 'waiver-templates')

$allowedExtensions : array<string|int, mixed> = ['pdf']

Optional array of allowed file extensions (default: ['pdf'])

$previewTempPath : string|null = null

Optional path to a temporary JPEG preview to store alongside the document

Return values
ServiceResult —

Success with document ID, or failure with error message

deleteDocument()

Delete a document and its associated file

public deleteDocument(int $documentId) : ServiceResult

This method deletes both the physical file and the database record. It uses the storage_adapter field from the document record to determine which storage backend to use for file deletion.

Parameters
$documentId : int

The document ID to delete

Return values
ServiceResult —

Success or failure

documentPreviewExists()

Determine whether a JPEG preview exists for the provided document.

public documentPreviewExists(Document $document) : bool
Parameters
$document : Document

Document entity reference

Return values
bool —

True when preview file can be located, otherwise false

getDocumentDownloadResponse()

Get a download response for a document

public getDocumentDownloadResponse(Document $document[, string|null $downloadName = null ]) : Response|null

This method handles file retrieval and response generation for downloading documents. It supports both local filesystem and remote storage (Azure Blob Storage, etc) via Flysystem. The method uses the storage_adapter field from the document record to determine which storage backend to use, allowing documents stored with different adapters to coexist.

Parameters
$document : Document

The document entity

$downloadName : string|null = null

Optional custom filename for download

Return values
Response|null —

Response with file, or null on error

getDocumentInlineResponse()

Get an inline response for a document (suitable for iframe/object embedding).

public getDocumentInlineResponse(Document $document[, string|null $inlineName = null ]) : Response|null
Parameters
$document : Document

The document entity

$inlineName : string|null = null

Optional custom filename for inline disposition

Return values
Response|null —

Response with file, or null on error

getDocumentPreviewResponse()

Get an inline preview response for a document's generated JPEG preview.

public getDocumentPreviewResponse(Document $document) : Response|null
Parameters
$document : Document

Document entity with stored file path

Return values
Response|null —

Response streaming the preview image, or null if unavailable

updateDocumentEntityId()

Update the entity_id of an existing document

public updateDocumentEntityId(int $documentId, int $entityId) : ServiceResult

This is useful when you need to save the parent entity first to get its ID, then update the document's entity_id reference.

Parameters
$documentId : int

The document ID to update

$entityId : int

The new entity ID

Return values
ServiceResult —

Success or failure

generateUniqueFilename()

Generate a unique filename for storage

private generateUniqueFilename(string $extension) : string
Parameters
$extension : string

File extension

Return values
string —

Unique filename

getFilesystemForAdapter()

Get a filesystem instance for a specific storage adapter

private getFilesystemForAdapter(string $adapterType) : Filesystem|null

This method creates a Flysystem instance configured for the specified adapter type. Used when retrieving files that may have been stored with a different adapter than the currently configured one.

Parameters
$adapterType : string

The storage adapter type ('local', 'azure', or 's3')

Return values
Filesystem|null —

Filesystem instance or null on error

handleUploadError()

Handle upload errors and return appropriate ServiceResult

private handleUploadError(int $errorCode) : ServiceResult
Parameters
$errorCode : int

PHP upload error code

Return values
ServiceResult

initializeFilesystem()

Initialize Flysystem with the configured storage adapter

private initializeFilesystem() : void

initializeLocalAdapter()

Initialize local filesystem adapter

private initializeLocalAdapter() : void
Tags
throws
RuntimeException

If storage directory cannot be created or is not writable

sanitizePath()

Sanitize file path to prevent directory traversal attacks

private sanitizePath(string $path) : string
Parameters
$path : string

The path to sanitize

Return values
string —

Sanitized path

savePreviewFromTemp()

Persist a temporary preview image into the configured storage adapter.

private savePreviewFromTemp(string $relativePdfPath, string $tempPreviewPath) : ServiceResult
Parameters
$relativePdfPath : string

Relative path of stored PDF, used to derive preview path

$tempPreviewPath : string

Temporary JPEG path produced during conversion

Tags
@return

\App\Services\ServiceResult Result indicating success and stored preview path

Return values
ServiceResult 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results