1. Introduction
    1. Who should read this document
      • FileMaker developers who are new to web publishing.
      • FileMaker developers who are feeling constrained by IWP.
      • FileMaker developers who have done CWP with FX.php.
      • FileMaker developers who have done CWP with XML/XSLT and are considering a move to PHP.
      • PHP developers who would like to learn how to work with a FileMaker backend.
      • CDML and Lasso developers who are planning to transition to a modern technology.
    2. Purpose of this document
      • This document was created to outline the basic similarities and differences of the FX.php and FileMaker.php classes.
      • This document maintains that developers writing CWP solutions should be familiar with both classes.
      • This document does not globally advocate either option.
      • This document is more conceptual that practical, therefore code examples will be kept to a minimum.
      • This document is not intended to teach the reader how to implement a CWP solution.
    3. Document conventions
      • Throughout this document, the terms "FileMaker API for PHP" and "Filemaker.php" will be used interchangebly.
  2. Code Comparison
    1. Notes on code samples
      • These code samples are not meant to serve as best practices. They are written for relative newcomers and therefore the emphasis is more on clarity than elegance.
      • These code samples are devoid of error checking. Error checking will be handled as it's own topic toward the end of this section.
      • The output of these code samples would normally be nested inside HTML tags, complete with the appropriate document encoding (UTF-8). This has been left out to keep the samples brief and focused.
    2. Code samples

        Note: When working with FX.php, users can choose to use either the original syntax, or a newer, streamlined syntax. Because most users of FX.php will be more familiar with the older syntax, and to keep the examples as consistent as possible, the FX.php examples below use the original syntax.

      • Compound Find 
        <?php

require_once ('FX/FX.php');
$request = new FX('127.0.0.1', '80', 'FMPro7');
$request->SetDBData('TimeTracker.fp7', 'associate_layout');
$request->SetDBUserPass('esmith', 'f!r3crack3r');
$request->SetLogicalOR();
$request->AddDBParam('Account Name', 'M');
$request->AddDBParam('Account Name', 'T');
$request->AddSortParam('Account Name');
$result = $request->FMFind();
$records = $result['data'];

echo '<table border="1">';
echo '<tr>';
echo '<th>Status</th>';
echo '<th>Type</th>';
echo '<th>Account Name</th>';
echo '</tr>';
foreach($records as $record) {
    if ($record['Status'][0] != 'Active') {
        echo '<tr>';
        echo '<td>'.$record['Status'][0].'</td>';
        echo '<td>'.$record['Type'][0].'</td>';
        echo '<td>'.$record['Account Name'][0].'</td>';
        echo '</tr>';
    }
}
echo '</table>';

?>


        <?php

require_once ('Filemaker/Filemaker.php');
$fm = new FileMaker('TimeTracker.fp7', '127.0.0.1', 'esmith', 'f!r3crack3r');

$request = $fm->newFindRequest('associate_layout');
$request->addFindCriterion('Account Name', 'M');

$request2 = $fm->newFindRequest('associate_layout');
$request2->addFindCriterion('Account Name', 'T');

$request3 = $fm->newFindRequest('associate_layout');
$request3->addFindCriterion('Status', 'Active');
$request3->setOmit(TRUE);

$compoundFind = $fm->newCompoundFindCommand('associate_layout');
$compoundFind->add(1, $request);
$compoundFind->add(2, $request2);
$compoundFind->add(3, $request3);
$compoundFind->addSortRule('Account Name', 1, FILEMAKER_SORT_ASCEND);

$result = $compoundFind->execute();
$records = $result->getRecords();

echo '<table border="1">';
echo '<tr>';
echo '<th>Status</th>';
echo '<th>Type</th>';
echo '<th>Account Name</th>';
echo '</tr>';
foreach ($records as $record) {
    echo '<tr>';
    echo '<td>'.$record->getField('Status').'</td>';
    echo '<td>'.$record->getField('Type').'</td>';
    echo '<td>'.$record->getField('Account Name').'</td>';
    echo '</tr>';
}
echo '</table>';

?>
      • Create Record 
        <?php

require_once ('FX/FX.php');
$newRecordRequest = new FX('127.0.0.1', '80', 'FMPro7');
$newRecordRequest->SetDBData('TimeTracker.fp7', 'associate_layout');
$newRecordRequest->SetDBUserPass('esmith', 'f!r3crack3r');
$newRecordRequest->AddDBParam('Account Name', 'twilliams');
$newRecordRequest->AddDBParam('Status', 'Active');
$newRecordRequest->AddDBParam('Type', 'Employee');
$result = $newRecordRequest->FMNew();

?>

        <?php

require_once ('Filemaker/Filemaker.php');
$fm = new FileMaker('TimeTracker.fp7', '127.0.0.1', 'esmith', 'f!r3crack3r');
$record = $fm->createRecord('associate_layout');
$record->setField('Account Name', 'twilliams');
$record->setField('Status', 'Active');
$record->setField('Type', 'Employee');
$result = $record->commit();

?>
      • Delete Record 
        <?php

require_once ('FX/FX.php');
$request = new FX('127.0.0.1', '80', 'FMPro7');
$request->SetDBData('TimeTracker.fp7', 'associate_layout');
$request->SetDBUserPass('esmith', 'f!r3crack3r');
$request->AddDBParam('-recid', '136');
$result = $request->FMDelete();

?>

        <?php

require_once ('Filemaker/Filemaker.php');
$fm = new FileMaker('TimeTracker.fp7', '127.0.0.1', 'esmith', 'f!r3crack3r');
$deleteRecord = $fm->newDeleteCommand('associate_layout', '140');
$result = $deleteRecord->execute();

?>
      • Display Portal Records 
        <?php

// Find associate records
require_once ('FX/FX.php');
$request = new FX('127.0.0.1', '80', 'FMPro7');
$request->SetDBData('TimeTracker.fp7', 'associate_layout');
$request->SetDBUserPass('esmith', 'f!r3crack3r');
$request->AddDBParam('Status', 'Active');
$result = $request->FMFind();
$records = $result['data'];

// Loop through the associate records 
foreach ($records as $record) {

    // Display the current associate record
    echo '<div>';
    echo '<table border="1">';
    echo '<tr><th>Account Name</th><td>'.$record['Account Name'][0].'</td></tr>';
    echo '<tr><th>Status</th><td>'.$record['Status'][0].'</td></tr>';
    echo '<tr><th>Type</th><td>'.$record['Type'][0].'</td></tr>';
    echo '</table>';
    
    // Display the time records in a separate table
    echo '<table border="1">';
    echo '<tr>';
    echo '<th>Date</th>';
    echo '<th>Duration</th>';
    echo '<th>Description</th>';
    echo '</tr>';
    foreach ($record['Time::Date Performed'] as $key => $val) {
        echo '<tr>';
        echo '<td>'.$record['Time::Date Performed'][$key].'</td>';
        echo '<td>'.$record['Time::Hours Actual'][$key].'</td>';
        echo '<td>'.$record['Time::Description'][$key].'</td>';
        echo '</tr>';
    }
    echo '</table>';
    echo '</div>';

}
?>


        <?php

// Find associate records
require_once ('Filemaker/Filemaker.php');
$fm = new FileMaker('TimeTracker.fp7', '127.0.0.1', 'esmith', 'f!r3crack3r');
$request = $fm->newFindCommand('associate_layout');
$request->addFindCriterion('Status', 'Active');
$result = $request->execute();
$records = $result->getRecords();
    
// Loop through the associate records 
foreach ($records as $record) {

    // Display the current associate record
    echo '<div>';
    echo '<table border="1">';
    echo '<tr><th>Account Name</th><td>'.$record->getField('Account Name').'</td></tr>';
    echo '<tr><th>Status</th><td>'.$record->getField('Status').'</td></tr>';
    echo '<tr><th>Type</th><td>'.$record->getField('Type').'</td></tr>';
    echo '</table>';
    
    // Get the time records related to this associate
    $timeRecords = $record->getRelatedSet('Time');
    
    // Display the time records in a separate table
    echo '<table border="1">';
    echo '<tr>';
    echo '<th>Date</th>';
    echo '<th>Duration</th>';
    echo '<th>Description</th>';
    echo '</tr>';
    foreach ($timeRecords as $timeRecord) {
        echo '<tr>';
        echo '<td>'.$timeRecord->getField('Time::Date Performed').'</td>';
        echo '<td>'.$timeRecord->getField('Time::Hours Actual').'</td>';
        echo '<td>'.$timeRecord->getField('Time::Description').'</td>';
        echo '</tr>';
    }
    echo '</table>';
    echo '</div>';

}
?>
      • Edit Record 
        <?php

require_once ('FX/FX.php');
$request = new FX('127.0.0.1', '80', 'FMPro7');
$request->SetDBData('TimeTracker.fp7', 'associate_layout');
$request->SetDBUserPass('esmith', 'f!r3crack3r');
$request->AddDBParam('-recid', '136');
$request->AddDBParam('Account Name', 'ttester');
$request->AddDBParam('Status', 'Inactive');
$request->AddDBParam('Type', 'Contractor');
$result = $request->FMEdit();

?>

        <?php

require_once ('Filemaker/Filemaker.php');
$fm = new FileMaker('TimeTracker.fp7', '127.0.0.1', 'esmith', 'f!r3crack3r');
$editRecord = $fm->newEditCommand('associate_layout', '140');
$editRecord->setField('Account Name', 'twilliams');
$editRecord->setField('Status', 'Active');
$editRecord->setField('Type', 'Employee');
$result = $editRecord->execute();

?>
      • Edit Records 
        <?php

require_once ('FX/FX.php');
$request = new FX('127.0.0.1', '80', 'FMPro7');
$request->SetDBData('TimeTracker.fp7', 'associate_layout');
$request->SetDBUserPass('esmith', 'f!r3crack3r');
$request->AddDBParam('Type', 'Administrator');
$result = $request->FMFind();
$records = $result['data'];

foreach($records as $keys => $record) {
    list($recid, $modid) = explode('.', $keys);
    $request = new FX('127.0.0.1', '80', 'FMPro7');
    $request->SetDBData('TimeTracker.fp7', 'associate_layout');
    $request->SetDBUserPass('esmith', 'f!r3crack3r');
    $request->AddDBParam('-recid', $recid);
    $request->AddDBParam('Type', 'Admin');
    $result = $request->FMEdit();
}

?>


        <?php

require_once ('Filemaker/Filemaker.php');
$fm = new FileMaker('TimeTracker.fp7', '127.0.0.1', 'esmith', 'f!r3crack3r');
$request = $fm->newFindCommand('associate_layout');
$request->addFindCriterion('Type', 'Admin');
$result = $request->execute();
$records = $result->getRecords();

foreach ($records as $record) {
    $record->setField('Type', 'Administrator');
    $record->commit();
}

?>
      • Find 
        <?php

require_once ('FX/FX.php');
$request = new FX('127.0.0.1', '80', 'FMPro7');
$request->SetDBData('TimeTracker.fp7', 'associate_layout');
$request->SetDBUserPass('esmith', 'f!r3crack3r');
$request->AddDBParam('ID Associate', '120..');
$result = $request->FMFind();
$records = $result['data'];

echo '<table border="1">';
echo '<tr>';
echo '<th>Status</th>';
echo '<th>Type</th>';
echo '<th>Account Name</th>';
echo '</tr>';
foreach($records as $record) {
    echo '<tr>';
    echo '<td>'.$record['Status'][0].'</td>';
    echo '<td>'.$record['Type'][0].'</td>';
    echo '<td>'.$record['Account Name'][0].'</td>';
    echo '</tr>';
}
echo '</table>';

?>


        <?php

require_once ('Filemaker/Filemaker.php');
$fm = new FileMaker('TimeTracker.fp7', '127.0.0.1', 'esmith', 'f!r3crack3r');
$request = $fm->newFindCommand('associate_layout');
$request->addFindCriterion('ID Associate', '120...');
$result = $request->execute();
$records = $result->getRecords();

echo '<table border="1">';
echo '<tr>';
echo '<th>Status</th>';
echo '<th>Type</th>';
echo '<th>Account Name</th>';
echo '</tr>';
foreach ($records as $record) {
    echo '<tr>';
    echo '<td>'.$record->getField('Status').'</td>';
    echo '<td>'.$record->getField('Type').'</td>';
    echo '<td>'.$record->getField('Account Name').'</td>';
    echo '</tr>';
}
echo '</table>';

?>
      • Find All 
        <?php

require_once ('FX/FX.php');
$request = new FX('127.0.0.1', '80', 'FMPro7');
$request->SetDBData('TimeTracker.fp7', 'associate_layout');
$request->SetDBUserPass('esmith', 'f!r3crack3r');
$request->AddSortParam('Status');
$request->AddSortParam('Type');
$request->AddSortParam('Account Name');
$result = $request->FMFindAll();
$records = $result['data'];

echo '<table border="1">';
echo '<tr>';
echo '<th>Status</th>';
echo '<th>Type</th>';
echo '<th>Account Name</th>';
echo '</tr>';
foreach($records as $record) {
    echo '<tr>';
    echo '<td>'.$record['Status'][0].'</td>';
    echo '<td>'.$record['Type'][0].'</td>';
    echo '<td>'.$record['Account Name'][0].'</td>';
    echo '</tr>';
}
echo '</table>';

?>


        <?php

require_once ('Filemaker/Filemaker.php');
$fm = new FileMaker('TimeTracker.fp7', '127.0.0.1', 'esmith', 'f!r3crack3r');
$request = $fm->newFindAllCommand('associate_layout');
$request->addSortRule('Status', 1);
$request->addSortRule('Type', 2);
$request->addSortRule('Account Name', 3);
$result = $request->execute();
$records = $result->getRecords();

echo '<table border="1">';
echo '<tr>';
echo '<th>Status</th>';
echo '<th>Type</th>';
echo '<th>Account Name</th>';
echo '</tr>';
foreach ($records as $record) {
    echo '<tr>';
    echo '<td>' . $record->getField('Status') . '</td>';
    echo '<td>' . $record->getField('Type') . '</td>';
    echo '<td>' . $record->getField('Account Name') . '</td>';
    echo "</tr>";
}
echo '</table>';

?>
      • Find Or 
        <?php

require_once ('FX/FX.php');
$request = new FX('127.0.0.1', '80', 'FMPro7');
$request->SetDBData('TimeTracker.fp7', 'associate_layout');
$request->SetDBUserPass('esmith', 'f!r3crack3r');
$request->SetLogicalOR();
$request->AddDBParam('Type', 'Admin');
$request->AddDBParam('Type', 'Intern');
$result = $request->FMFind();
$records = $result['data'];

echo '<table border="1">';
echo '<tr>';
echo '<th>Status</th>';
echo '<th>Type</th>';
echo '<th>Account Name</th>';
echo '</tr>';
foreach($records as $record) {
    echo '<tr>';
    echo '<td>'.$record['Status'][0].'</td>';
    echo '<td>'.$record['Type'][0].'</td>';
    echo '<td>'.$record['Account Name'][0].'</td>';
    echo '</tr>';
}
echo '</table>';

?>


        <?php

require_once ('Filemaker/Filemaker.php');
$fm = new FileMaker('TimeTracker.fp7', '127.0.0.1', 'esmith', 'f!r3crack3r');
$request = $fm->newFindCommand('associate_layout');
$request->setLogicalOperator(FILEMAKER_FIND_OR);
$request->addFindCriterion('Type', 'Admin');
$request->addFindCriterion('Type', 'Intern');
$result = $request->execute();
$records = $result->getRecords();

echo '<table border="1">';
echo '<tr>';
echo '<th>Status</th>';
echo '<th>Type</th>';
echo '<th>Account Name</th>';
echo '</tr>';
foreach ($records as $record) {
    echo '<tr>';
    echo '<td>'.$record->getField('Status').'</td>';
    echo '<td>'.$record->getField('Type').'</td>';
    echo '<td>'.$record->getField('Account Name').'</td>';
    echo "</tr>";
}
echo '</table>';

?>
  3. Performance
    1. Informal performance tests were done to compare the execution time of typical FileMaker web publishing operations.
    2. The goal was to determine if there were any consisent performance differences between FX.php and FileMaker.php.
    3. Performance tests were done on a PowerBook G4 15" with a 1.5 GHz processor and 1GB of RAM running OS 10.4.7, PHP 5.1.4, Apache 1.3.33, and FileMaker Server 8.0v4.
    4. Results
      • Create 1000 records
        • FileMaker.php: 76 seconds
        • FX.php: 69 seconds
      • Return 1000 records
        • FileMaker.php: 3 seconds
        • FX.php: 2 seconds
      • Edit 1000 records
        • FileMaker.php: 73 seconds
        • FX.php: 68 seconds
      • Delete 1000 records
        • FileMaker.php: 90 seconds
        • FX.php: 73 seconds
  4. Debugging and Error Handling
    1. When publishing FileMaker data to the web, two general types of errors can occur: 1) Connection errors, meaning that your PHP page could not make contact with FileMaker Server at all, and 2) FileMaker Errors, which indicate that you page successfully connected to FileMaker, but FileMaker could not execute your request as expected.
    2. Under FileMaker.php, debugging and error handling are centered around the FileMaker Error Object. When testing for errors, you only need to test for one kind of error. In the event of an error, you must perform a further check to determine if that error was FileMaker or connection related.
    3. When using FX.php, connection errors return an FX Error Object. FileMaker errors return a found set as normal, but with a found count of less than one, and flagged with the relevant FileMaker error code. This means that one check needs to be made for a connection error, and a separate check -- with appropriate handling -- for FileMaker errors.
    4. FileMaker.php provides localized versions of FileMaker error messages.
    5. FX.php provides only English versions of FileMaker error messages.
    6. FX.php also allows a DEBUG flag to be set, which will cause FX to output information related to the connection that it is attempting. This output can then be used to check for missing parameters, or even to attempt the connection manually.
    7. FileMaker.php does not provide access to connection information.

      8. Potential Gotcha: Because FX.php sends POST requests to FileMaker by default, and manual connections generally use GET, the connection performed via a manual connection for debugging is not precisely identical to the connection performed by FX.php.

      Note: The latest release of FX.php includes the FX Fuzzy Debugger class which can be used as a debugging aid with either tool.

    8. Debugging Examples (expanded from the FindAll examples, above): 
      <?php

// this can be toggled to true for additional error checking
define('DEBUG', FALSE); 

require_once ('FX/FX.php');
$request = new FX('127.0.0.1', '80', 'FMPro7');
$request->SetDBData('TimeTracker.fp7', 'associate_layout');
$request->SetDBUserPass('esmith', 'f!r3crack3r');
$request->AddSortParam('Status');
$request->AddSortParam('Type');
$request->AddSortParam('Account Name');
$result = $request->FMFindAll();

echo '<table border="1">';
echo '<tr>';
echo '<th>Status</th>';
echo '<th>Type</th>';
echo '<th>Account Name</th>';
echo '</tr>';
if (FX::isError($result)) {
    echo '<tr>';
    echo '<td colspan="3">A System Error Occured</td>';
    echo '</tr>';
} elseif ($result['foundCount'] < 1) {
    echo '<tr>';
    echo '<td colspan="3">No Records Found (Error Code: '.$result['errorCode'].')</td>';
    echo '</tr>';
} else {
    $records = $result['data'];
    foreach($records as $record) {
        echo '<tr>';
        echo '<td>'.$record['Status'][0].'</td>';
        echo '<td>'.$record['Type'][0].'</td>';
        echo '<td>'.$record['Account Name'][0].'</td>';
        echo '</tr>';
    }
}
echo '</table>';

?>


      <?php

require_once ('Filemaker/Filemaker.php');
$fm = new FileMaker('TimeTracker.fp7', '127.0.0.1', 'esmith', 'f!r3crack3r');
$request = $fm->newFindAllCommand('associate_layout');
$request->addSortRule('Status', 1);
$request->addSortRule('Type', 2);
$request->addSortRule('Account Name', 3);
$result = $request->execute();

echo '<table border="1">';
echo '<tr>';
echo '<th>Status</th>';
echo '<th>Type</th>';
echo '<th>Account Name</th>';
echo '</tr>';
if (FileMaker::isError($result)) {
    if (! isset($result->code) || strlen(trim($result->code)) < 1) {
        echo '<tr>';
        echo '<td colspan="3">A System Error Occured</td>';
        echo '</tr>';
    } else {
        echo '<tr>';
        echo '<td colspan="3">No Records Found (Error Code: '.$result->code.')</td>';
        echo '</tr>';
    }
} else {
    $records = $result->getRecords();
    foreach ($records as $record) {
        echo '<tr>';
        echo '<td>' . $record->getField('Status') . '</td>';
        echo '<td>' . $record->getField('Type') . '</td>';
        echo '<td>' . $record->getField('Account Name') . '</td>';
        echo "</tr>";
    }
}
echo '</table>';

?>
  5. Customizablity
    1. FileMaker.php is not an open source product. Therefore, it can be dificult or even impossible to customize it to your needs. In fact, it is a violation of the license agreement to do so.
    2. FX.php is an open source product. As such, developers are free to customize it as they wish. Furthermore, it is a simple matter to "look under the hood" to see how it works, which can be very helpful at times.

      3. Note: Wrapper classes can be created around either tool to add additional, custom functionality.

    3. Installers
      1. FileMaker.php
        • FileMaker, Inc. distributes the FileMaker API for PHP in two forms: a traditional installer, and a bundled version. Both installers are freely available on FileMaker.com.
        • The traditional installer installs not only the FileMaker API for PHP, but also PHP itself. This is very convenient for individuals who do not already have PHP installed.
        • The bundled version is simply a compressed archive of text files that you manually download and place on your hard drive. This is a good option for individuals who do not have root level access to their web server, or who already have PHP installed.

          • Potential Gotcha: If you do use the FileMaker API for PHP Installer, and then subsequently run the Uninstaller, you may need to manually edit your web server software's configuration. In testing on Apache running on Mac OS X, this meant that Apache would not start until httpd.conf had been manually modified.

      2. FX.php
        • FX.php is only distributed as a bundle. It is freely available at iViking.org.
        • As with the FileMaker.php bundle, the FX.php distribution is a compressed archive of text files that you manually download and place on your hard drive.

        3. Potential Gotcha: When doing the manual install for either tool, be sure that the privileges for all related files allow all users read (and possibly execute) access. At the very least, give this level of access to the user under which the server process runs. For security reasons, web server processes run under special low access accounts -- almost certainly not the account used to install the software.

    4. Software Requirements & Compatibility
      1. Platforms: Both technologies run on Mac, Windows, and Linux. It should be noted that there is no FileMaker.php installer for Linux, so you would have to opt for the bundled distribution.
      2. Web Servers: Both technologies work with Apache and IIS.
      3. PHP Versions: Both technologies run on PHP 4.3 or greater.
      4. FileMaker Versions: FileMaker.php requires FMSA 8.0v4 or greater. FX.php works with FileMaker 5 or greater.
      5. Connection Methods: FileMaker.php requires cURL in order to function. FX.php uses cURL by default (if present), but will work without it.
      6. Other Data Stores: FX.php can also be used to talk to MySQL, PostgreSQL, OpenBase, and ODBC data sources. FileMaker.php only works with FileMaker Server Advanced.

        7. Note: On Mac OS X, cURL is present by default, and cURL is installed by the FileMaker installer, if used.

        Potential Gotcha: As is always the case when working with web-based solutions, firewalls and server addressing (among other things) can add complexity when installing, configuring, and/or testing with either tool.

    5. About the Authors
      1. Chris Hansen
        • Chris Hansen, VP of Web Application Development at Scodigo, spent four plus years developing FileMaker web solutions with Lasso and decided there had to be a better way. He was right. In 2001 Chris co-authored FX.php, an open-source class for working with FileMaker data via PHP, and has maintained it ever since. FX.php is freely available at iviking.org.
        • Chris taught himself AppleSoft BASIC at age 14, and has been programming in whatever language came along for over 20 years. Expertise and interests include PHP, Java, HTML, FileMaker, OpenBase, CSS, JavaScript, C, Pascal, PostgreSQL, MySQL, Oracle, stuffing PC innards into Mac cases, and so on.
        • Chris is currently co-authoring the definitive work on using FileMaker with PHP.
      2. Jonathan Stark
        • Jonathan Stark is an author and instructor who specializes in building FileMaker/PHP web applications for creative professionals. He maintains a free website of articles, downloads, and FAQs at jonathanstark.com.