Optional parameters to most API methods.
The $options parameter to most apiNNNNNN() methods is an array of abstracted options passed to the Data API.
Not every call supports all these options. See the documentation for each call to determine what options are allowed.
$options = array(
'limit' => <integer>,
'offset' => <integer>,
'sort' => array(array('fieldName' => <string>) [, 'fieldName' => <string>)] [, 'sortOrder' => <string>)]), // sortOder should be 'ascend' or 'descend'
'script' => <string>,
'scriptParams' => <string>,
'scriptPrerequest' => <string>,
'scriptPrerequestParams' => <string>,
'scriptPresort' => <string>,
'scriptPresortParams' => <string>,
'layoutResponse' => <string>,
'portals' => array(<string> [, <string>, ...]),
'portalLimits' => array(
array('name' => <string>, 'limit' => (integer)),
...
),
'portalOffsets' => array(
array('name' => '<string>', 'offset' => (integer)),
...
),
'deleteRelated' => array(array('table' => '<string>', 'recordID' => '<number>'), ...),
'query' => array(
array('<fieldname>' => <string> [, '<fieldname>' => <string>, ...] ['omit' => 'true']),
...
)
);
fmDataAPI Constructor
__construct($database, $host, $username, $password, $options = array())
Constructor for the fmDataAPI class.
Parameters:
(string) $database The name of the database (do NOT include the .fmpNN extension)
(string) $host The host name typically in the format of https://HOSTNAME
(string) $username The user name of the account to authenticate with
(string) $password The password of the account to authenticate with
(array) $options Optional parameters
['version'] Version of the API to use (1, 2, etc. or 'Latest')
Token management - typically you choose none or one of the following 3 options:
['storeTokenInSession'] and ['sessionTokenKey']
['tokenFilePath']
['token']
['storeTokenInSession'] If true, the token is stored in the $_SESSION[] array (defaults to true)
['sessionTokenKey'] If ['storeTokenInSession'] is true, this is the key field to store
the token in the $_SESSION[] array. Defaults to 'FM-Data-Session-Token'.
['tokenFilePath'] Where to read/write a file containing the token. This is useful
when you are called as a web hook and do not have a typical
browser-based session to rely on. You should specify a path that
is NOT visible to the web. If you need to encrypt/decrypt the token
in the file, override getTokenFromStorage() and setToken().
['token'] The token from a previous call. This will normally be pulled
from the $_SESSION[] or ['tokenFilePath'], but in cases where
you need to store it somewhere else, pass it here. You are responsible
for calling the getToken() method after a successful call to retrieve
it for your own storage.
['authentication'] set to 'oauth' for oauth authentication
['oauthID'] oauthID
['oauthIdentifier'] oauth identifier
['sources'] => array( External database authentication
array(
'database' => '', // do NOT include .fmpNN
'username' => '',
'password' => ''
)
)
Returns:
The newly created object.
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
fmDataAPI::apiProductinfo()
function apiProductinfo()
Retrieves information about the FileMaker Server or FileMaker Cloud host
Parameters:
None
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] Returns data about the server
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiProductinfo();
if (! $fm->getIsError($apiResult)) {
...
}
Return info about the server
fmDataAPI::apiListDatabases()
function apiListDatabases()
Retrieve a list of hosted FileMaker databases with the specified credentails.
Parameters:
None
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] A list of databases
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiListDatabases()
if (! $fm->getIsError($apiResult)) {
...
}
Return a list of databases
fmDataAPI::apiListLayouts()
function apiListLayouts()
Retrieves a list of layouts for the database
Parameters:
None
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] A list of layouts in the database
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiListLayouts()
if (! $fm->getIsError($apiResult)) {
...
}
Return a list of layouts in the database
fmDataAPI::apiListScripts()
function apiListScripts()
Retrieves a list of scripts for the database
Parameters:
None
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] A list of scripts in the database
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiListScripts()
if (! $fm->getIsError($apiResult)) {
...
}
Return a list of scripts in the database
fmDataAPI::apiLayoutMetadata()
function apiLayoutMetadata()
Return layout information. If $recordID specified, retrieve value list data.
Parameters:
(string) $layout The name of the layout
(integer) $recordID The recordID of the record to retrieve value list data
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] The meta data
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiLayoutMetadata('Web_Project', 1);
if (! $fm->getIsError($apiResult)) {
...
}
Return the layout meta data
fmDataAPI::apiLogin()
function apiLogin()
Create a new session on the server. Authentication parameters were previously passed to the __construct method.
Normally you will not call this method as the other apiNNNNNN() methods take care of logging in when appropriate.
By default, the authentication token is stored within this class and reused for all further calls. If the server
replies that the token is not longer valid (FM_ERROR_INVALID_TOKEN - 952), this class will automatically login
again to get a new token.
The server expires a timer after approximately 15 minutes, but the timer is reset each time you make a call to
the server. You should not assume it is always 15 minutes; a later version of FileMaker Server may change this
time. Let this class handle the expiration in a graceful manner.
Parameters:
None
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] If the call succeeds, the ['token'] element contains the authentication token.
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiLogin();
if (! $fm->getIsError($apiResult)) {
...
}
Log in and create a new session
fmDataAPI::apiLogout()
function apiLogout()
Logs out of the current session and clears the username, password, and authentication token.
Any global variables previously set will be restored to their previous values by the server.
Normally you will not call this method so that you can keep re-using the authentication token for future calls.
Only logout if you know you are completely done with the session. This will also clear the stored username/password.
Parameters:
None
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] Typically this will be empty
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiLogout();
if (! $fm->getIsError($apiResult)) {
...
}
Log out and destroy the session
fmDataAPI::apiGetRecord()
function apiGetRecord($layout, $recordID, $params = '', $options = array())
Get the record specified by $recordID.
Parameters:
(string) $layout The name of the layout
(integer) $recordID The recordID of the record to retrieve
(string) $params The raw GET parameters to modify the call. Typically done with $options [optional]
(array) $options Additional API parameters call [optional]
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] The record data
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiGetRecord('Web_Project', 1);
if (! $fm->getIsError($apiResult)) {
...
}
$apiResult = $fm->apiGetRecord('Web_Project', 55555);
if (! $fm->getIsError($apiResult)) {
...
}
Get 2 records by ID, second one will fail because it doesn't exist
Get 1 record by ID using external authentication
Get 1 record by ID using external authentication
fmDataAPI::apiGetRecords()
function apiGetRecords($layout, $params = '', $options = array())
Get a series of records. By default the first 100 records will be returned.
Parameters:
(string) $layout The name of the layout
(string) $params The raw GET parameters (ie: '&_limit=50&_offset=10') to modify the call. Typically done with $options [optional]
(array) $options Additional API parameters(ie: array('limit' => 50, 'offset' => 10) to modify the call [optional]
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] The record data
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiGetRecords('Web_Project', '', array('limit' => 50, 'offset' => 10));
if (! $fm->getIsError($apiResult)) {
...
}
Get 50 records starting at the 10th record
fmDataAPI::apiFindRecords()
function apiFindRecords($layout, $data, $options = array())
Find record(s) with a query which can be a non-compound or a compound find.
Parameters:
(string) $layout The name of the layout
(array) $data An array of query parameters in the format the Data API expects.
Currently this is the same format as $options['query'].
(array) $options Additional API parameters. Valid options:
['limit']
['offset']
['sort']
['script']
['scriptParams']
['scriptPrerequest']
['scriptPrerequestParams']
['scriptPresort']
['scriptPresortParams']
['layoutResponse']
['portals']
['portalLimits']
['portalOffsets']
['query']
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] The record(s) data
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$data = array(
'query'=> array(
array('Name' => 'Test', 'ColorIndex' => '5', 'omit' => 'true'),
array('ColorIndex' => '20')
)
);
$apiResult = $fm->apiFindRecords('Web_Project', $data);
if (! $fm->getIsError($apiResult)) {
...
}
Non compound find
Compound find
Compound find
fmDataAPI::apiCreateRecord()
function apiCreateRecord($layout, $fields, $options = array())
Create a new record.
Parameters:
(string) $layout The name of the layout
(array) $fields An array of field name/value pairs
(array) $options Additional API parameters. Valid options:
['script']
['scriptParams']
['scriptPrerequest']
['scriptPrerequestParams']
['scriptPresort']
['scriptPresortParams']
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] If the call succeeds:
['modId'] Modification ID (should be 0)
['recordId'] Record ID of the newly created record
['response']
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$fields = array();
$fields['Name'] = 'Test';
$fields['ColorIndex'] = 999;
$apiResult = $fm->apiCreateRecord('Web_Project', $fields);
if (! $fm->getIsError($apiResult)) {
...
}
Add a record
fmDataAPI::EditRecord()
function apiEditRecord($layout, $recordID, $data, $options = array())
Edit a record.
Parameters:
(string) $layout The name of the layout
(integer) $recordID The recordID of the record to edit
(array) $data Array of field name/value pairs
(array) $options Additional API parameters. Valid options:
['script']
['scriptParams']
['scriptPrerequest']
['scriptPrerequestParams']
['scriptPresort']
['scriptPresortParams']
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] If the call succeeds:
['modId'] The new modification ID of the edited record
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$fields = array();
$fields['ColorIndex'] = 48;
$apiResult = $fm->apiEditRecord('Web_Project', 6, $fields);
if (! $fm->getIsError($apiResult)) {
...
}
Edit a record
fmDataAPI::apiDeleteRecord()
function apiDeleteRecord($layout, $recordID, $options = array())
Delete a record.
Parameters:
(string) $layout The name of the layout
(integer) $recordID The recordID of the record to delete
(array) $options Additional API parameters. Valid options:
['script']
['scriptParams']
['scriptPrerequest']
['scriptPrerequestParams']
['scriptPresort']
['scriptPresortParams']
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] Typically this will be empty
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiDeleteRecord('Web_Project', 5);
if (! $fm->getIsError($apiResult)) {
...
}
Delete a record
fmDataAPI::apiDuplicateRecord()
function apiDuplicateRecord($layout, $recordID, $options = array())
Edit a record.
Parameters:
(string) $layout The name of the layout
(integer) $recordID The recordID of the record to duplicate
(array) $options Additional API parameters. Valid options:
['script']
['scriptParams']
['scriptPrerequest']
['scriptPrerequestParams']
['scriptPresort']
['scriptPresortParams']
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] If the call succeeds:
['modId'] The new modification ID of the duplicated record
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiDuplicateRecord('Web_Project', 6);
if (! $fm->getIsError($apiResult)) {
...
}
Duplicate a record
fmDataAPI::apiSetGlobals()
function apiSetGlobalFields($layout, $data)
Set global variable(s). The values retain their value throughout the session until you logout or the token expires.
Parameters:
(string) $layout The name of the layout
(array) $data An array of field name/value pairs
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] Typically this will be empty
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiSetGlobalFields('Web_Global', array('Project::gGlobal' => 5));
if (! $fm->getIsError($apiResult)) {
...
}
Set a global field, then do a get record to see if the global is returned
fmDataAPI::apiGetContainer() or fmDataAPI::GetRecord() to retrieve a URL or the container contents
Example 1:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiGetRecord('Web_Project', 1);
if (! $fm->getIsError($apiResult)) {
$responseData = $fm->getResponseData($apiResult);
$photoURL = $responseData[0][FM_FIELD_DATA]['Photo'];
$photoHW = $responseData[0][FM_FIELD_DATA]['c_PhotoHWHTML'];
$photoName = $responseData[0][FM_FIELD_DATA]['PhotoName'];
echo '<img src="'. $photoURL .'" '. $photoHW .' alt="'. $photoName .'" />
';
}
Examples 2, 3, & 4:
$options = array();
$options['action'] = 'get'; // get, download, or inline
$options['fileNameField'] = 'PhotoName'; // The value stored in the PhotoName field becomes the file name of the downloaded file.
$fm = new fmDataAPI(FM_DATABASE, FM_HOST, FM_USERNAME, FM_PASSWORD);
$apiResult = $fm->apiGetContainer('Web_Project', 114, 'Photo', FM_FIELD_REPETITION_1, $options);
Use fmDataAPI::GetRecord() to retrieve a record and display the container in an <img> tag
Use fmDataAPI::apiGetContainer() to display the container field contents.
Use fmDataAPI::apiGetContainer() to download the container field contents.
Use fmDataAPI::apiGetContainer() to download/inline the container field contents.
Use fmDataAPI::apiGetContainer() to display the container field contents.
Use fmDataAPI::apiGetContainer() to download the container field contents.
Use fmDataAPI::apiGetContainer() to download/inline the container field contents.
fmDataAPI::apiUploadContainer()
function apiUploadContainer($layout, $recordID, $fieldName, $fieldRepetition, $file)
Upload a file to a container field.
Parameters:
(string) $layout The name of the layout
(integer) $recordID The recordID of the record to store the file in
(string) $fieldName The field name where the file will be stored
(integer) $fieldRepetition The field repetition number
(string) $file An array of information about the file to be uploaded. You specify ['path'] or ['contents']:
$file['path'] The path to the file to upload (use this or ['contents'])
$file['contents'] The file contents (use this or ['path'])
$file['name'] The file name (required if you use ['contents'] otherwise
it will be determined)
$file['mimeType'] The MIME type
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] Typically this will be empty
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$file = array();
$file['path'] = 'sample_files/sample.png';
$apiResult = $fm->apiUploadContainer('Web_Project', 1, 'Photo', FM_FIELD_REPETITION_1, $file);
if (! $fm->getIsError($apiResult)) {
...
}
Upload a file to a container field
fmDataAPI::apiExecuteScript()
function apiExecuteScript($layout, $scriptName, $params = '', $options = array())
Execute a script. The underlying table matched with $layout does *not* need to have any records.
Typically you will call this with a $layout set to a layout with nothing on it.
Parameters:
(string) $layout The name of the layout
(string) $scriptName The name of the FileMaker script to execute
(string) $params The script parameter
(array) $options Additional API parameters. In v1 there are currently none.
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] Typically contains two elements:
['scriptError'] has any scripting error
['scriptResult'] is the value returned from the Exit Script[] script step
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiExecuteScript('Web_Global', 'Test', 'some');
if (! $fm->getIsError($apiResult)) {
...
}
Execute a script (FMS 18+)
fmDataAPI::apiPerformScript()
function apiPerformScript($layout, $scriptName, $params = '', $layoutResponse = '')
This function works with FMS 17+, but you must have record(s) in the table matching $layout.
Use apiExecuteScript() for v1 with FMS 18+, which does *not* need any records in the table.
Execute a script. We do this by doing a apiGetRecords() call for the first record on the specified layout.
For this to work, *YOU MUST* have at least one record in this table or the script *WILL NOT EXECUTE*.
For efficiency, you may want to create a table with just one record and no fields.
Typically you will call this with an $layout set to a layout with nothing on it and then use $layoutResponse
to indicate where you expect the result from the script to have put the record(s).
Parameters:
(string) $layout The name of the layout
(string) $scriptName The name of the FileMaker script to execute
(string) $params The script parameter
(string) $layoutResponse The name of the layout that any found set will be returned from
Returns:
An JSON-decoded associative array of the API result. Typically:
['response'] Returns any record(s) in ['data'] if there is a found set.
['scriptError'] has any scripting error
['scriptResult'] is the value returned from the Exit Script[] script step
['messages'] Array of code/message pairs
Example:
$fm = new fmDataAPI($database, $host, $username, $password);
$apiResult = $fm->apiPerformScript('Web_Global', 'Test', 'some', 'Web_Project');
if (! $fm->getIsError($apiResult)) {
...
}
Run a script