README

Team

Lesterius is a European FileMaker Business Alliance Platinum member that operates in Belgium, France, the Netherlands, Portugal and Spain. We are creative business consultants who co-create FileMaker Platform based solutions with our customers.
Sharing knowledge takes part of our DNA, that's why we developed this library to make the FileMaker Data API easy-to-use with PHP.
Break the limits of your application!

Richard Carlton Consulting is a full-stack Claris FileMaker development consultancy, serving clients globally with any and all FileMaker-related needs. We also publish the largest and most complete video training course for the FileMaker Community.

Description

This library is a PHP wrapper for the Claris FileMaker Data API. It supports version 17/18/19 Data API commands, though if you use an 18 command (metadata commands for ex) on 17, it will fail.

You will be able to use every functions like it's documented in your FileMaker server Data Api documentation (accessible via https://[your server domain]/fmi/data/apidoc).

General FileMaker document on the FMS 17 Data API is available here

General FileMaker document on the FMS 18 Data API is available here

General FileMaker document on the FMS 19+ Data API is available here

Rationale

This fork is to bring greater out of the box compatibility to the myFMApiLibrary library vs the Lesterius upstream code. We're immensely grateful for the hard work Lesterius put in. Pull Requests welcome.

Requirements

Library version <2.1.0:

PHP >= 5.5
PHP cURL extension
PHP mbstring extension

Library version >=2.1.0:

PHP >= 7.1
PHP cURL extension
PHP mbstring extension

Library version >=3.0.0:

PHP >= 8.3
PHP cURL extension
PHP mbstring extension
Guzzle

Installation

The recommended way to install it is through Composer.

composer require rcconsulting/myfmapilibrary-for-php:\>=3.0.0

After installing, you need to notate that you'll use this library, and require Composer's autoloader:

use \RCConsulting\FileMakerApi\DataApi;
require_once __DIR__ . '/vendor/autoload.php';

Usage

Prepare your FileMaker solution

Enable the FileMaker Data API on your FileMaker Server Admin Console.
Create a user in your FileMaker database, with a custom privilege set that has at least the 'fmrest' extended privilege enabled
Define records & layouts access for this user

Use the library

Login

// Please note that the library does not currently support external data source authentication
$dataApi = new \RCConsulting\FileMakerApi\DataApi('https://test.fmconnection.com/fmi/data', 'MyDatabase');
$dataApi->login('filemaker api user', 'filemaker api password');

One-line example of Login with Credentials and all Options:

// Arguments: DAPI URL, Database Name, DAPI User, DAPI Password, SSL Verification Enabled?, Force Legacy HTTP 1.1?, Return Response Object?, HTTP Client Type?, Data API Version?
$dataApi = new \RCConsulting\FileMakerApi\DataApi('https://test.fmconnection.com/fmi/data','MyDatabase', "DAP_User", "DAPI_Pass_1234~", True, False, False, HttpClient::CURL, DapiVersion::V1);

// Please note that RCC has not tested OAuth logins. We welcome any PR's which improve support.
$dataApi = new \RCConsulting\FileMakerApi\DataApi('https://test.fmconnection.com/fmi/data', 'MyDatabase');
$dataApi->loginOauth('oAuthRequestId', 'oAuthIdentifier');

Logout

// It is highly recommended to log out at each script or large process end. The Data API tokens last 15 minutes after last use, and so will hold a slot open for 15 minutes after your last connection if you do not clean up after yourself. Additionally, logout() does not destroy the DataAPI object you created (via new) previously, but it does clean out any authorization tokens from the object.

$dataApi->logout();

HTTP Client Options

The library supports multiple HTTP client implementations through an abstraction layer. You can choose between cURL-based and Guzzle-based HTTP clients using either type-safe enumerations or backward-compatible strings.

Available HTTP Clients

CurlClient (Default)

Uses PHP's native cURL extension
Lightweight and fast
Default choice for backward compatibility

GuzzleClient

Uses the Guzzle HTTP client library
Better HTTP/2 support
Advanced features like middleware support
Better error handling and debugging capabilities

Usage Examples

Using HttpClientType Enumeration (Recommended):

use RCConsulting\FileMakerApi\DataApi;

// Using DataApi\HttpClientType::CURL (default)
$dataApi = new DataApi(
    'https://test.fmconnection.com/fmi/data',
    'MyDatabase',
    'username',
    'password',
    true,                       // SSL verification
    false,                      // Force legacy HTTP
    false,                      // Return response object
    HttpClient::CURL,           // HTTP client type (enum)
    DapiVersion::V1             // Data API version (enum)
);

// Using DataApi\HttpClientType::GUZZLE
$dataApi = new DataApi(
    'https://test.fmconnection.com/fmi/data',
    'MyDatabase',
    'username',
    'password',
    true,                       // SSL verification
    false,                      // Force legacy HTTP
    false,                      // Return response object
    HttpClient::GUZZLE,         // HTTP client type (enum)
    DapiVersion::VLATEST        // Data API version (enum)
);

// Default behavior (uses HttpClientType::CURL)
$dataApi = new DataApi(
    'https://test.fmconnection.com/fmi/data',
    'MyDatabase',
    'username',
    'password'
);

Using String Values (Backward Compatibility):

// Using string 'curl'
$dataApi = new DataApi(
    'https://test.fmconnection.com/fmi/data',
    'MyDatabase',
    'username',
    'password',
    true,               // SSL verification
    false,              // Force legacy HTTP
    false,              // Return response object
    'curl',             // HTTP client type (string)
    DapiVersion::V1     // Data API version (enum)
);

// Using string 'guzzle'
$dataApi = new DataApi(
    'https://test.fmconnection.com/fmi/data',
    'MyDatabase',
    'username',
    'password',
    true,               // SSL verification
    false,              // Force legacy HTTP
    false,              // Return response object
    'guzzle',           // HTTP client type (string)
    DapiVersion::V1     // Data API version (enum)
);

Constructor Parameters:

new DataApi(
    string $apiUrl,                                     // FileMaker Data API URL
    string $apiDatabase,                                // Database name
    string $apiUser = null,                             // Username (optional)
    string $apiPassword = null,                         // Password (optional)
    bool $sslVerify = true,                             // Verify SSL certificates
    bool $forceLegacyHTTP = false,                      // Force HTTP/1.1
    bool $returnResponseObject = false,                 // Return full response objects
    HttpClient|string $httpClient = HttpClient::CURL    // HTTP client (enum or string)
    DapiVersion $dapiVersion = DapiVersion::V1          //specify Data API version (enum) currently v1, v2 or vLatest
);

Benefits of HTTP Client Abstraction

Flexibility: Switch between HTTP implementations without changing your code
Future-proofing: Easy migration to new HTTP client libraries
Testing: Better mocking capabilities with Guzzle
Performance: Choose the best client for your specific needs
Backward Compatibility: Existing code continues to work unchanged

Create record

// Call login method first

$recordData = [
    'FirstName'         => 'John',
    'LastName'          => 'Doe',
    'email'             => 'johndoe@acme.inc',
    'RepeatingField(1)' => 'Test'
];

$scripts = [
    [
        'name'  => 'ScriptThatRunsBeforeRequest',
        'param' => 'johndoe@acme.inc',
        'type'  => RCConsulting\FileMakerApi\DataApi::SCRIPT_PREREQUEST
    ],
    [
        'name'  => 'ScriptThatRunsAfterRequestBeforeSort',
        'param' => 'johndoe@acme.inc',
        'type'  => RCConsulting\FileMakerApi\DataApi::SCRIPT_PRESORT
    ],
    [
        'name'  => 'ScriptThatRunsAfterRequestAfterSort',
        'param' => 'johndoe@acme.inc',
        'type'  => RCConsulting\FileMakerApi\DataApi::SCRIPT_POSTREQUEST
    ]
];

$portalData = [
    'lunchDate' => '17/04/2013',
    'lunchPlace' => 'Acme Inc.'
];

try {
    $recordId = $dataApi->createRecord('layout name', $recordData, $scripts, $portalData);
} catch(\Exception $e) {
  // handle exception
}

Delete record

// Call login method first

try {
  $dataApi->deleteRecord('layout name', $recordId, $scripts);
} catch(\Exception $e) {
  // handle exception
}

Edit record

// Call login method first

try {
  $recordId = $dataApi->editRecord('layout name', $recordId, $recordData, $lastModificationId, $portalData, $scripts);
} catch(\Exception $e) {
  // handle exception
}

Get record

// Call login method first

$portals = [
    [
        'name'   => 'Portal1',
        'limit'  => 10
    ],
    [ 
        'name'   => 'Portal2',
        'offset' => 3
    ]
];

try {
  $record = $dataApi->getRecord('layout name', $recordId, $portals, $scripts, $responseLayout, $dateFormat);
} catch(\Exception $e) {
  // handle exception
}

Get records

// Call login method first

$sort = [
    [
        'fieldName' => 'FirstName',
        'sortOrder' => 'ascend'
    ],
    [
        'fieldName' => 'City',
        'sortOrder' => 'descend'
    ]
];

try {
  $record = $dataApi->getRecords('layout name', $sort, $offset, $limit, $portals, $scripts, $responseLayout, $dateFormat);
} catch(\Exception $e) {
  // handle exception
}

Find records

// Call login method first
$query = [
    [
        'fields'  => [
            ['fieldname' => 'FirstName', 'fieldvalue' => '==Test'],
            ['fieldname' => 'LastName', 'fieldvalue' => '==Test'],
        ],
        'options' => [
            'omit' => false
        ]
    ]
];

try {
  $results = $dataApi->findRecords('layout name', $query, $sort, $offset, $limit, $portals, $scripts, $responseLayout, $dateFormat);
} catch(\Exception $e) {
  // handle exception
}

Blind Fire Script

try {
    $dataApi->executeScript($layout, $scriptName, $scriptParameters);
} catch(\Exception $e) {
    // handle exception
}

Set global fields

// Call login method first

$globalsData = [
  'FieldName1'	=> 'value',
  'FieldName2'	=> 'value'
];

try {
  $dataApi->setGlobalFields('layout name', $globalsData);
} catch(\Exception $e) {
  // handle exception
}

Upload file to container

File Passed Via WebForm

// Call login method first

$containerFieldName       = 'Picture';
$containerFieldRepetition = 1;
// replace 'upload' below with the name="value" of the file input element of your web form
$filepath                 = $_FILES['upload']['tmp_name'];
$filename                 = $_FILES['upload']['name'];

try {
  $dataApi->uploadToContainer('layout name', $recordId, $containerFieldName, $containerFieldRepetition, $filepath, $filename);
} catch(\Exception $e) {
  // handle exception
}

File On Server

// Call login method first

$containerFieldName       = 'Picture';
$containerFieldRepetition = 1;
$filepath                 = '/usr/home/acme/pictures/photo.jpg';

try {
  $dataApi->uploadToContainer('layout name', $recordId, $containerFieldName, $containerFieldRepetition, $filepath);
} catch(\Exception $e) {
  // handle exception
}

library helper methods

token usage

FileMaker Data API session tokens last 15 minutes from last use. By default, this library will manage them for you. If you use the login() methods, the library will log in again automatically to retreive a new token if the one you are using has expired.

This allows easy management, and separation by user, database, or privilege set. You can easily separate different data sets, databases, or privileged access views by launching (new) and managing multiple data api objects at once.

If you wish to manage these session tokens directly, you can use the methods below.

// useful when not explicitly logging into data api, but already have valid session token
// this implicitly sets the token retrieval date to now()
$dataApi->setApiToken($token);
// here, $tokenDate is a unix timestamp
$dataApi->setApiToken($token, $tokenDate);

// returns current api token (without checking if it's valid)
$token = $dataApi->getApiToken();

// check if token is expired using previously-stored last use-date
// this is NOT a live check with FMS
if ($dataApi->isApiTokenExpired()) {
// token expired
} else {
// do stuff
}

// refresh token when it has expired
// this logs in again, which creates a new session, so should only be used after the previous token has expired
// you must have used the login() method previously. oAuth not tested.
if ($dataApi->refreshToken()) {
// success
} else {
// failure - either the login itself failed, or you have no stored credentials
}

// check if the session token we are using is valid according to FileMaker Server
if ($dataApi->validateTokenWithServer()){
// token is valid according to FMS!
} else {
// token has expired according to FMS!
}

update object settings

//use this if you need to explicitly use v1 or v2. The default is v1, any future versions will be added. vLatest is also supported.
$dataApi->setDAPIVersion(DapiVersion::V2)

ToDo:

~~replace all curl with guzzle~~, while adding certainty and monolog

rcconsulting / myfmapilibrary-for-php

Maintainers

Details