Setting Up the FX Parser
What is FX Parser
The FX Parser is a handy example of how to use the FX class. It is a PHP program that will show you how to setup FX for your particular data source. What FX Parser does after that, is give you a robust and interactive outline of the data array as it comes back from your database server: it parses the returned array into a JavaScript driven HTML viewer.
Installing the FX Class and FX Parser
The FX Parser is distributed with the FX class from github. Make sure you have downloaded the latest version of this distribution.
The FX Class does not have an installer, it is simply in a folder called "FX" or "fxphp". For consistency, go ahead and rename the directory "FX", if it isn't already. To install the FX class put its folder at the root level of your site. Your site should now have the path www.your_domain.com/FX/.
Although installing FX as described above is a great way to get started (especially with a development setup), at some point you'll likely want to move the FX directory somewhere more secure — at the very least, the configuration data is likely quite sensitive. For now, concentrate on becoming more familiar with FX.php and web development. There are more details about this in the Best Practices documentation.
Inside the FX folder are documentation, helper files, and of course the FX Parser. The FX Parser resides in its own folder called "fx_parser" at the root level of the FX folder. With your favorite text editor or IDE open up the document "index.php" inside the "fx_parser" folder and you'll be ready to go!
Recap of what you are about to do
When you become familiar with PHP and the FX class you will be typing your own PHP code, querying against a live databases, and building dynamic web pages. But right now, we're going to show you how that's done using the FX Parser. We will edit some PHP code in the "index.php" document and then load the page to see the results.
Editing the FX Parser "index.php"
The FX Parser is a document call "index.php" inside the "fx_parser" folder at the root level of the "FX" folder. Open "index.php" in your favorite text editor.
We will be editing the lines of code near the top between the lines marked
# BEGINNING OF USER CODE HERE .... # END OF USER CODE HERE
The code you need to modify is well documented. These lines of code are good examples of how you will use FX in your own web solutions. What follows are step-by-step instructions of how to modify these lines of code so that FX Parser works, and you can see how to use the FX Class.
Configuring Your Environment
The first step is to set up the configuration variables at the top of the USER CODE section. The comments here will walk you through what each item does. For now, leave the $recordsPerPage variable at its initial setting.
# First off, change the values below to match how your database server is
# set up. Keeping things together this way, and using variables, makes it
# easier to find things and change them later.
#
# Your database server's address may be an IP address like "192.168.1.12",
# or it may be a hostname like "fms.your-domain.com".
$serverAddress = 'your_server_address';
# The port on which the database server is listening, usually:
# - 80 for FileMaker Server
# - 3306 for MySQL
# - 5432 for PostgreSQL
$serverPort = 80;
# The type of server being accessed. For FileMaker, the XML has not changed
# since version 7 (though you may use FMPro13, for example, if you prefer.)
# You can also use mysql, postgresql, etc. See the functions documentation
# for more details.
$serverType = 'FMPro7';
# The username and password combination for your database. In FileMaker,
# this user will need the fmxml extended privilege (note that FX.php does NOT
# use the php extended privilege in FileMaker.)
$username = 'your_username';
$password = 'your_password';
# The name of your database and layout (table for SQL data sources) are
# specified here, as well as how many records (rows) you would like returned
# at once (this example limits the result record set to 3)
$databaseName = 'your_database';
$layoutOrSqlTable = 'your_layout';
$recordsPerPage = 3;
Once you've set these to match your environment, you're ready for the next step. If a value is a string (that is, text), be sure to enclose it in quotes!
Instantiating and Configuring the FX Object
The next line of code needs to tell PHP where the FX object code is located. You do this by using the include or require statement(s).
require_once('../FX.php');
With this line, we’ve loaded the FX object so if PHP receives any calls to FX functions they can be executed.
Now we need to get FX going. This is done be creating an FX object. Once we create an FX object then we can start talking to it and telling it what to do.
$query = new FX($serverAddress, $serverPort, $serverType);
No tricks here. You are saying that the variable $query will be an FX object. When creating the FX object called $query, three variables that you set above are used: $serverAddress contains the address of your database server, $serverPort is the port number on which your database server is listening, and $serverType is the type of data source you are using. More information on this is found in the FX functions documentation.
Now that we have an "instance" of FX, we can work with it and eventually tell it to give us the results of a find of our choice.
Two important lines come next, one deals with authentication and the other with the database. First, authentication:
$query->SetDBUserPass($username, $password);
Of course your web available databases should be protected with user names and passwords. Notice the syntax here:
$query->SetDBPassword ...
To use the functions in an FX class object, we first type the object's name, $query, then we use the symbols ->, then we type the function. This syntax for calling object functions and setting object parameters is consistent throughout the object oriented programming of PHP and will be used when working with the FX class.
Next, we need to tell $query, which database file to use and which layout to work from. Again, this information is contained in the variables that you prepared above.
$query->SetDBData($databaseName, $layoutOrSqlTable, $recordsPerPage);
The SetDBData() function is used here. The first two parameters are your file name and layout name respectively. The last parameter $recordsPerPage is optional — you could completely remove it and the preceding comma, and your code would still work (though you might get more records at once than you'd wanted since it specifies how many records to display in the result.)
Review of our New FX Object
So far we have told PHP where to find the FX related code by using a require statement. We then created an FX object called $query, passing the server address, port number and datasource type as parameters.
Once the FX object was created we called the two basic and essential functions: SetDBUserPass() and SetDBData(). PHP now knows about FX and can execute its code. FX now knows about your database server, it's port, username, password, database name, and layout (or SQL table) name.
Don’t forget to make sure the account you use for this job has access to the database and layout or table that was specified.
We are now at exactly the same point in a FileMaker® database that a user would be if they just opened up a file, logged in, and navigated to a specific layout. What we're going to do now is perform a find using that layout.
Performing the Find
In FileMaker® Pro, you would perform a find by entering find mode first, and then typing the criteria in the desired field(s). With FX it's even easier because you don't have to enter find mode, you just start entering find criteria right into the fields. This is done with the AddDBParam() function. Only one AddDBParam() function per field — there are some FX functions that you may prefer as you become more experienced.
$query->AddDBParam('your_field_name', 'your_find_criteria');
Again, your parameters for this function are strings, so you will need to enclose them in quotes. To search on criteria in more than one field you just keep adding AddDBParam() lines.
$query->AddDBParam('your_field_name2', 'your_find_criteria2');
$query->AddDBParam('your_field_name3', 'your_find_criteria3');
In FileMaker® Pro, the logical OR can be added to a find by creating new find requests. In SQL, you would separate your find criteria with the keyword "OR". To do this with FX, you simply call the SetLogicalOR() function, like so:
$query->SetLogicalOR();
This SetLogicalOR() line creates a new Find Request. Just like being in FileMaker® Find Mode and then selecting "New Request" from the menu.
You can now populate the fields in this request by using the AddDBParam() function, one line per field, just like you did on the first request. When you are satisfied with the criteria setup for your find you ready to perform the find.
Some of you may be saying at this point: "but what if I want a find that combines logical AND and logical OR?" There's an FX function for that, but it's complex enough to be outside of the scope of this basic "getting started" documentation. It's called FindQuery_AND() and you can see more about it in the functions documentation.
Actually performing the find is the easiest part. This is done with the function FMFind() with one important difference. You need to use a new variable for the last function to work: a new variable that will hold the results of your search. If you just type
$query->FMFind();
it will indeed perform a find, but it also wants to give you an array of the results. You need to define a variable to hold that array.
So, a proper find is executed with code like this,
$queryResult = $query->FMFind();
and that is exactly what you see in the FX Parser. Please remember that the code
$queryResult = $query->FMFind();
must not be changed in the FX Parser. The Parser will work with an array call $queryResult and if you change the name of that variable... oops... it breaks.