-
Notifications
You must be signed in to change notification settings - Fork 15
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.
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.
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.
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 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.
As the name implies, this is where all the magic happens. It contains three sub-namespaces corresponding to the above participants of the communication: Page, Client and Server.
Page is currently empty (which further highlights the focus on the communication between the two servers), but may in the future contain some convenient helpers for generate HTML/JavaScript snippets.
Client contains two classes related to communication with the Client (your server). Note that the Client\UrlBuilder generates URLs to the Client (which will however be displayed on the Page).
Server contains a number of classes and alternative implementations that take care of requesting data from the FACT-Finder server.
Additionally, there are a few classes directly in FACTFinder\Core which are either very central to the library (e.g. Configuration interface and implementations) or pertain to multiple participants, e.g. the ParametersConverter which converts parameters between Client and Server URLs.
While you may have to interact with some classes in Core, those are just to set up the adapters. They provide the real functionality you are usually looking for. Each adapter provides access to one FACT-Finder feature (currently there is 1:1 corresponds between adapter classes and actions on the FACT-Finder server). Therefore, this namespace contains the main chunk of the library's "public" API (PHP doesn't really provide any means to hide any of the library's classes, but a bunch of classes in Util and Core are intended only for internal use).
This namespace is and will always be empty. However, you can overwrite pretty much any class in the library by inheriting from it and putting your subclass in the Custom namespace under the same name. The Loader will always first try to find a class in there, before falling back to the library's own implementation (see Loader and name lookup for more details). Note that this is only really necessary for classes that are not dependency-injected anyway.
As an example, if you want to make some tweaks to \FACTFinder\Core\Server\UrlBuilder you can add a class \FACTFinder\Custom\Core\Server\UrlBuilder in the file src/FACTFinder/Custom/Core/Server/UrlBuilder.php (inheriting from the library's implementation). You should even be able to run our test suite to see if everything still works with your changes.