1 files changed, 150 insertions, 0 deletions
diff --git a/lib/classes/librarysearch/LibrarySearch.php b/lib/classes/librarysearch/LibrarySearch.php
new file mode 100644
index 0000000..473eacf
--- /dev/null
+++ b/lib/classes/librarysearch/LibrarySearch.php
@@ -0,0 +1,150 @@
+<?php
+/**
+ * This file is part of Stud.IP.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License as
+ * published by the Free Software Foundation; either version 2 of
+ * the License, or (at your option) any later version.
+ *
+ * @author      Moritz Strohm <strohm@data-quest.de>
+ * @copyright   2020
+ * @license     http://www.gnu.org/licenses/gpl-2.0.html GPL version 2
+ * @category    Stud.IP
+ * @since       4.6
+ */
+
+
+/**
+ * This class contains basic methods for querying a library catalog
+ * using standardised search parameters.
+ */
+abstract class LibrarySearch
+{
+    //The following constants define the strings for the
+    //standardised field names for the query method. These can be
+    //converted to library-specific field names.
+    const TITLE       = 'title';
+    const AUTHOR      = 'author';
+    const YEAR        = 'year';
+    const NUMBER      = 'number';
+    const ISSN        = 'issn';
+    const ISBN        = 'isbn';
+    const PUBLICATION = 'publication';
+    const SIGNATURE   = 'signature';
+
+    //Constants for the ordering of results.
+    const ORDER_BY_RELEVANCE = 'relevance';
+    const ORDER_BY_YEAR = 'year';
+
+
+    /**
+     * The base URL for the HTTP request to retrieve data.
+     */
+    protected $request_base_url = '';
+
+
+    /**
+     * Additional URL parameters for the HTTP request to retrieve data.
+     */
+    protected $request_url_parameters = [];
+
+
+    /**
+     * Implementation-specific configuration that can define the behavior
+     * of the LibrarySearch implementation.
+     */
+    protected $settings = [];
+
+
+    /**
+     * A basic constructor.
+     *
+     * @param array $configuration The configuration for the LibrarySearch
+     *     implementation. It should be an associative array with the following
+     *     keys:
+     *     - base_url: The base URL for retrieving data.
+     *     - additional_url_parameters: Additional URL parameters for the base URL.
+     *     - settings: Implementation-specific configuration. This should also
+     *         be an associative array.
+     */
+    public function __construct(array $configuration = [])
+    {
+        if ($configuration['base_url']) {
+            $this->request_base_url = $configuration['base_url'];
+        }
+        if (is_array($configuration['additional_url_parameters'])) {
+            $this->request_url_parameters = $configuration['additional_url_parameters'];
+        }
+        if (is_array($configuration['settings'])) {
+            $this->settings = $configuration['settings'];
+        }
+    }
+
+
+    /**
+     * This method shall replace the generalised search query fields with the
+     * implementation specific query fields.
+     *
+     * @param array $query_fields An array with query parameters using the
+     *     generalised query fields.
+     *
+     * @returns array The translated version of the $query_fields array.
+     */
+    abstract protected function translateQueryFields(array $query_fields = []) : array;
+
+
+    /**
+     * A common method for the libcurl code to request data from an URL so that
+     * LibrarySearch implementations don't have to include their own libcurl
+     * code to get data.
+     *
+     * @param string $base_url The base URL to request data from.
+     *
+     * @param array $url_parameters URL parameters for the request. The array
+     *     should consist of an associative array with keys representing
+     *     the parameter name and the values representing the parameter values.
+     *
+     * @returns string|bool The result of the request. If the base URL is empty
+     *     or no data could be retrieved due to an error, false is returned.
+     *     In case of success, a string with the retrieved data is returned.
+     */
+    protected function requestData(string $base_url = '', array $url_parameters = [])
+    {
+        if (!$base_url) {
+            return false;
+        }
+        $full_url = $base_url;
+        if ($url_parameters) {
+            $full_url .= '?' . http_build_query($url_parameters);
+        }
+
+        $data = file_get_contents($full_url, false, get_default_http_stream_context($base_url));
+        return $data;
+    }
+
+
+    /**
+     * Starts a query to a library catalogue using the specified
+     * parameters. If standardised parameters as defined in the FIELD_
+     * constants of this class are used as keys in the $search_parameters array,
+     * their keys may be converted to library-specific search keys.
+     *
+     * @param array $search_parameters The search parameters to be used.
+     *     The array must be an associative array where the keys represent
+     *     the fields.
+     *
+     * @param string $order_by
+     *
+     * @param int $limit The maximum amount of items that shall be retrieved
+     *     from the catalog.
+     *
+     * @returns LibrarySearchResult[] An array of LibrarySearchResult items
+     *     if entries matching the search could be found in the library.
+     */
+    abstract public function query(
+        array $search_parameters = [],
+        string $order_by = self::ORDER_BY_RELEVANCE,
+        int $limit = 200
+    ) : array;
+}