Though not technically required (you won't see a query related error if you omit it), many of the execution functions won't behave as expected, or do much without it. AddDBParam() is the method by which query criteria are specified. It is common to use more than one instance of this function in a query, especially when performing complex searches or updating an existing record/row.

$name - name of the entity (usually a field/column) against which to query.

Something for FileMaker® developers to keep in mind:

If the field is from a related table and/or database, you'll need to make sure that the relationship is appended to the field name, e.g. relationship_name::field_name.

$value - value for the named entity.

For FileMaker® users, note that wild cards can be used in $value just like they can in your queries. If your wild cards seem to be behaving strangely, try using PHP's urlencode() function on the value passed in.

For those using SQL data sources, please note that begins with, ends with, and contains operators generate the commonly used wild card patterns for the associated type of operation. For finer control — though without auto-magic SQL generation — you may find the PerformSQLQuery() method useful.

$op - (optional, searches only) operator to use.

Default is a "begins with" query, though this behavior can be changed with the SetDefaultOperator() function. Available operators are as follows:

$op   function performed on field/column
eq  - an 'equals' search.
cn  - a 'contains' search.
bw  - a 'begins with' search.
ew  - an 'ends with' search.
gt  - a 'greater than' search.
gte - a 'greater than or equal to' search.
lt  - a 'less than' search.
lte - a 'less than or equal to' search.
neq - a 'not equal to' search.

// query on FileMaker ≥7 DB named "CMS" returning 50 records (the default)
// with first names starting with "Jo" and last names ending with "sen"
$serverAddress = '192.168.22.11';
$serverPort = 80;
$serverType = 'FMPro7';
$username = 'web_user';
$password = 'password';
$databaseName = 'CMS';
$tableName = 'contacts';

$query = new FX($serverAddress, $serverPort, $serverType);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName);
$query->AddDBParam('first_name', 'Jo'); // begins with is default
$query->AddDBParam('last_name', 'sen', 'ew');
$queryResult = $query->DoFXAction('perform_find');

This function is designed to streamline the creation of FX.php database queries. Instead of calling AddDBParam() multiple times, the field names and parameters can be combined into one array, the operators in another, and a single call made to AddDBParamArray().

$paramsArray - array where each key is a field/column name, and each value is as desired for the associated key.

$paramOperatorsArray - (optional) array corresponding to $paramsArray with keys again equal to the associated field/column name, but each value is the desired operator for that field.

Note that in $paramOperatorsArray, elements may be omitted for fields where the default operator is the desired one.

// equivalent to query example for AddDBParam(), above
$serverAddress = '192.168.22.11';
$serverPort = 80;
$serverType = 'FMPro7';
$username = 'web_user';
$password = 'password';
$databaseName = 'CMS';
$tableName = 'contacts';
$groupSize = 15;
$fieldsArray = array('first_name' => 'Jo', 'last_name' => 'sen');
$operatorsArray = array('last_name' => 'ew');

$query = new FX($serverAddress, $serverPort, $serverType);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName, $groupSize);
$query->AddDBParamArray($fieldsArray, $operatorsArray);
$queryResult = $query->DoFXAction('perform_find');

This function is used to determine how the specified data source will sort the found records/rows before returning the data to FX. This method is optional when performing a search and is not relevant to any other type of query. By default, the order in which multiple calls to AddSortParam() appear determines sort precedence — i.e. the results will first be sorted as specified in the first call, next by the second, etc. This behavior can be modified by using the $performOrder parameter.

$field - field/column to sort on.

$sortOrder - (optional) the type of sort (ascending by default.)

In FileMaker® ≥ 7, the possible values of $sortOrder are ascend, descend, or the name of a value list. In the event that the name of a value list is passed, the returned data will be sorted based on that value list.

For SQL data sources, DESC or Descend will sort in descending order. Otherwise, an ascending sort is specified in the SQL.

$sortOrder can contain one one of three values in FileMaker® versions 5 through 6: Ascend, Descend, or Custom. Custom sorting works the same way that it does in FileMaker® Pro (i.e. it uses the value list formatted for the field specified on the current layout.)

$performOrder - (optional) the order in which this sort should be performed.

The $performOrder parameter can be used to order multiple sort requests as desired, rather than in the order which they appear in your code. The value passed must be a positive integer.

// will return a found set from the default data source and port
// by searching the works table/layout of the "Culture" DB for
// rows/records of "Type"="Art" - the results will first
// be sorted by descending "Medium", then by ascending "Name"
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'knock_knock';
$databaseName = 'Culture';
$layoutName = 'works';

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $layoutName);
$query->AddDBParam('Type', 'Art');
$query->AddSortParam('Medium', 'Descend');
$query->AddSortParam('Name');
$foundSet = $query->DoFXAction('perform_find');

This method has been deprecated as identical functionality if available via optional parameters of the execute functions.

FileMaker Only This optional function is used to change FX's method of accessing FileMaker® databases from an HTTP GET to an HTTP POST. FX.php uses POST by default for a number of reasons. In the event that you wish to use a GET request for some reason, FMPostQuery(false) can be called.

Because of GET's many limitations — including data limits that vary across servers and browsers and poorer security — it is recommended that this method be used very sparingly.

FMPostQuery() determines the method in which data is sent from your web server to your FileMaker® data source, not the method by which data is sent from a user's browser to your server (that is most often done in the HTML <form> tag.)

$isPostQuery - (optional) whether to use POST. Default is true.

// will request a random record via GET using the default
// data source and port
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'knock_knock';
$databaseName = 'Contacts';
$layoutName = 'web_Contact';

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $layoutName);
$query->FMPostQuery(false);
$randomRecord = $query->DoFXAction('show_any');

Deprecated! (see SetSkipSize())

$skipSize - number of records/rows to skip when returning data.

FileMaker Only This function is used to specify whether FX.php accesses FileMaker® data using cURL or sockets. FX.php has logic built in to detect cURL support, but there may be times when it may be helpful to control this explicitly. By default, cURL is used. Should you want or need to use sockets instead, FMUseCURL(false) can be called.

IMPORTANT: Although cURL and sockets are generally interchangeable, several calls to a FileMaker® data source from a single page using sockets may result in the truncation of your data. For this reason, it's best to use this function sparingly.

$useCURL - (optional) whether to use cURL to communicate with FileMaker® data sources. Default is true.

// will request a random record via sockets using the default
// data source and port
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'knock_knock';
$databaseName = 'Contacts';
$layoutName = 'web_Contact';

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $layoutName);
$query->FMUseCURL(false);
$randomRecord = $query->DoFXAction('show_any');

FileMaker Only When working with a FileMaker® data source, there may be cases when you would like to perform a script on the returned data set. In fact, at times, that is precisely the best way to accomplish a task. These three functions do just that. When PerformFMScript is called, the specified FileMaker® script will be executed after the current find and sort (if any) are performed. Using PerformFMScriptPrefind causes the specified script to execute before the current find and sort are executed. Finally, PerformFMScriptPresort runs the specified FileMaker script after the current find, but before the current sort is executed.

$scriptName - the name of the script to execute.

$scriptParam - the value to be passed to the script as a parameter.

// will return a found set from the default FileMaker ≥ 7 database and port
// the "bestArtFirst" script is called using a script parameter of "Garfunkel"
// the script will be performed after the specified find and sort
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'knock_knock';
$databaseName = 'Culture';
$layoutName = 'works';

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $layoutName);
$query->AddDBParam('Type', 'Art');
$query->AddSortParam('Name');
$query->PerformFMScript('bestArtFirst', 'Garfunkel');
$foundSet = $query->DoFXAction('perform_find');

This function, and its companion — SetDataParamsEncoding() — are used when connecting to a multi-byte data source without using UTF-8 html encoding. Note that both of these functions require that multi-byte support be compiled into PHP.

Even if your site is based on UTF-8, it's a good idea to call the SetCharacterEncoding() method. You might see any multi-byte characters as you'd expect in your browser, but behind the scenes they would be numeric character references styled like so: "&#nnnnn;" That is, they would show as a valid letter, but performing string operations would be problematic. These methods allow valid encoded characters to pass through.

$encoding - used to determine both how data is passed to FileMaker, and how data is returned from FileMaker.

If you need to set separate encoding for each direction when communicating with your database, first use SetCharacterEncoding() to set the encoding of incoming data, then use its companion SetDataParamsEncoding() to set the encoding of data being passed upstream.

// will return a random record using the default data source and port
// data will be encoded properly as UTF-8 (without use of html entities)
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'knock_knock';
$databaseName = 'Contacts';
$layoutName = 'web_Contact';

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $layoutName);
$query->SetCharacterEncoding('UTF-8');
$randomRecord = $query->DoFXAction('show_any');

Only determines how data is passed to your database. See the notes for its companion function, SetCharacterEncoding(), for information on how to use the encoding functions together.

$encoding - the encoding to use when sending data.

// will return a random record using the default data source and port
// data will be encoded as UTF-8 up, UTF-16 down (no use of html entities)
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'knock_knock';
$databaseName = 'Contacts';
$layoutName = 'web_Contact';

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $layoutName);
$query->SetCharacterEncoding('UTF-16');
$query->SetDataParamsEncoding('UTF-8');
$randomRecord = $query->DoFXAction('show_any');

SetDBData() is a required function for most of the functions which execute a query. Documentation for each function will indicate whether this is the case. Failure to call this method when it is required, will cause your query to return an error.

$database - the name of the database to be accessed.

$layout - the name of the layout (in FileMaker ® databases) or table (for SQL databases) to access.

$layout is technically an optional parameter for FileMaker versions 5 through 6, but is required for most other queries performed via FX. Failure to specify $layout when it is required will cause your query to return an FX Error Object. It is optional in older versions of FileMaker® databases because by default these versions will access a FileMaker® internal layout which contains every field. However, using the default layout will almost always result in reduced performance. See the Best Practices page for suggestions about the right way to design FileMaker® layouts for the web.

$groupSize - (optional) how many records FX returns per query. Defaults to 50. Generally an integer, but may be the special value "All" (use "All" with caution!

$responseLayout - (optional, FMS ≥ 7 only) the layout from which to return data.

When accessing a FileMaker® version 7 or later data source, it is possible to perform the request on one layout, and then use a different layout to pull the returned data. Caution should be used with this parameter since a change in layout may correspond to a change in context (e.g. a query that was performed on a layout with a "Contacts" table context, should not try to return data via a layout based on a table called "Movie_Titles".)

// query to FMS7+ that uses different layouts for query and return
// would return up to 10 records, but "show_any" returns a single record
$serverAddress = '192.168.22.11';
$serverPort = 80;
$serverType = 'FMPro7';
$username = 'web_user';
$password = 'password';
$databaseName = 'Contacts';
$queryLO = 'web_ContactSearch';
$responseLO = 'web_ContactDetails';
$groupSize = 10;

$query = new FX($serverAddress, $serverPort, $serverType);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $queryLO, $groupSize, $responseLO);
$randomRecord = $query->DoFXAction('show_any');

// query on PostgreSQL database named "CMS":
// SELECT * FROM contacts WHERE last_name = 'Smith' LIMIT 15
$serverAddress = '192.168.22.11';
$serverPort = 5432;
$serverType = 'PostgreSQL';
$username = 'web_user';
$password = 'password';
$databaseName = 'CMS';
$tableName = 'contacts';
$groupSize = 15;

$query = new FX($serverAddress, $serverPort, $serverType);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName, $groupSize);
$query->AddDBParam('last_name', 'Smith');
$queryResult = $query->DoFXAction('perform_find');

Used to specify the password and user name — in that order — for the current query. The function SetDBUserPass performs the same task, but the parameters are in a more traditional order. Most queries need to specify a username and password. It is important that the credentials specified provide the required access to perform the current query.

This particular function, with it's non-traditional parameter order, has its roots in the versions of FileMaker® databases in use when FX was first created. At that time, FileMaker® databases had a password at most; and sometimes, authentication was not present at all. It was not until version 7 that FileMaker® databases first used user names, and credentials became ubiquitous.

$DBPassword - password to be used for the current query.

$DBUser - (optional) user name to be used for the current query. Default is 'FX'.

// query on PostgreSQL database named "CMS" returning a random record
// to work, there must be a user "FX" with password "saysME"
$serverAddress = '192.168.22.11';
$serverPort = 5432;
$serverType = 'PostgreSQL';
$password = 'saysME';
$databaseName = 'CMS';
$tableName = 'contacts';

$query = new FX($serverAddress, $serverPort, $serverType);
$query->SetDBPassword($password);
$query->SetDBData($databaseName, $tableName);
$queryResult = $query->DoFXAction('show_any');

Used to specify the user name and password required for the current query. It is important that the credentials specified provide the required access to perform the current query.

$DBUser - user name to be used for the current query.

$DBPassword - (optional) password for the specified user. Defaults to blank password.

// will return a random record using the default data source and port
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'knock_knock';
$databaseName = 'Contacts';
$layoutName = 'web_Contact';

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $layoutName);
$randomRecord = $query->DoFXAction('show_any');

By default, FX.php performs "begins with" searches when performing a find. If desired, SetDefaultOperator() can be used to change this behavior — if, for example, most of your queries compare using equals.

$op - the desired default operator. Possible values are covered in detail in the $op parameter section of AddDBParam().

// query on default database named "CMS"
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'password';
$databaseName = 'CMS';
$tableName = 'contacts';

// begins with queries -- would return Jon Smith, Jonathan Smits, etc.
$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName);
$query->AddDBParam('first_name', 'Jon');
$query->AddDBParam('last_name', 'Smit');
$queryResult = $query->DoFXAction('perform_find');

// equals queries -- would return only Jon Smit
$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName);
$query->SetDefaultOperator('eq');
$query->AddDBParam('first_name', 'Jon');
$query->AddDBParam('last_name', 'Smit');
$queryResult = $query->DoFXAction('perform_find');

This function is only for use with FileMaker® version 7 and later databases. In order to ensure that a global field is set properly (before performing a script, for example), use this function instead of AddDBParam() to set the field.

$globalFieldName - the name of the global field to set.

$globalFieldValue - the desired value for the global field.

// will return the found set resulting from the "getNewContacts" script
// using a script parameter of "20" after first setting a global,
// using the default FileMaker ≥ 7 data source and port
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'knock_knock';
$databaseName = 'Contacts';
$layoutName = 'web_Contact';

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $layoutName);
$query->SetFMGlobal('Active_User_global', $_SESSION['user_id']);
$query->PerformFMScript('getNewContacts', 20);
// script found set (if any) will override the random record from the "show_any" query
$foundSet = $query->DoFXAction('show_any');

Because of its heritage, FX.php searches are logical "AND" queries by default. This function toggles the current query to use logical "OR" instead.

By default, FX.php uses the same logical keyword, whether "OR", or "AND", between all elements of a query. For more complex queries that mix the two, the FindQuery_AND() function can be used. When working with SQL data sources, PerformSQLQuery() can be used to explicitly define the SQL query to be performed.

// query on a MySQL database named "CMS" returning 50 rows (the default)
// with first names starting with "Jo" OR last names ending with "sen"
// some possible names returned: Joe Smith, Mark Jensen, John Hansen
$serverAddress = '192.168.22.11';
$serverPort = 3306;
$serverType = 'MySQL';
$username = 'web_user';
$password = 'password';
$databaseName = 'CMS';
$tableName = 'contacts';

$query = new FX($serverAddress, $serverPort, $serverType);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName);
$query->SetLogicalOR();
$query->AddDBParam('first_name', 'Jo'); // begins with is default
$query->AddDBParam('last_name', 'sen', 'ew');
$queryResult = $query->DoFXAction('perform_find');

When editing or deleting records/rows in some more advanced use cases, it can be important to insure that the record/row hasn't changed since the current data was retrieved. For example, this might be useful in a high traffic solution with multiple users performing edits.

$modID - the modification identifier of the specified record/row.

In FileMaker® databases, each record has a built-in ModID that is managed behind the scenes. In the event that a database operation fails because of an outdated ModID, FileMaker® Server will return error code 306.

Basic support for the concept of a column that tracks row modification is built into FX.php via the SetDataKey() method. The second parameter of this method is the name of a column which provides this functionality (e.g. a modification timestamp), and the third parameter allows a separator between the record and modification identifiers — other than a period — to be specified.

// update query on default (FileMaker ≥7) database named "CMS":
// we'll try to grab Ichabod Crane's record, display his current status, then
// set it to "scared!" We're going to decrement the ModID, so this will fail.
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'password';
$databaseName = 'CMS';
$tableName = 'Contacts';

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName);
$query->AddDBParam('first_name', 'Ichabod', 'eq');
$query->AddDBParam('last_name', 'Crane', 'eq');
$findResult = $query->DoFXAction('perform_find');
if (FX::isError($findResult) || $findResult->lastErrorCode != 0) {
    echo 'An error occurred!';
    exit;
}
$ichabodCrane = each($findResult);
list($recordId, $modId) = explode('.', $ichabodCrane['key']);
$ichabodCrane = $ichabodCrane['value'];
echo $ichabodCrane['status'];

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName);
$query->SetRecordID($recordId);
$query->SetModID(--$modId); // decrementing the ModID
$query->AddDBParam('status', 'scared!');
$queryResult = $query->DoFXAction('update');
if (FX::isError($findResult) || $findResult->lastErrorCode != 306) {
    echo 'An unexpected result occurred!';
}
else {
    echo 'ModID value was lower than the value in the database.';
}

FileMaker Only This function is used to edit a portal row, or to create a record via a portal row. It's the equivalent of making several AddDBParam() calls using the full FileMaker® portal syntax for the field name: relationship_name::fieldName.rowIdentifier.

$fieldsArray - an array of the data to be passed into the portal row. Each element of the array should have the FileMaker® field name as the key, with the desired value as the value.

$portalRowID - (optional) the ID of the relevant portal row.

For FileMaker® 7 and later, this means the RecordID of the row in question, whereas for FileMaker 5/6, this is the number of the portal row (e.g. the third row of the portal would be "3".) The default value, 0 (zero), creates a new portal row. Note that only one row may be created in this manner per query, and the associated relationship must allow the creation of records, as appropriate. On the other hand, multiple calls to SetPortalRow() could be used to edit multiple records in a portal via a single FX.php action.

$relationshipName - (optional) the relationship name with which to prefix each field name.

The $relationshipName parameter is intended to reduce repetition in the common case where all fields in a portal use the same relationship. For example, instead of prefixing all of your field names with "myRelationship::", you could just pass "myRelationship" (no double colon) as the value of this parameter.

// update query on default (FileMaker ≥7) database named "CMS":
// for a Contact record with a RecordID of 29 - one record will be created
// in the Contact_Phones portal, and a row with RecordID = 7 will be updated
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'password';
$databaseName = 'CMS';
$tableName = 'Contacts';
$fieldsArray0 = array('number' => '555-555-4321', 'label' => 'cell');
$fieldsArray7 = array('number' => '555-555-4343', 'label' => 'main');

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName);
$query->SetRecordID(29);
$query->SetPortalRow($fieldsArray0, 0, 'Contact_Phones'); // new portal row
$query->SetPortalRow($fieldsArray7, 7, 'Contact_Phones');
$queryResult = $query->DoFXAction('update');

When updating or deleting a single record/row in a database, this method is the typical method of identifying the desired one.

$recordID - the ID of the record of interest.

FileMaker® records have a built-in identifier, the record ID, that is used when working with a specific record. If you're not familiar with how this works, review the "Getting Started" portion of this documentation, especially the FX Parser Output section. There's not a built-in method of updating or deleting multiple FileMaker® records at once, though this can be done via the SetPortalRow() function (if the records of interest appear, or can be made to appear, within the same portal), or by using FileMaker Scripts.

Most SQL data sources do not have built-in identifiers, but rather primary keys. That said, this method is designed to work with SQL databases in a couple of different ways: first, the SetDataKey() can be used to explicitly pass in the name of a primary key field; second, FX.php includes an attribute called $fuzzyKeyLogic which works as part of a system to auto-magically figure out what the identifier column should be. More information about $fuzzyKeyLogic can be found in the documentation for the SQLFuzzyKeyLogicOn() method.

// update query on default (FileMaker ≥7) database named "CMS":
// we'll grab Ichabod Crane's record, display his current status,
// then set it to "scared!"
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'password';
$databaseName = 'CMS';
$tableName = 'Contacts';

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName);
$query->AddDBParam('first_name', 'Ichabod', 'eq');
$query->AddDBParam('last_name', 'Crane', 'eq');
$findResult = $query->DoFXAction('perform_find');
if (FX::isError($findResult) || $findResult->lastErrorCode != 0) {
    echo 'An error occurred!';
    exit;
}
$ichabodCrane = each($findResult);
list($recordId, $modId) = explode('.', $ichabodCrane['key']);
$ichabodCrane = $ichabodCrane['value'];
echo $ichabodCrane['status'];

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName);
$query->SetRecordID($recordId);
$query->AddDBParam('status', 'scared!');
$queryResult = $query->DoFXAction('update');

FileMaker, PostgreSQL, MySQL Only There may be times when it is desirable to skip a certain number of records/rows when returning data (e.g. when setting up a paging interface.) SetSkipSize() will cause FX.php to start returning data with row/record $skipSize + 1.

$skipSize - number of records/rows to skip when returning data.

// query on default (FileMaker, PostgeSQL, or MySQL) database named "CMS":
// we'll skip the first row/record then return the next 10
$serverAddress = '192.168.22.11';
$username = 'web_user';
$password = 'password';
$databaseName = 'CMS';
$tableName = 'contacts';
$groupSize = 10;

$query = new FX($serverAddress);
$query->SetDBUserPass($username, $password);
$query->SetDBData($databaseName, $tableName, $groupSize);
$query->SetSkipSize(1);
$findResult = $query->DoFXAction('show_all');