FMDataAPI
in package
Class FMDataAPI is the wrapper of The REST API in Claris FileMaker Server and FileMaker Cloud for AWS.
Tags
Table of Contents
Properties
Methods
- __construct() : mixed
- FMDataAPI constructor. If you want to activate OAuth authentication, $user and $password are set as oAuthRequestId and oAuthIdentifier. Moreover, call useOAuth method before accessing layouts.
- curlErrorCode() : int
- The error number of curl, i.e., kind of communication error code.
- curlErrorMessage() : string|null
- The error message of curl, text representation of code.
- endCommunication() : void
- Finish a communication scope.
- errorCode() : int
- The error code of the latest response from the REST API.
- errorMessage() : string|null
- The error message of the latest response from the REST API.
- getContainerData() : string
- Return the base64 encoded data in the container field with streaming url.
- getDatabaseNames() : null|array<string|int, mixed>
- Get the information about a hosting database. It includes the target database and others in FileMaker Server.
- getFieldHTMLEncoding() : bool
- Detect the return value of the field() method uses htmlspecialchars function or not.
- getFoundCount() : null|int
- Get the founded record count of just a previous query.
- getLayoutNames() : null|array<string|int, mixed>
- Get the list of layout name in a database.
- getProductInfo() : null|object
- Get the product information, such as the version, etc. This isn't required to authenticate.
- getReturnedCount() : null|int
- Get the returned record count of just a previous query.
- getScriptNames() : null|array<string|int, mixed>
- Get the list of script name in a database.
- getSessionToken() : string|null
- The session token earned after authentication.
- getTargetTable() : null|string
- Get the table occurrence name of just a previous query.
- getTotalCount() : null|int
- Get the total record count of just a previous query.
- httpStatus() : int|null
- The HTTP status code of the latest response from the REST API.
- layout() : FileMakerLayout
- Refers to the FileMakerLayout object as the proxy of the layout.
- setAPIVersion() : void
- FileMaker Data API's version is going to be set. If you don't call, the "vLatest" is specified.
- setCertValidating() : void
- Set to verify the server certificate. The default is to handle as a self-signed certificate and doesn't verify.
- setDebug() : void
- Set the debug mode or not. The debug mode isn't in default.
- setExcludeTimeStampInException() : void
- Set the property of the communication provider for excluding the timestamp from the exception message.
- setFieldHTMLEncoding() : void
- Set to true if the return value of the field() method uses the htmlspecialchars function.
- setGlobalField() : void
- Set the value to the global field.
- setRetryOnAccessTokenInvalidation() : void
- Controls whether failed Data API calls are automatically retried after session invalidation.
- setSessionCacheTtl() : void
- Overrides the time-to-live (TTL) of the cached FileMaker Data API session token.
- setSessionToken() : void
- Set session token
- setThrowException() : void
- Set to prevent throwing an exception in case of error.
- setTimeout() : void
- Set the cURL communication timeout in seconds
- startCommunication() : void
- Start a communication scope with a shared authenticated session.
- useOAuth() : void
- In the authentication session, username and password are handled as OAuth parameters.
Properties
$layout read-only
public
FileMakerLayout
$layout
Returns the FileMakerLayout object from the layout named with the property. If the layout doesn't exist, no error arises here. Any errors might arise on methods of FileMakerLayout class.
Methods
__construct()
FMDataAPI constructor. If you want to activate OAuth authentication, $user and $password are set as oAuthRequestId and oAuthIdentifier. Moreover, call useOAuth method before accessing layouts.
public
__construct(string $solution, string $user, string|null $password[, string|null $host = null ][, int|null $port = null ][, string|null $protocol = null ][, array<string|int, mixed>|null $fmDataSource = null ][, bool $isUnitTest = false ][, SessionCacheInterface|null $sessionCache = null ]) : mixed
Parameters
- $solution : string
-
The database file name which is just hosting. Every database must have the accessing privilege 'fmrest' including external data sources.
- $user : string
-
The fmrest privilege accessible user to the database. If you’re going to call useOAuth method, you have to specify the data for X-FM-Data-OAuth-Request-Id.
- $password : string|null
-
The password of the above user. This can be null for testing purposes only. Null data is going to replace the string "password". This prevents to being detected as a security issue. On the real solutions, you have to set a valid password string. If you’re going to call useOAuth method, you have to specify the data for X-FM-Data-OAuth-Identifier.
- $host : string|null = null
-
FileMaker Server's host name or IP address. If omitted, 'localhost' is chosen. The value "localserver" tries to connect directory 127.0.0.1, and you don't have to set $port and $protocol.
- $port : int|null = null
-
FileMaker Server's port number. If omitted, 443 is chosen.
- $protocol : string|null = null
-
FileMaker Server's protocol name. If omitted, 'https' is chosen.
- $fmDataSource : array<string|int, mixed>|null = null
-
Authentication information for external data sources. Ex. [{"database"=>"<databaseName>", "username"=>"
", "password"=>" "}]. If you use OAuth, "oAuthRequestId" and "oAuthIdentifier" keys have to be specified. - $isUnitTest : bool = false
-
If it's set to true, the communication provider just works locally.
- $sessionCache : SessionCacheInterface|null = null
-
Cache backend for persistent sessions. If omitted, the library logs in and out on every database operation, or once per communication scope when using startCommunication() / endCommunication(). If specified, session tokens are persisted and reused across requests via startCommunication() / endCommunication(), avoiding redundant logins against the FileMaker Server. When a session cache is specified, self::setRetryOnAccessTokenInvalidation() is automatically set to true, ensuring the library re-authenticates and retries the request if the cached token has expired on the FileMaker Server.
curlErrorCode()
The error number of curl, i.e., kind of communication error code.
public
curlErrorCode() : int
Return values
int —The error number of curl.
curlErrorMessage()
The error message of curl, text representation of code.
public
curlErrorMessage() : string|null
Return values
string|null —The error message of curl.
endCommunication()
Finish a communication scope.
public
endCommunication() : void
Without a session cache, the authenticated session for the current communication scope is ended and the server session is logged out.
With a session cache, the cached token's TTL is renewed if it still matches the token held by this instance. If another process has replaced the cached token in the meantime, only this instance's now-stale token is logged out, leaving the newer cached token intact.
Tags
errorCode()
The error code of the latest response from the REST API.
public
errorCode() : int
Code 0 means no error, and -1 means error information wasn't returned. This error code is associated with FileMaker's error code.
Return values
int —The error code.
errorMessage()
The error message of the latest response from the REST API.
public
errorMessage() : string|null
This error message is associated with FileMaker's error code.
Return values
string|null —The error message.
getContainerData()
Return the base64 encoded data in the container field with streaming url.
public
getContainerData(string $url) : string
Parameters
- $url : string
-
The container data URL.
Tags
Return values
string —The base64 encoded data in the container field.
getDatabaseNames()
Get the information about a hosting database. It includes the target database and others in FileMaker Server.
public
getDatabaseNames() : null|array<string|int, mixed>
This is required to authenticate.
Tags
Return values
null|array<string|int, mixed> —The information of hosting databases. Every element is an object and just has 'name' property.Ex.: [{"name": "TestDB"},{"name": "sample_db" }]
getFieldHTMLEncoding()
Detect the return value of the field() method uses htmlspecialchars function or not.
public
getFieldHTMLEncoding() : bool
Return values
bool —The result.
getFoundCount()
Get the founded record count of just a previous query.
public
getFoundCount() : null|int
Usually this method returns the information of the FileMakerRelation class.
Tags
Return values
null|int —The founded record count.
getLayoutNames()
Get the list of layout name in a database.
public
getLayoutNames() : null|array<string|int, mixed>
Tags
Return values
null|array<string|int, mixed> —The information of layouts in the target database. Every element is an object and just has 'name' property. Ex.: [{"name": "person_layout"},{"name": "contact_to"},{"name": "history_to"}...]
getProductInfo()
Get the product information, such as the version, etc. This isn't required to authenticate.
public
getProductInfo() : null|object
Tags
Return values
null|object —The information of this FileMaker product. Ex.: {'name' => 'FileMaker Data API Engine', 'buildDate' => '03/27/2019', 'version' => '18.0.1.109', 'dateFormat' => 'MM/dd/yyyy', 'timeFormat' => 'HH:mm:ss', 'timeStampFormat' => 'MM/dd/yyyy HH:mm:ss'}.
getReturnedCount()
Get the returned record count of just a previous query.
public
getReturnedCount() : null|int
Usually this method returns the information of the FileMakerRelation class.
Tags
Return values
null|int —The returned record count.
getScriptNames()
Get the list of script name in a database.
public
getScriptNames() : null|array<string|int, mixed>
Tags
Return values
null|array<string|int, mixed> —The information of scripts in the target database. Every element is an object and has a 'name' property. The 'isFolder' property is true if it's a folder item, and it has the 'folderScriptNames' property and includes an object with the same structure. Ex.: [{"name": "TestScript1","isFolder": false},{"name": "TestScript2","isFolder": false},{"name": "Maintenance", "isFolder": true, "folderScriptNames": [{"name": "DataImport","isFolder": false}]}]
getSessionToken()
The session token earned after authentication.
public
getSessionToken() : string|null
Return values
string|null —The session token.
getTargetTable()
Get the table occurrence name of just a previous query.
public
getTargetTable() : null|string
Usually this method returns the information of the FileMakerRelation class.
Tags
Return values
null|string —The table name.
getTotalCount()
Get the total record count of just a previous query.
public
getTotalCount() : null|int
Usually this method returns the information of the FileMakerRelation class.
Tags
Return values
null|int —The total record count.
httpStatus()
The HTTP status code of the latest response from the REST API.
public
httpStatus() : int|null
Return values
int|null —The HTTP status code.
layout()
Refers to the FileMakerLayout object as the proxy of the layout.
public
layout(string $layout_name) : FileMakerLayout
If the layout doesn't exist, no error arises here. Any errors might arise on methods of the FileMakerLayout class.
Parameters
- $layout_name : string
-
Layout name.
Return values
FileMakerLayout —object which is a proxy of FileMaker's layout.
setAPIVersion()
FileMaker Data API's version is going to be set. If you don't call, the "vLatest" is specified.
public
setAPIVersion(int $vNum) : void
As far as FileMaker 18 supports just "v1", no one has to call this method.
Parameters
- $vNum : int
-
FileMaker Data API's version number.
setCertValidating()
Set to verify the server certificate. The default is to handle as a self-signed certificate and doesn't verify.
public
setCertValidating(bool $value) : void
Parameters
- $value : bool
-
Turn on to verify the certificate if the value is true.
setDebug()
Set the debug mode or not. The debug mode isn't in default.
public
setDebug(bool $value) : void
Parameters
- $value : bool
-
set the debug mode if the value is true.
setExcludeTimeStampInException()
Set the property of the communication provider for excluding the timestamp from the exception message.
public
setExcludeTimeStampInException([bool $value = true ]) : void
The default value of this property is false.
Parameters
- $value : bool = true
-
Excluding the timestamp from the exception message if true.
setFieldHTMLEncoding()
Set to true if the return value of the field() method uses the htmlspecialchars function.
public
setFieldHTMLEncoding(bool $value) : void
The default value is FALSE. The nostalgic FileMaker API for PHP was returning the htmlspecialchars value of the field. If we want to get the row field data, we had to call the getFieldUnencoded method. If this property is set to true, FileMakerRelation class's field method (including describing field name directly) returns the value processed with the htmlspecialchars. This means a kind of compatible mode to FileMaker API for PHP. This feature works whole the FMDataAPI library.
Parameters
- $value : bool
-
Turn on to verify the certificate if the value is true.
setGlobalField()
Set the value to the global field.
public
setGlobalField(array<string|int, mixed> $fields) : void
Parameters
- $fields : array<string|int, mixed>
-
Associated array contains the global field names (Field names must be Fully Qualified) and its values. Keys are global field names and values are these values.
Tags
setRetryOnAccessTokenInvalidation()
Controls whether failed Data API calls are automatically retried after session invalidation.
public
setRetryOnAccessTokenInvalidation([bool $value = true ]) : void
When enabled and a call fails with error 952 (invalid token) or 112 (window missing), the current session is discarded, a new session is established, and the call is retried once.
When a session cache is provided to the constructor, retry on token invalidation is always active regardless of this setting. This flag only has an effect when no session cache is configured.
Warning: The retry runs in a fresh session. Any session-scoped state from the original session is lost — for example, global fields set before the retry will not carry over.
Parameters
- $value : bool = true
setSessionCacheTtl()
Overrides the time-to-live (TTL) of the cached FileMaker Data API session token.
public
setSessionCacheTtl([int $ttl = 840 ]) : void
WARNING: Setting a TTL that exceeds the FileMaker Data API session timeout (15 minutes) will cause the library to use expired tokens, resulting in authentication failures. Do not use this method unless you fully understand the implications.
The default TTL is 840 seconds (14 minutes), intentionally set one minute below the FileMaker Data API session timeout of 15 minutes to ensure the cached token is invalidated before it expires on the FileMaker Server.
Parameters
- $ttl : int = 840
-
Time-to-live in seconds. Defaults to 840 seconds (14 minutes).
Tags
setSessionToken()
Set session token
public
setSessionToken(string $value) : void
Parameters
- $value : string
-
The session token.
setThrowException()
Set to prevent throwing an exception in case of error.
public
setThrowException(bool $value) : void
The default is true, so an exception is going to throw in error.
Parameters
- $value : bool
-
Turn off to throw an exception in case of error if the value is false.
setTimeout()
Set the cURL communication timeout in seconds
public
setTimeout(int $timeout) : void
Parameters
- $timeout : int
startCommunication()
Start a communication scope with a shared authenticated session.
public
startCommunication() : void
Usually most methods login and logout before and after each database operation. By calling startCommunication() and endCommunication(), methods between them don't log in and out every time, and it can expect faster operations.
Without a session cache, one authenticated session is kept for the duration of the current communication scope and discarded when endCommunication() is called.
With a session cache, the session token is persisted beyond the current communication scope and reused across requests. If no cached token is available, a new session is created and stored for future reuse.
Tags
useOAuth()
In the authentication session, username and password are handled as OAuth parameters.
public
useOAuth() : void