Zu Handbuch PHP-API

Golem_Api_Article_Search – Artikel suchen

Mit der Klasse Golem_Api_Article_Search durchsuchen Sie Artikel nach einem oder mehreren Begriffen im Volltext auf Golem.de.

Einbindung

require_once '[Installationsort/]Golem/Request.php';
require_once '[Installationsort/]Golem/Api/Article/Search.php';

Verwendung

Die Parameter einer Suchabfrage

Für eine Suche können Sie neben den eigentlichen Suchbegriffen weitere Parameter angeben, welche die Menge der Suchergebnisse regulieren.

Die Suchergebnisse werden auf "Seiten" (Pages) aufgeteilt, mit einer Suchanfrage erhalten Sie nur eine einzelne Seite, mit weitere Suchabfragen blättern Sie durch die Suchergebnisse. Pro Seite können Sie sich zwischen 1 und 50 Ergebnisse liefern lassen.

Rufen Sie die Suche zum ersten Mal auf, reicht es aus, die Suchbegriffe zu setzen und die Anzahl der Ergebnisse (Items) pro Seite. Werden bei einer Suche mehr Artikel gefunden als pro Seite übergeben werden, und wollen Sie weitere Ergebnisse erhalten, dann starten Sie weitere Anfragen. Bei den nachfolgenden Abfragen müssen sie zusätzlich die jeweilige gewünschte Seite (Start-Index) angeben.

Beispiel: Für eine Suche wurde die Anzahl der Items auf 20 gesetzt. Es wurden aber 47 Artikel gefunden. Die 1. Seite enthält die ersten 20 Suchergebnisse. Wenn Sie nun die nächsten 20 Artikel haben möchten, führen Sie eine weitere Abfrage durch, bei der sie den Start-Index auf 2 setzen. Für die restlichen 7 Artikel setzen Sie in einer dritten Abfrage den Start-Index auf 3.

  Übergebene Parameter: Zurückgelieferte Suchergebnisse
Start-Index Items pro Seite
1. Aufruf 1 20 1. - 20. Artikel
2. Aufruf 2 20 21. - 40. Artikel
3. Aufruf 3 20 41. - 47. Artikel

Suche durchführen

Um ein neues Objekt der Klasse Golem_Api_Article_Search zu erzeugen, übergeben Sie lediglich dem Konstruktor Ihren Entwicklerschlüssel:

$request = new Golem_Api_Article_Search($developerKey);
Beispiel 1: Objektinitialisierung

Alle weiteren Parameter für die Suche setzen Sie mit den Methoden

  • setQuery() für die Suchbegriffe
  • setStartIndex() für die gewünschte Suchseite
  • setItemsPerPage() für die Anzahl der Ergebnisse pro Seite
Wenn Sie die beiden letzten Methoden nicht verwenden, dann werden die Standardwerte für diese Parameter verwendet.
$request->setQuery('Suchbegriff');
$request->setStartIndex(1);
$request->setItemsPerPage(10);
Beispiel 2: Suchparameter setzen

Die Suche führen Sie durch mit der fetch()-Methode. Wenn Sie erfolgreich war, dann liefert Ihnen die Methode getArticles die gefundenen Artikel zurück.

$request->fetch();

$articles = $request->getArticles();
Beispiel 3: Abfrage starten und Daten holen

Seitennavigation

Wenn die Suche mehr Ergebnisse zurückliefert als auf eine Seite passen, müssen Sie zumindest Navigationselemente zum Vor- und Zurückblättern durch die Ergebnisse anbieten.

Die notwendige Logik umfasst nur wenige Bestandteile. Sie benötigen eine Bedingung für die Darstellung des Zurückblättern-Elementes. Wenn die aktuelle Seite nicht die erste Seite ist, dann gibt es eine Vorgänger-Seite, können also das Zurück-Element darstellen:

 if(0 < ($request->getStartIndex() - 1)) {

  ...

 }
Beispiel 4: Bedingung für die Darstellung der Seite-Zurück-Navigation

Die Methode getStartIndex() liefert die aktuelle Seitenzahl. Sie sollten unbedingt diese Methode verwenden, auch wenn Sie die aktuelle Seitenzahl bereits vor der Suchabfrage kennen. Nach einer erfolgreichen Abfrage kann dieser Wert nicht mehr dem ursprünglich gesetzten entsprechen. Das ist insbesondere dann der Fall, wenn Parameter ausserhalb des zulässigen Wertebereichs lagen.

Die Bedingung für die Darstellung des Vorblätter-Elementes prüfen Sie, ob die Anzahl der gesamten Suchergebnisse (getTotalResult()) größer ist, als das Produkt aus der aktuellen Seitenzahl (getStartIndex()) und der Anzahl der Ergebnisse pro Seite (getItemsPerPage). Auch diese Werte können nach einer erfolgreichen Seitenabfrage nicht mehr dem ursprünglich gesetzten entsprechen.

if($request->getTotalResults() 
     > ($request->getStartIndex() * $request->getItemsPerPage())) {

  ...

}
Beispiel 5: Bedingung für die Darstellung der Nächste-Seite-Navigation

Fehlerbehandlung

Während der Datenabfrage können Fehler auftreten:

  • Golem_Api_Article_Search::ERROR_QUERY_TOO_LONG bedeutet, dass die Query zu lang war.
  • Golem_Api_Article_Search::ERROR_TOO_MUCH_WORDS bedeutet, dass die Query zu viele Suchbegriffe enthält.
  • Golem_Api_Article_Search::ERROR_WORD_TOO_LONG bedeutet, dass die Query einen Suchbegriff enthält, der länger ist als erlaubt.
  • Golem_Api_Article_Search::ERROR_WORD_TOO_SHORT bedeutet, dass die Query einen Suchbegriff enthält, der zu kurz ist, um als Suchbegriff verwendet zu werden.

Wenn während der Abfrage ein Fehler auftritt, wird eine Exception geworfen, die Sie mit try-catch auffangen können.

try {

 $request->fetch();

} catch(Exception $e) {

 switch($e->getErrorCode()) {

  case Golem_Api_Article_Search::ERROR_QUERY_TOO_LONG :
       ...
       break;
  case ...

 }

}
Beispiel 6: Fehler abfangen

Verfügbare Artikeldaten

Für jeden Artikel werden folgende Eigenschaften mitgeliefert:

Name Bedeutung
articleid Artikel-Identifier
abstracttext Der Abstract des Artikels, eine Kurzzusammenfassung des Inhaltes
headline Die Überschrift des Artikels
date Das Veröffentlichungsdatum als UNIX-Timestamp in Millisekunden
url Die URL des Artikels

Vollständiges Beispiel

<?php

$developerKey = ''; // insert your developer key here

require_once 'Golem/Request.php';
require_once 'Golem/Api/Article/Search.php';

$query    = '';
$page     = 1;
$articles = array();

$backElement = ' ';
$nextElement = ' ';

$error = '';

if (isset($_GET['query']) && '' != $_GET['query']) {

 $query = $_GET['query'];

}

if (isset($_GET['page']) && preg_match('/\d+/', $_GET['page'])) {

 $page = $_GET['page'];

}

if ('' != $query) {

 $request = new Golem_Api_Article_Search($developerKey);

 $request->setQuery($query);
 $request->setStartIndex($page);
 $request->setItemsPerPage(10);

 try {

  $request->fetch();

  $articles = $request->getArticles();

  $baseLink = $_SERVER['PHP_SELF'].'?query='.$query.'&page=';

  if (0 < ($request->getStartIndex() - 1)) {

   $backElement = '<a href="'.
                  $baseLink.($request->getStartIndex() - 1).
                  '">Previous page</a>';

  }

  if ($request->getTotalResults() >
      ($request->getStartIndex() * $request->getItemsPerPage())) {

   $nextElement = '<a href="'.
                  $baseLink.($request->getStartIndex() + 1).
                  '">Next page</a>';

  }

 } catch (Exception $e) {

  $error = $e->getMessage();

 }

}

?>
<html>
 <head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <title>Golem.de Article search example</title>
 </head>
 <body>
  <form action="<?php echo $_SERVER['PHP_SELF']; ?>" method="GET">
   Suchbegriff: <input type="text" name="query" 
                          value="<?php echo $query; ?>">
   <input type="submit" value="Suchen">
  </form>

  <?php echo $error; ?>

  <?php
   if (0 < count($articles)) {
  ?>

    <ul>
     <?php

      foreach($articles as $article) {

       echo '<li>';
       echo '<h1>'.$article['headline'].'</h1>';
       echo '<p>'.$article['abstracttext'].'</p>';
       echo '<a href="'.$article['url'].'">mehr...</a>';
       echo '</li>';

      }

     ?>
    </ul>

    <span style="float:left;">

     <?php echo $backElement; ?>

    </span>
    <span style="float:right;">

     <?php echo $nextElement; ?>

    </span>

  <?php
   }
  ?>

 </body>
</html>


Zu Handbuch PHP-API