PHP Sample and "PHP API" (Reusable Functions) - IBM OmniFind Yahoo! Edition

This information still applies, but as of OmniFind Yahoo! Edition 8.4.1 the PHP sample is included with the product so it does not need to be downloaded separately.

From the IBM OmniFind Yahoo! Edition Blog (http://blog.360.yahoo.com/omnifind)

The great thing about a REST API like IBM OmniFind Yahoo! Edition's is that it is both development language and platform neutral. The bad thing about a REST API like OmniFind Yahoo! Edition's is that it is development language and platform neutral. Using a REST API is not like using an API that is "native" to a particular language. Someone will surely develop a language that uses REST as the native method calls (or maybe it's been done, leave me a comment if you know), but until that time we all use things like JSPs, PHP or Ruby on Rails for web development.

We know that many of you are using PHP to build your search applications, and it's not as easy as it would be with a "PHP native API". An ad-hoc team of OmniFind developers, Bruce Tannenbaum and Louis Gates, and Visual Designer Robert Lee have come together to provide some relief in the form of a sample application and a set of PHP functions that should make developing PHP search applications much simpler.

Besides being a useful head start for PHP development, some users wanting to provide web site search (as opposed to intranet search) have struggled with how to have their web server in the firewall DMZ but their OmniFind Yahoo! Edition server behind the firewall. This requires having a search application that uses the REST API for remotely invoking OmniFind Yahoo! Edition. This sample application is probably the fastest way to get going with a REST API-based remote search application.

Let's Get Started

1. First, you need to get PHP 5 running on your web server. PHP 5 is required as the sample application uses the SimpleXML extension. Search the web and follow instructions specific to your platform. If your site is hosted, consult your ISP's instructions for enabling PHP 5. Once you think you have it setup, try putting a simple PHP script (call it test.php) into your web server's document space to confirm PHP is setup:

Code:

<?php phpinfo() ?>

Now open the test.php file from your web browser, in my case at:

http://92.168.1.5/testApp/test.php

You should see something vaguely like this:

2. ~~Download the PHP_Sample.zip file~~ ~~(http://omnifind.ibm.yahoo.net/blog/resources/PHP_Sample.zip) and copy the contents to somewhere in your web server's document space where you want the application to live.~~ This sample is now shipped with the product in the "examples" directory. Open up the search.php page with your browser to ensure that all is well. On my machine, I use:

http://92.168.1.5/testSearchApp/search.php

And here is the result:

3. Now you need to tell this PHP application where OmniFind Yahoo! Edition is. Modify the location of your IBM OmniFind Yahoo! Edition server in the search.php file. Find this line:

Code:

$oyeUrl = "http://localhost:8888/api/search?index=Default&start=" . $start . "&results=" . $resultsPerPage;

And modify it to reflect the name or IP address and the port of your OmniFind Yahoo! Edition server. In my case, it looks like:

Code:

$oyeUrl = "http://92.168.1.5/api/search?index=Default&start=" . $start . "&results=" . $resultsPerPage;

4. There is no four! You are done. Try a search, it should look something like this:

Now you can go crazy customizing the look and feel of the application. It's all just a standard, simple PHP application. Start with the images in the image directory and the cascading stylesheet in the css directory. You can also modify the search.php file of course for more in depth changes.

One change you may want to make is to the results per page. It is controlled by this line in search.php:

Code:

$resultsPerPage = 10;

The PHP Functions

oye.php serves as a reusable set of PHP functions for OmniFind Yahoo! Edition that you can use in any PHP search application. The best way to get familiar with the PHP functions available in oye.php is to read through the PHP application that uses them, search.php. Then try them out yourself. Here is a list of the functions provided:

search($queryString) - execute a search

getTotalResults($feed) - get the total results available for the completed search

getSearchTerms($feed) - get the terms that were used in the completed search

getSpellCorrections($feed) - get any spelling suggestions OmniFind might have made for the completed search

getStartIndex($feed) - get the starting result for this completed search (this may be a search to return additional results for a page that is not the first page)

getSearchResults($feed) - get the search results for the completed query as Results objects

getFeaturedLinks($feed) - get the featured links (if any) for the completed query as Results objects

And for each document returned from the search, the Result class has the following methods which should be self-explanatory:

getTitle()

getSummary()

getLink()

getRelevance()

Troubleshooting the Sample Application

If you get the PHP code in your browser, rather than the rendered HTML page, that means your web server is not successfully configured for PHP and so it is serving up the page as a text file rather than interpreting the PHP code. Make sure you can successfully run the sample code from the "Getting Started" section above before trying the sample application.

If you get an error like this one:

Then the SimpleXML extension is not available. It probably means your are not running PHP 5.

If you get a long delay or a communications error then it means that PHP on your web server machine could not communicate with the IBM OmniFind Yahoo! Edition instance. Either you didn't remember to update the server and port in the search.php file, or your web server can't successfully communicate to your OmniFind Yahoo! Edition server (could be a firewall or DNS issue) or OmniFind Yahoo! Edition is not running.

Good luck!
Sean