Download the PHP package codebar-ag/laravel-m-files without Composer

Laravel M-Files Integration

A Laravel package providing DTOs and requests for integrating with M-Files REST API.

Installation

You can install the package via composer:

Requirements

PHP and Laravel compatibility

Install a package version whose row matches your application’s PHP and Laravel versions. The current major release is v13.x (see Packagist for the exact tag).

Configuration

Publish the configuration file:

Add your M-Files authentication credentials to your .env file:

Configuration Options

The package supports the following configuration options:

• M_FILES_URL - Your M-Files server URL
• M_FILES_USERNAME - Your M-Files username
• M_FILES_PASSWORD - Your M-Files password
• M_FILES_VAULT_GUID - The vault GUID to connect to
• M_FILES_CACHE_DRIVER - Cache driver for storing authentication tokens (defaults to CACHE_DRIVER, then file)
• M_FILES_EXPIRATION_SECONDS - How long to cache the vault authentication token, in seconds (default: 3600)
• M_FILES_SESSION_ID - Optional; sets config('m-files.auth.session_id') (not used by the package’s built-in connector/requests; available for your own integrations)

Transport Options

The m-files.http config block controls timeouts and retries:

• M_FILES_CONNECT_TIMEOUT - Seconds to wait for the connection to be established (default: 10)
• M_FILES_TIMEOUT - Seconds to wait for the complete response (default: 60)
• M_FILES_TRIES - Maximum number of attempts per request (default: 3)
• M_FILES_RETRY_INTERVAL_MS - Base delay between attempts in milliseconds, grown exponentially (default: 500)

Without the timeouts Guzzle waits indefinitely, so a single unresponsive vault can pin every PHP worker in the pool.

Retries are deliberately conservative — only failures that are safe to replay are retried: connection errors, 408, 429, 503, and 5xx only on idempotent methods (GET, HEAD, OPTIONS). A document-creating POST is never sent twice. On a 401 the cached authentication token is dropped and re-fetched automatically, which covers a vault that expired or restarted the session before the cache TTL lapsed; genuinely bad credentials still fail fast. Set M_FILES_TRIES to 1 to disable retries entirely.

Authentication

The package provides automatic authentication token management with caching support.

M-Files Connector

How the connector authenticates

Authentication is handled automatically by the MFilesConnector. When you create a connector instance with your credentials, it will automatically:

1. Cache authentication tokens - Tokens are cached for M_FILES_EXPIRATION_SECONDS / config('m-files.auth.expiration') (default 3600 seconds), or the tokenTtlSeconds argument on ConfigWithCredentials
2. Include authentication headers - The X-Authentication header is automatically added to all requests
3. Handle token refresh - When the cache entry expires, a new token is obtained on the next request

You can optionally inject a CacheKeyManager for tests or custom cache wiring: new MFilesConnector(configuration: $config, cacheKeyManager: $manager).

Cache and production security

• Auth tokens are stored in your configured Laravel cache store. Use a private backend in production (not a shared public cache).
• Cache keys incorporate a hash of connection parameters (including credentials). For multi-tenant apps, avoid sharing one cache namespace across tenants; prefer per-tenant key prefixes or separate Redis databases where applicable.

Requests

Authentication Requests

LogInToVaultRequest

Gets an authentication token using username/password credentials.

Constructor Parameters:

• url (string) - M-Files server URL
• vaultGuid (string) - Vault GUID
• username (string) - M-Files username
• password (string) - M-Files password

Request:

Response:

File Requests

UploadFileRequest

Uploads a file to M-Files.

Constructor Parameters:

• fileContent (string) - File content
• fileName (string) - File name

Request:

Response:

CreateSingleFileDocumentRequest

Creates a single file document in M-Files.

Constructor Parameters:

• title (string) - Document title
• files (array) - A single uploaded file information array, or a list of them
• propertyValues (array) - Array of SetProperty objects for custom properties

Request:

Both shapes are accepted for files: a single upload-info array (files: $uploadedFile) and a list of them (files: [$uploadedFile]). Passing several entries creates a multi-file document:

Response:

With Custom Property Values:

DownloadFileRequest

Downloads a file from M-Files.

Constructor Parameters:

• objectType (int) - Object type ID
• objectId (int) - Object ID
• objectVersion (int) - Object version
• fileId (int) - File ID

Request:

Response:

Property Requests

GetObjectInformationRequest

Retrieves object information and properties from M-Files.

Constructor Parameters:

• objectType (int) - Object type ID
• objectId (int) - Object ID
• objectVersion (int) - Object version

Request:

Response:

SetPropertiesRequest

Sets properties for an existing object in M-Files.

Constructor Parameters:

• objectType (int) - Object type ID
• objectId (int) - Object ID
• objectVersion (int) - Object version (-1 for latest)
• propertyValues (array) - Array of SetProperty objects

Request:

Response:

Error Handling

Every failure surfaces as a single exception, CodebarAg\MFiles\Exceptions\MFilesErrorException — including responses that are not JSON at all (an HTML error page from a reverse proxy or gateway, which previously escaped as a JsonException).

DTOs

Configuration DTOs

ConfigWithCredentials

Represents M-Files configuration with authentication credentials.

Properties:

• url (string) - M-Files server URL
• vaultGuid (string) - Vault GUID
• username (string) - M-Files username
• password (string) - M-Files password
• cacheDriver (string|null) - Cache store name for tokens (see M_FILES_CACHE_DRIVER / config('m-files.cache_driver'))
• tokenTtlSeconds (int) - Cache TTL for the vault token in seconds (default 3600; must be ≥ 1)

Methods:

• fromArray(array $data): self - Builds from an array; requires a Laravel app context so config('m-files.*') defaults apply for omitted cacheDriver / tokenTtlSeconds. Required keys: url, vaultGuid, username, password (each a non-empty string). Throws InvalidArgumentException if validation fails.
• toArray(): array - Converts to array format (includes tokenTtlSeconds)

Usage:

File DTOs

File

Represents a file in M-Files.

Properties:

• id (int) - File ID
• name (string) - File name
• extension (string|null) - File extension
• version (int|null) - File version
• size (int|null) - File size in bytes

Methods:

• fromArray(array $data): self - Static factory method
• toArray(): array - Converts to array format

Usage:

DownloadedFile

Represents a downloaded file with content and metadata.

Properties:

• name (string|null) - File name
• extension (string|null) - File extension
• size (int|null) - File size in bytes
• contentType (string|null) - MIME content type
• content (string) - File content

Methods:

• fromArray(array $data): self - Static factory method
• toArray(): array - Converts to array format

Usage:

Property DTOs

SetProperty

Represents a property value for creating documents.

Properties:

• propertyDef (int) - Property definition ID
• dataType (MFDataTypeEnum) - Property data type
• value (mixed) - Property value
• displayValue (mixed) - Display value (optional)

Methods:

• fromArray(int $propertyDef, MFDataTypeEnum $dataType, mixed $value, mixed $displayValue = null): self - Static factory method
• toArray(): array - Converts to array format for API requests

Usage:

GetProperty

Represents a property retrieved from M-Files.

Properties:

• propertyDef (int) - Property definition ID
• dataType (MFDataTypeEnum) - Property data type
• value (mixed) - Property value
• displayValue (mixed) - Display value

Methods:

• fromArray(array $data): self - Static factory method
• toArray(): array - Converts to array format

Usage:

ObjectProperties

Represents object properties in M-Files.

Properties:

• classId (int) - Class ID
• objectId (int) - Object ID
• objectTypeId (int) - Object type ID
• objectVersionId (int) - Object version ID
• lastModifiedAt (CarbonImmutable) - Last modified timestamp
• properties (Collection) - Collection of GetProperty objects
• files (Collection) - Collection of File objects

Methods:

• fromArray(array $data): self - Static factory method
• toArray(): array - Converts to array format

Usage:

Enums

MFDataTypeEnum

Represents data types in M-Files.

Available Values:

• UNINITIALIZED (0) - Document/Object
• TEXT (1) - Text
• INTEGER (2) - A 32-bit integer
• FLOATING (3) - A double-precision floating point
• DATE (5) - Date
• TIME (6) - Time
• TIMESTAMP (7) - Timestamp
• BOOLEAN (8) - Boolean
• LOOKUP (9) - Lookup (from a value list)
• MULTISELECTLOOKUP (10) - Multiple selection from a value list
• INTEGER64 (11) - A 64-bit integer
• FILETIME (12) - FILETIME (a 64-bit integer)
• MULTILINETEXT (13) - Multi-line text
• ACL (14) - The access control list (ACL)

Usage:

Testing

composer test runs Pest with --no-coverage so the suite passes without PCOV or Xdebug (PHPUnit is configured with failOnWarning="true", and missing a coverage driver would otherwise fail the run).

Static analysis:

To generate a coverage report locally, install and enable PCOV or Xdebug, then run:

On GitHub Actions, the run-tests workflow runs the matrix with --no-coverage and includes a coverage job (PHP 8.5 + PCOV) that writes Clover output and uploads it as a workflow artifact.

Changelog

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

Contributing

Open a pull request or issue on GitHub. Please run composer test and composer analyse before submitting.

Security

Operational notes on caching and credentials are described under Cache and production security.

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

Credits

• Codebar Solutions AG
• All Contributors

License

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