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:

composer require codebar-ag/laravel-m-files

Requirements

PHP and Laravel compatibility

Package release	PHP (Composer constraint)	Laravel
v13.x	`8.3.\|8.4.\|8.5.*`	^13.0
v12.x	`8.2.\|8.3.\|8.4.*`	^12.0

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:

php artisan vendor:publish --provider="CodebarAg\MFiles\MFilesServiceProvider"

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

M_FILES_URL=https://your-mfiles-server.com
M_FILES_USERNAME=your-username
M_FILES_PASSWORD=your-password
M_FILES_VAULT_GUID=ABC0DE2G-3HW-QWCQ-SDF3-WERWETWETW
M_FILES_CACHE_DRIVER=file
M_FILES_EXPIRATION_SECONDS=3600
# M_FILES_SESSION_ID=   # optional; exposed as config('m-files.auth.session_id') for custom use
# M_FILES_CONNECT_TIMEOUT=10
# M_FILES_TIMEOUT=60
# M_FILES_TRIES=3
# M_FILES_RETRY_INTERVAL_MS=500

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

use CodebarAg\MFiles\Connectors\MFilesConnector;
use CodebarAg\MFiles\DTO\ConfigWithCredentials;

$config = new ConfigWithCredentials(
    url: 'https://your-mfiles-server.com',
    vaultGuid: '{ABC0DE2G-3HW-QWCQ-SDF3-WERWETWETW}',
    username: 'your-username',
    password: 'your-password',
    cacheDriver: 'file',
    tokenTtlSeconds: 3600,
);

$connector = new MFilesConnector(configuration: $config);

How the connector authenticates

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

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
Include authentication headers - The X-Authentication header is automatically added to all requests
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.

use CodebarAg\MFiles\Requests\LogInToVaultRequest;

// Manual authentication (if needed)
$request = new LogInToVaultRequest(
    url: 'https://your-mfiles-server.com',
    vaultGuid: '{ABC0DE2G-3HW-QWCQ-SDF3-WERWETWETW}',
    username: 'your-username',
    password: 'your-password',
);

$token = $request->send()->dto();
// Returns authentication token as string

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:

use CodebarAg\MFiles\Requests\LogInToVaultRequest;

$request = new LogInToVaultRequest(
    url: 'https://your-mfiles-server.com',
    vaultGuid: '{ABC0DE2G-3HW-QWCQ-SDF3-WERWETWETW}',
    username: 'your-username',
    password: 'your-password',
);

Response:

$token = $request->send()->dto();
// Returns authentication token as string

File Requests

UploadFileRequest

Uploads a file to M-Files.

Constructor Parameters:

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

Request:

use CodebarAg\MFiles\Requests\UploadFileRequest;

$request = new UploadFileRequest(
    fileContent: $fileContent,
    fileName: 'document.pdf'
);

Response:

$uploadedFile = $connector->send($request)->dto();
// Returns array with file information including Title, Extension, and other metadata

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:

use CodebarAg\MFiles\Requests\CreateSingleFileDocumentRequest;
use CodebarAg\MFiles\DTO\SetProperty;
use CodebarAg\MFiles\Enums\MFDataTypeEnum;

$request = new CreateSingleFileDocumentRequest(
    title: 'My Document',
    files: [$uploadedFile]
);

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:

$request = new CreateSingleFileDocumentRequest(
    title: 'My Document',
    files: [$firstUploadedFile, $secondUploadedFile]
);

Response:

use CodebarAg\MFiles\DTO\ObjectProperties;

$document = $connector->send($request)->dto();
// Returns ObjectProperties DTO with document information

With Custom Property Values:

$propertyValues = [
    new SetProperty(propertyDef: 0, dataType: MFDataTypeEnum::TEXT, value: 'Custom Title'),
    new SetProperty(propertyDef: 5, dataType: MFDataTypeEnum::DATE, value: '2024-01-01'),
];

$request = new CreateSingleFileDocumentRequest(
    title: 'Custom Document',
    files: [$uploadedFile],
    propertyValues: $propertyValues
);

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:

use CodebarAg\MFiles\Requests\DownloadFileRequest;

$request = new DownloadFileRequest(
    objectType: 0,
    objectId: 123,
    objectVersion: 1,
    fileId: 456
);

Response:

use CodebarAg\MFiles\DTO\DownloadedFile;

$downloadedFile = $connector->send($request)->dto();
// Returns DownloadedFile DTO with content, name, extension, size, contentType

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:

use CodebarAg\MFiles\Requests\GetObjectInformationRequest;

$request = new GetObjectInformationRequest(
    objectType: 0,
    objectId: 123,
    objectVersion: 1
);

Response:

use CodebarAg\MFiles\DTO\ObjectProperties;

$objectProperties = $connector->send($request)->dto();
// Returns ObjectProperties DTO with object information and properties

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:

use CodebarAg\MFiles\Requests\SetPropertiesRequest;
use CodebarAg\MFiles\DTO\SetProperty;
use CodebarAg\MFiles\Enums\MFDataTypeEnum;

$propertyValues = [
    new SetProperty(1856, MFDataTypeEnum::BOOLEAN, true),
    new SetProperty(0, MFDataTypeEnum::TEXT, 'Updated Title'),
];

$request = new SetPropertiesRequest(
    objectType: 140,
    objectId: 1770,
    objectVersion: -1,
    propertyValues: $propertyValues
);

Response:

use CodebarAg\MFiles\DTO\ObjectProperties;

$objectProperties = $connector->send($request)->dto();
// Returns ObjectProperties DTO with updated object information

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).

use CodebarAg\MFiles\Exceptions\MFilesErrorException;

try {
    $document = $connector->send($request)->dto();
} catch (MFilesErrorException $e) {
    $e->getMessage();               // The message exactly as M-Files reported it
    $e->status();                   // HTTP status, or 0 when it could not be determined
    $e->errorCode();                // M-Files error code, or null when the payload carried none
    $e->isAuthenticationFailure();  // true for 401 / 403
    $e->context();                  // Single-line summary for logs: status, exception name, code, method and URL
    $e->error;                      // The underlying MFilesError DTO (errorCode, status, url, method, exceptionName, exceptionMessage, stack)
}

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:

use CodebarAg\MFiles\DTO\ConfigWithCredentials;

$config = new ConfigWithCredentials(
    url: 'https://your-mfiles-server.com',
    vaultGuid: '{ABC0DE2G-3HW-QWCQ-SDF3-WERWETWETW}',
    username: 'your-username',
    password: 'your-password',
    cacheDriver: 'file',
    tokenTtlSeconds: 3600,
);

// Using static factory method (inside a Laravel application)
$config = ConfigWithCredentials::fromArray([
    'url' => 'https://your-mfiles-server.com',
    'vaultGuid' => '{ABC0DE2G-3HW-QWCQ-SDF3-WERWETWETW}',
    'username' => 'your-username',
    'password' => 'your-password',
    'cacheDriver' => 'file',
    'tokenTtlSeconds' => 3600,
]);

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:

use CodebarAg\MFiles\DTO\File;

$file = new File(
    id: 456,
    name: 'document.pdf',
    extension: 'pdf',
    version: 1,
    size: 1024
);

// Using static factory method
$file = File::fromArray([
    'ID' => 456,
    'Name' => 'document.pdf',
    'Extension' => 'pdf',
    'Version' => 1,
    'Size' => 1024
]);

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:

use CodebarAg\MFiles\DTO\DownloadedFile;

$downloadedFile = new DownloadedFile(
    name: 'document.pdf',
    extension: 'pdf',
    size: 1024,
    contentType: 'application/pdf',
    content: $fileContent
);

// Using static factory method
$downloadedFile = DownloadedFile::fromArray([
    'name' => 'document.pdf',
    'extension' => 'pdf',
    'size' => 1024,
    'contentType' => 'application/pdf',
    'content' => $fileContent
]);

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:

use CodebarAg\MFiles\DTO\SetProperty;
use CodebarAg\MFiles\Enums\MFDataTypeEnum;

$propertyValue = new SetProperty(
    propertyDef: 0,
    dataType: MFDataTypeEnum::TEXT,
    value: 'Sample Text'
);

// Using static factory method
$propertyValue = SetProperty::fromArray(
    propertyDef: 0,
    dataType: MFDataTypeEnum::TEXT,
    value: 'Sample Text'
);

// Convert to array for API requests
$array = $propertyValue->toArray();

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:

use CodebarAg\MFiles\DTO\GetProperty;

$property = GetProperty::fromArray([
    'PropertyDef' => 0,
    'Value' => [
        'DataType' => 1,
        'Value' => 'Sample Text',
        'DisplayValue' => 'Sample Text'
    ]
]);

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:

use CodebarAg\MFiles\DTO\ObjectProperties;

$objectProperties = ObjectProperties::fromArray([
    'Class' => 1,
    'ObjVer' => [
        'ID' => 123,
        'Type' => 0,
        'Version' => 1,
        'Modified' => '2024-01-01T00:00:00Z'
    ],
    'Properties' => [],
    'Files' => []
]);

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:

use CodebarAg\MFiles\Enums\MFDataTypeEnum;

$dataType = MFDataTypeEnum::TEXT;
$dataTypeValue = $dataType->value; // 1

Testing

composer test

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:

composer analyse

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

composer test-coverage

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 security@codebar.ch instead of using the issue tracker.

Credits

License

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

Name		Name	Last commit message	Last commit date
.github		.github
config		config
src		src
tests		tests
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE.md		LICENSE.md
README.md		README.md
composer.json		composer.json
phpstan-baseline.neon		phpstan-baseline.neon
phpstan.neon.dist		phpstan.neon.dist
phpunit.xml.dist		phpunit.xml.dist

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Laravel M-Files Integration

Installation

Requirements

PHP and Laravel compatibility

Configuration

Configuration Options

Transport Options

Authentication

M-Files Connector

How the connector authenticates

Cache and production security

Requests

Authentication Requests

LogInToVaultRequest

File Requests

UploadFileRequest

CreateSingleFileDocumentRequest

DownloadFileRequest

Property Requests

GetObjectInformationRequest

SetPropertiesRequest

Error Handling

DTOs

Configuration DTOs

ConfigWithCredentials

File DTOs

File

DownloadedFile

Property DTOs

SetProperty

GetProperty

ObjectProperties

Enums

MFDataTypeEnum

Testing

Changelog

Contributing

Security

Credits

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages