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. At the end of the page there is a checklist you can go through when upgrading your integration.

In addition to this article, it may be helpful to compare the demo of the framework with the demo of the library. They are very similar in structure and feature set, which highlights the differences in usage between framework and library.

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.

Renamed and split-up classes

A few classes have been restructured and renamed, to better follow the single responsibility principle (SRP) and get more expressive names:

• What used to be the Configuration is now Core\XmlConfiguration which is just one particular implementation of Core\ConfigurationInterface.
• What used to be the EncodingHandler is now several implementations of the Core\AbstractEncodingConverter such as Core\Utf8EncodingConverter.
• What used to be the ParameterParser has been separated into:
  • Core\Client\RequestParser which reads query parameters and request targets from the current request. It also takes care of the client URL encoding, so that the resulting strings are properly UTF-8 encoded.
  • Core\Client\UrlBuilder which generates links to the Client for use on the Page.
  • Core\ParametersConverter which applies the parameter rules defined in the configuration. This one is no longer needed outside the library.
• Adapters no longer have Adapter in their names, because it's already in the namespace. E.g. Adapter\Search instead of SearchAdapter.
• Everything relating to server communication has undergone a significant change. What used to be only different implementations of a DataProvider is now a set of several classes, which aim to follow the SRP and flexibly handle different technologies for talking to the server. See the separate article Adapters, Requests and Data Providers for an in-depth documentation of the new system.

Setting up dependencies

To use the adapters of the framework you had to set up a bunch of dependencies first, including a configuration, an encoding handler, a parameters parser and a data provider. This situation has become slightly worse: due to a better separation of concerns in the library there are now a few objects that need to be created.

To make this tedious setup process a bit more convenient, the library ships with Fabien Potencier's dependency-injection container Pimple. You can get hold of an instance with

$dic = FF::getInstance('Util\Pimple');

Have a look at the annotated source code of the demo to see how you can set up all the necessary dependencies.

Upgrade checklist

Now that we've covered all the changes, here is a summary of things to look out for when upgrading your integration:

• Make sure you are using PHP 5.3 (or newer) and FACT-Finder 6.9 (or newer).

• Choose the most recent library release for your FACT-Finder version. The README.d contains an overview of library releases.

• If you are using the XML configuration provided by the library (as opposed to rolling your own), update the elements that have changed (see section on configuration above).

• After including the Loader.php, add the following declaration:

  use \FACTFinder\Loader as FF;
  

  You may need to do this in each file that uses the loader.

• Create a Pimple instance

   $dic = FF::getInstance('Util\Pimple');
  

• Adjust your dependency setup. You can use the demo's initialization script as a starting point. You may even be able to copy it verbatim.

• Go through any other FF::getInstance() calls and update all the class identifiers. In particular, change things like xml69/searchAdapter to Adapter\Search and so on. For other classes, look at source tree or this library overview to find out where they went. Some constructor signatures changed as well, so it's worth taking extra care with this step.

• Lastly, if your integration contains any customizations, then you'll have to make these work with the new library, of course. This may be as simple as putting the classes in the new FACTFinder\Custom directory and namespace and changing the name of the base class, or it may require deeper changes - especially if you customized, for instance, the DataProvider. Don't hesitate to contact support if you need any help.

That's it!

From a usage perspective these are all the changes from framework to library! If you find this guide leaves something to be desired or you still have some trouble doing the upgrade, please open an issue. We'll then look into helping you out and improving the guide where it's unclear.