codebar-ag / laravel-m-files
M-Files integration with Laravel
Requires
- php: 8.4.*
- guzzlehttp/guzzle: ^7.8
- illuminate/contracts: ^12.0
- nesbot/carbon: ^3.8
- saloonphp/cache-plugin: ^3.0
- saloonphp/laravel-plugin: ^3.0
- saloonphp/saloon: ^3.10.1
- spatie/laravel-package-tools: ^1.19
- spatie/laravel-ray: ^1.40
Requires (Dev)
- larastan/larastan: ^v3.1
- laravel/pint: ^1.21
- orchestra/testbench: ^10.0
- pestphp/pest: ^3.7
- phpstan/extension-installer: ^1.4
- phpstan/phpstan-deprecation-rules: ^2.0
- phpstan/phpstan-phpunit: ^2.0
README
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
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
Configuration Options
The package supports the following configuration options:
M_FILES_URL
- Your M-Files server URLM_FILES_USERNAME
- Your M-Files usernameM_FILES_PASSWORD
- Your M-Files passwordM_FILES_VAULT_GUID
- The vault GUID to connect toM_FILES_CACHE_DRIVER
- Cache driver for storing authentication tokens (default: file)
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' ); $connector = new MFilesConnector(config: $config);
Authentication
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 1 hour to avoid repeated login requests
- Include authentication headers - The
X-Authentication
header is automatically added to all requests - Handle token refresh - When tokens expire, new ones are automatically obtained
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 URLvaultGuid
(string) - Vault GUIDusername
(string) - M-Files usernamepassword
(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 contentfileName
(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 titlefiles
(array) - Array of uploaded file informationpropertyValues
(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] );
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 IDobjectId
(int) - Object IDobjectVersion
(int) - Object versionfileId
(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
DTOs
Configuration DTOs
ConfigWithCredentials
Represents M-Files configuration with authentication credentials.
Properties:
url
(string) - M-Files server URLvaultGuid
(string) - Vault GUIDusername
(string) - M-Files usernamepassword
(string) - M-Files passwordcacheDriver
(string|null) - Cache driver for tokens
Methods:
fromArray(array $data): self
- Static factory methodtoArray(): array
- Converts to array format
Usage:
use CodebarAg\MFiles\DTO\ConfigWithCredentials; $config = new ConfigWithCredentials( url: 'https://your-mfiles-server.com', username: 'your-username', password: 'your-password', vaultGuid: '{ABC0DE2G-3HW-QWCQ-SDF3-WERWETWETW}', cacheDriver: 'file' ); // Using static factory method $config = ConfigWithCredentials::fromArray([ 'url' => 'https://your-mfiles-server.com', 'username' => 'your-username', 'password' => 'your-password', 'vaultGuid' => '{ABC0DE2G-3HW-QWCQ-SDF3-WERWETWETW}', 'cacheDriver' => 'file' ]);
File DTOs
File
Represents a file in M-Files.
Properties:
id
(int) - File IDname
(string) - File nameextension
(string|null) - File extensionversion
(int|null) - File versionsize
(int|null) - File size in bytes
Methods:
fromArray(array $data): self
- Static factory methodtoArray(): 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 nameextension
(string|null) - File extensionsize
(int|null) - File size in bytescontentType
(string|null) - MIME content typecontent
(string) - File content
Methods:
fromArray(array $data): self
- Static factory methodtoArray(): 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 IDdataType
(MFDataTypeEnum) - Property data typevalue
(mixed) - Property valuedisplayValue
(mixed) - Display value (optional)
Methods:
fromArray(int $propertyDef, MFDataTypeEnum $dataType, mixed $value, mixed $displayValue = null): self
- Static factory methodtoArray(): 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 IDdataType
(MFDataTypeEnum) - Property data typevalue
(mixed) - Property valuedisplayValue
(mixed) - Display value
Methods:
fromArray(array $data): self
- Static factory methodtoArray(): 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 IDobjectId
(int) - Object IDobjectTypeId
(int) - Object type IDobjectVersionId
(int) - Object version IDlastModifiedAt
(CarbonImmutable) - Last modified timestampproperties
(Collection) - Collection of GetProperty objectsfiles
(Collection) - Collection of File objects
Methods:
fromArray(array $data): self
- Static factory methodtoArray(): 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/ObjectTEXT
(1) - TextINTEGER
(2) - A 32-bit integerFLOATING
(3) - A double-precision floating pointDATE
(5) - DateTIME
(6) - TimeTIMESTAMP
(7) - TimestampBOOLEAN
(8) - BooleanLOOKUP
(9) - Lookup (from a value list)MULTISELECTLOOKUP
(10) - Multiple selection from a value listINTEGER64
(11) - A 64-bit integerFILETIME
(12) - FILETIME (a 64-bit integer)MULTILINETEXT
(13) - Multi-line textACL
(14) - The access control list (ACL)
Usage:
use CodebarAg\MFiles\Enums\MFDataTypeEnum; $dataType = MFDataTypeEnum::TEXT; $dataTypeValue = $dataType->value; // 1
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
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.