Introducing soSIMPLE Calendar Add-on for FileMaker 19
What is the FileMaker Data API?
The newly released FileMaker Server 16 now offers REST access to your FileMaker databases. There’s more about that how this impacts PHP developers here.
The bottom line is that to use REST as part of your PHP solution, you would usually need to write a series of cURL functions and you would have to manually manage connecting & disconnecting from your server, and saving your tokens.
This is a pain!
We know it’s a pain, because we have spent the last several weeks rolling REST functionality into soSIMPLE Calendar.
FREE fmREST.php – Simplifies & manages PHP connections to FileMaker 16’s REST-based Data API.
We created this class file to make it easier to manage dynamic REST sessions for soSIMPLE and our custom development. The goal of the class file was to help PHP developers start using the new REST engine as quickly and easily as possible.
We’ll also be updating it with new features. If you’d like to add something to it, please let us know.
What fmREST.php does:
- Makes every REST call available as a PHP function.
- Automatically login into FileMaker Server whenever you call any REST functions
- Saves your token for 15 minutes to reuse
- Checks for a broken or disconnected token and automatically reconnects and runs your function again
Where do I get it?
You can download the fmREST class file here.
(Update: this is now linked to our GitHub repository for better community participation.)
How do I use it?
1. Install the file
Install the class file by putting the file “fmREST.php” at the same location as your custom PHP page, or anywhere in your include path.
Include the file in your php file by adding the line:
include_once ('fmREST.php');
And don’t forget to set the extended privilege for your FileMaker file.
2. Call the class:
$fm = new fmREST ($host, $db, $layout, $user, $pass);
You can also set the parameters seperately
$fm = new fmREST ();
$fm -> host = 'myhost.com';
$fm -> db = 'my database.fmp12';
$fm -> layout = 'my layout';
$fm -> user = 'admin';
$fm -> pass = 'mySecretPassword';
3. Call your functions:
fmREST will automatically log in for you as necessary, as each function is called.
Important note: since we use a cookie to keep track of your token, your first function, or a specific call to the login function should be called before any visible content on the page.
How the functions work:
The functions that are part of this class use the same name and the same construct as the Data API. The only substantial difference is that you can pass the parameters as either JSON strings, or as PHP arrays. We find that native PHP arrays have been the easiest method.
For specific reference of the expected parameters, and results refer to the API documentation, located on your FileMaker Server. The documentation is located: https://<your server>/fmi/rest/apidoc/. There’s also a wealth of information here: https://fmhelp.filemaker.com/docs/16/en/restapi/#reference-information
Function Reference:
LOGIN:
$result = $fm -> login ();
notes:
- We use the user name and password from when you instantiated the class. This is the only function that doesn’t take parameters the same way as the API Doc.
- You don’t need to call this explicitly. It will be called whenever any data function is called.
- Whether explicitly called, or part of another function, the login should happen before any content is shown on the page.
LOGOUT:
$result = $fm -> logout ();
notes:
- We don’t log out automatically when functions are called. Doing so would add to the overhead of every call, defeating the purpose of managing tokens.
- FileMaker Server will automatically disconnect you after 15 minutes, or you can call this function to manually disconnect the session.
CREATE RECORD:
$record['my_field_name'] = 'my_field_value';
$record['another field'] = 'another value';
$data['data'] = $record;
$result = $fm -> createRecord ($data);
notes:
- please note how the record data is an array of fields, wrapped within another array
- all field data needs to be wrapped in quotation marks – even number fields
DELETE RECORD:
$recordId = 1234;
$result = $fm -> deleteRecord ($recordId);
notes:
- $recordId is the ID of the record – not the primary key field. You can find it in FileMaker Pro by calling get(recordid). It’s also part of every record returned from the API as $result [‘recordId’];
EDIT RECORD:
$recordId = 1234;
$record['my_field_name'] = 'my_field_value';
$record['another field'] = 'another value';
$data['data'] = $record;
$result = $fm -> editRecord ($recordId, $data);
notes:
- please note how the record data is an array of fields, wrapped within another array
- all field data needs to be wrapped in quotation marks – even number fields
- $recordId is the ID of the record – not the primary key field. You can find it in FileMaker Pro by calling get(recordid). It’s also part of every record returned from the API as $result [‘recordId’];
GET RECORD:
$recordId = 1234;
$result = $fm -> getRecord ($recordId);
notes:
- $recordId is the ID of the record – not the primary key field. You can find it in FileMaker Pro by calling get(recordid). It’s also part of every record returned from the API as $result [‘recordId’];
GET RECORDS:
$parameters = "offset=1&range=50";
$result = $fm -> getRecords ($parameters);
FIND RECORDS:
$request1['my_field_name'] = 'my_field_value';
$request1['another field'] = 'another value';
$request2['my_field_name'] = 'my_field_value';
$query = array ($request1, $request2);
$criteria['query'] = $query;
$result = $fm -> findRecords ($criteria);
notes:
- you can have any number of requests be part of a query by adding elements to the $query variable.
- you can also add sort, offset, range and portal by adding these parameters to the $criteria variable.
- please note how the request data is an array of fields, which is wrapped within another array, then wrapped into another array before it’s sent to the findRecords function.
- all field data needs to be wrapped in quotation marks – even number fields
SET GLOBAL FIELDS:
$globals['my_field_name'] = 'my_field_value';
$globals['another field'] = 'another value';
$data['globalFields'] = $globals;
$result = $fm -> setGlobalFields ($data);
notes:
- please note how the field data is an array of fields, wrapped within another array
- all field data needs to be wrapped in quotation marks – even number fields
DEBUGGING:
By setting a variable $debug anywhere on your page to $debug=true, the class file will output an array object of the data being generated for debugging purposes.
Related posts
