Upgrade guide

This page is intended for users of the old FACT-Finder-PHP-Framework (referred to as "the framework" in the following) who wish to upgrade to the new FACT-Finder-PHP-Library (referred to as "the library"). It explains the changes between the framework (as of v2.5.5) and the library (as of v1.0.0) along with information about how those changes may affect your integration. Note that this is not an in-depth manual: it assumes you are familiar with the framework and focuses only on the changes.

Prerequisites

The minimum PHP version to use the library is 5.3 (the framework only needed 5.1.2). Make sure your server runs at least this version.

The library does not support FACT-Finder versions before 6.9 (the framework supported all versions since 6.5).

The library no longer has the Zend framework as a dependency. It was only used for the XML configuration where we roll our own now.

Namespaces

One of the main milestones of PHP 5.3 is the introduction of namespaces. So we ditched the pseudo-namespace naming conventions of the old framework in favor of actual namespaces. We still follow the Zend Framework conventions which means that the directory structure mirrors the name spaces. However, if you only want to use the library (as opposed to contributing to it), this barely affects you as long as you obtain all your objects from the Loader.

Using the Loader

The framework came with a convenient alias FF for the loader. However, now that we have namespaces we don't want to pollute the global namespace with the library. You can easily create the alias yourself though:

use \FACTFinder\Loader as FF;

Furthermore, class identifiers passed to the loader now use UpperCamelCase (or PascalCase is you prefer) instead of lowerCamelCase and backslashes instead of forward slashes. So where you might have done FF::getInstance('data/tagQuery'); before (this class didn't exist, but take it as an example), you would now do

FF::getInstance('Data\TagQuery');

Note that this is just just the fully qualified class name minus the leading \FACTFinder\. For more information on the loader, see Loader and name lookup.

Different FACT-Finder versions

The framework supported all versions of FACT-Finder through different versions of its adapters. This has become a massive burden for maintenance and code clarity. Each major release of the library will always only support the most recent FACT-Finder version (starting with 6.9)! If your FACT-Finder server has an older version than the currently supported one, please refer to the README.md which contains an overview of the library's major releases and which FACT-Finder version they support. This also means, that you shouldn't follow library updates that change the major version (these are not backward-compatible anyway by semantic versioning).

Different FACT-Finder APIs

The framework was designed to support all of FACT-Finder's different APIs (JSON and XML were implemented, Web Service would have been possible, too). Since there is a clear recommendation to use the JSON interface, the library does not provide that choice to the user any longer. There are a few features that don't yet provide a JSON interface or which are easier to deal with using raw data output. The library may use something else than JSON in those cases.

The point here is that the choice of interface does no longer need to concern the user of the library but is only an implementation detail. In cases like search suggestions, where some users might need raw data and some might need JSONP (depending on their suggest implementation), the library does provide the alternatives as distinct methods of the same adapter.

The Library's Structure

The above two changes mean that you will no longer see things Xml65 or Json68 in the class names/identifiers. There is only one implementation for each feature. We used this opportunity to overhaul the entire library structure into more sensible namespace. See Library overview to find your way around the new tree.

Configuration

The XML configuration looks mostly the same as before, with a few minor changes (the list is structured like the XML tree):

• The root tag is called configuration instead of config.
  • The section search has been renamed to connection.
    • The section auth has been renamed to authentication.
    • In the options scicTimeout and scicConnectTimeout, scic has been renamed to tracking.
  • The section params has been renamed to parameters.
  • There are only two encoding options now:
    • pageContent
    • clientUrl

Please refer to A Note on Encodings for more information about how the library deals with different encodings.