Library overview

This page briefly explains how the library is structured. It is intended for those who simply want to know where they find which class and for contributors to understand the design decision behind the current structure, so they can make additions in the right place.

Page vs. Client vs. Server

In order to understand our design decisions, we need to clarify some nomenclature first. If you think about it, there are three participants in the communication of any FACT-Finder based shop.

• The browser displaying the shop.
• Your server running the shop.
• The FACT-Finder server.

So there are two servers. But in a way, your server is a client to the FACT-Finder server, just as the browser is a client to your server. To avoid ambiguities with names within the library, we define the following:

• Anything that happens in the browser goes by the name Page
• Your server is called the Client
• The FACT-Finder server is just the Server

We decided to go with this nomenclature, because the library focuses on the communication between the two servers (in which your server becomes the client), whereas any communication with the browser is somewhat peripheral.

Now that we're clear on this, let's look at the library's structure.

The FACTFinder namespace

Everything that belongs to the library itself can be found in the path src/FACTFinder and in the namespace \FACTFinder. Similarly, the subordinate directory tree mirrors the namespace structure.

Right at the root level of that tree there is only one class, the Loader. That's because it's central to using the library in any conceivable way. Anything else goes in subdirectories/namespaces.

The Util namespace

Let's get this out of the way first. This namespace contains everything that is not directly related to the problem domain (i.e. talking to the FACT-Finder server), and could be useful verbatim in any other project. This namespace also contains two external projects, which you'll likely want to use with the library: an abstraction of PHP's cURL interface which makes it easy to mock HTTP requests, as well as Fabien Potencier's amazingly elegant Dependency-Injection Container Pimple (v1, though).

The Data namespace

The classes in this namespace are all simple "struct-like" data containers that represent all kinds of data you can obtain from the FACT-Finder server - from search results to tag cloud elements. It also contains a bunch of classes that mimic enums, such as SearchStatus. The FilterStyle class is thoroughly documented if you need any guidance on how they work. For contributors, if you need to add another enum-like class to the library, please follow the pattern of the existing ones.