Twitter mit PHP nutzen

1. Vorwort

Twitter ist ein sehr bekanntes soziales Netzwerk und ein Micro-Blogging-Dienst  der es seinen registrierten Benutzern erlaubt, Kurznachrichten in einer Länge von bis zu 140 Zeichen zu senden und zu lesen. Diese Nachrichten sind auch als sog. Tweets bekannt.

Die Nachrichten eines Benutzers werden auf seiner jeweiligen Profilseite unter twitter.com angezeigt und werden an weitere Benutzer verschickt, die dessen Nachrichten abonniert haben (in diesem Fall 'folgen' sie dem Nutzer). Die Kurznachrichten können über das dafür vorgesehene Webinterface auf der genannten Webseite, über eine der Gateway-SMS-Telefonnummern oder über Drittanwendungen wie z.B. Browser Plug-Ins, Onlinedienste, Widgets, usw. verschickt werden.

Alle Implementierungen von Drittherstellern basieren dabei auf einer sehr gut dokumentierten API, die es Programmierern auf einfache Weise ermöglicht, Twitter Funktionalitäten in alle Arten von Anwendungen zu integrieren.

Millionen von Anwendern und Unternehmen nutzen Twitter bereits täglich um zu kommunizieren oder Informationen auszutauschen. Immer mehr Webseitenbetreiber, -besucher und Webentwickler verspüren daher einen wachsenden Bedarf, ihre Tweets über eigene Webseiten oder Content Management Systeme zu aktualisieren, ohne dabei auf Software von Drittherstellern oder die Twitter-Webseite angewiesen zu sein.

Dies war für mich der Grund, eine umfassende Beispielimplementierung der Twitter-API in der weit verbreiteten Programmiersprache PHP aufzusetzen. Das Ergebnis ist eine standardisierte PHP-Klasse, die weiter unten heruntergeladen werden kann. Sie soll Ihnen die Arbeit mit der Twitter-API abnehmen und wird es Ihnen ermöglichen, Ihrer Webanwendung Twitter Funktionalitäten mit nur ein paar Zeilen zusätzlichem Code hinzuzufügen.

2. Systemanforderungen

Um diese PHP-Klasse verwenden zu können, ist ein Webserver mit PHP ab Version 5.2 und installierter cURL-Bibliothek erforderlich.

Bitte denken Sie daran, dass alle Ein- und Ausgaben in der Formatierung UTF-8 gehandhabt werden. Dies kann zu Problemen führen, wenn Sie diese Klasse zusammen mit Anwendungen verwenden, die andere Kodierungen verwenden. In diesen Fällen müssen Sie die entsprechenden Daten encoden oder decoden.

3. Lizenz

Dieses Programm ist freie Software: Sie können es unter den Bedingungen der GNU Lesser General Public License, wie von der Free Software Foundation veröffentlicht, weitergeben und/oder modifizieren, entweder gemäß Version 3 der Lizenz oder (nach Ihrer Option) jeder späteren Version.

Die Veröffentlichung dieses Programms erfolgt in der Hoffnung, dass es Ihnen von Nutzen sein wird, aber OHNE IRGENDEINE GEWÄHRLEISTUNG, sogar ohne die implizite Garantie der MARKTREIFE oder der VERWENDBARKEIT FÜR EINEN BESTIMMTEN ZWECK. Details finden Sie in der GNU Lesser General Public License.

4. Download

Alle Informationen und Quelldateien zu diesem Projekt sind über die zugehörige Sourceforge.net-Projektseite verfügbar.

Bitte laden Sie hier die aktuelle Version der Twitter Klasse herunter und entpacken Sie alle Inhalte in das entsprechende Verzeichnis Ihrer Webanwendung auf Ihrem Webserver.

5. Installation

Der erste Schritt um die Twitter-Klasse innerhalb Ihrer PHP-Anwendung zu verwenden ist das Einbinden der Quelldatei selbst (möglicherweise müssen Sie abhängig von Ihrer Installation den enthaltenen Dateipfad anpassen):

require_once('twitter.php');

Im nächsten Schritt müssen Sie mit Hilfe der Methode getInstance() ein neues Objekt der Klasse erstellen, bzw. eine bereits existierende Objektinstanz aufrufen (diese Implementierung basiert auf einem Singleton-Entwurfsmuster):

$Twitter = Twitter::getInstance();

Um mit Twitter arbeiten zu können muss zunächst ein Benutzer gesetzt werden. Übergeben Sie hierfür Ihre Twitter- Benutzerdaten mit Hilfe der Methode setUser():

$Twitter->setUser('ihrBenutzername','ihrPasswort');

6. Funktionalitäten

Jetzt sind alle Voraussetzungen erfüllt, um einen Tweet abzuschicken. Die entsprechende Methode lautet post():

$Twitter->post('Dies ist eine neue Nachricht!');

Diese Methode setzt einen als String formatierten Parameter (der auf eine vorgegebene Zeichenanzahl begrenzt ist) voraus, der dann im Programmablauf an Twitter geschickt wird. Zurückgegeben wird im Erfolgsfall der boolesche Wert true oder eine als String formatierte Fehlermeldung.

Um eine bereits veröffentlichte Nachricht zu löschen, müssen Sie dessen ID kennen (welche Sie über die Methoden weiter unten in Erfahrung bringen können). Die Funktion zum Löschen heisst deletePost():

$Twitter->deletePost(idDerNachricht);

Diese Methode setzt einen als Integer formatierten Parameter voraus, der die Tweet-ID beinhaltet. Zurückgegeben wird im Erfolgsfall der boolesche Wert true oder eine als String formatierte Fehlermeldung.

Um einem anderen Twitter-Benutzer zu folgen oder nicht weiter zu folgen müssen Sie nur eine der beiden folgenden Methoden aufrufen:

$Twitter->followUser('Benutzername');

$Twitter->unfollowUser('Benutzername');

Beide Methoden liefern im Erfolgsfall den booleschen Wert true zurück oder im Fehlerfall eine als String formatierte Fehlermeldung.

Möglicherweise möchten Sie detaillierte Daten zu einem bestimmten Twitter-Benutzer abfragen. Dies können Sie über die Methode getUser() problemlos bewerkstelligen:

$Twitter->getUser('BenutzernameOderId');

Diese Methode setzt einen als String formatierten Parameter voraus, der den Benutzernamen oder alternativ die Twitter-ID des gewünschten Benutzers beinhaltet. Zurückgegeben wird im Erfolgsfall ein Array mit allen verfügbaren Benutzerdaten oder eine als String formatierte Fehlermeldung.

Natürlich gibt es auch eine ähnliche Methode namens getPost(), welche detaillierte Informationen zu einem speziellen Tweet zurückliefert:

$Twitter->getPost(idDerNachricht);

Diese Methode setzt einen als Integer-Wert formatierten Parameter voraus, der die ID des gewünschten Tweets beinhaltet. Zurückgegeben wird im Erfolgsfall ein Array mit allen verfügbaren Nachrichtendaten oder eine als String formatierte Fehlermeldung.

Darüber hinaus beinhaltet die aktuelle Implementierung außerdem 3 Methoden um Benutzerlisten abzufragen:

$Twitter->getFriends();

$Twitter->getFollowers();

$Twitter->getFeaturedUsers();

getFriends() und getFollowers() beziehen sich auf den Benutzer, der mit Hilfe der Funktion setUser() gesetzt wurde, getFeaturedUsers() gibt eine von Twitter zusammengestellte Liste zurück.

All diese Funktionen stellen Arrays bereit, die aus einigen Benutzerdetails und des jeweils letzten Tweets der User bestehen. Im Fehlerfall wird eine als String formatierte Meldung zurückgegeben.

Ein weiterer wichtiger Eckpunkt beim Arbeiten mit Twitter sind die sog. Timelines. Mit Hilfe der folgenden 4 Methoden können auch diese abgefragt werden:

$Twitter->getMentions(optionaleIntegerElementAnzahl);

$Twitter->getUserTimeline(optionaleIntegerElementAnzahl);

$Twitter->getFriendsTimeline(optionaleIntegerElementAnzahl);

$Twitter->getPublicTimeline();

Auch in diesem Fall beziehen sich getMentions(), getUserTimeline() und getFriendsTimeline() auf den Benutzer, der mit Hilfe der Funktion setUser() gesetzt wurde, während  getPublicTimeline() von Twitter selbst zusammengestellt wird.

All diese Methoden liefern ein Array mit den letzten 20 Tweets aus der gewählten Gruppierung zurück und beinhalten ebenfalls einige Benutzerdetails. Im Fehlerfall wird auch hier eine als String formatierte Meldung zurückgegeben. Die ersten 3 Methoden sind über den optionalen Integer-Parameter auch in der Lage, mehr oder weniger als 20 Elemente auszugeben (beachten Sie bitte, dass ein maximales Limit von 200 Elementen pro Timeline gilt).

7. Diese Klasse erweitern

Falls Sie einen größeren Funktionsumfang für Ihre Anwendung benötigen sollten als diese Klasse momentan bereitstellt, sollten Sie sie besser über eine weitere PHP-Klasse erweitern als die Vorliegende Datei zu patchen. Dies hilft Ihnen, wenn in Zukunft neue Versionen dieser Klasse veröffentlicht werden, mit denen Sie Ihre Software aktuell halten können.

Nachdem alle bislang genannten Methoden mit public-Zugriffsrechten versehen sind, können Sie diese in Ihrer Erweiterungsklasse natürlich uneingeschränkt nutzen. Zusätzlich gibt es eine als protected deklarierte Methode, mit deren Hilfe Sie überprüfen können, ob bereits Benutzerzugangsdaten gesetzt wurden:

$Twitter->validateUserdata();

Diese Methode gibt einen booleschen Wert zurück, mit dem Sie Ihren anwendungsinternen Twitter-Arbeitsablauf verbessern können, indem Sie vorab prüfen, ob dem Objekt bereits ein Benutzer zugewiesen wurde.

Die als protected ausgewiesene Klassenvariable

$Twitter->maxPostLength;

enthält die maximal mögliche Zeichenanzahl für Twittermeldungen. Sie können diesen Wert z.B. für Validierungsprozesse in Ihren Eingabeformularen verwenden. So bleibt Ihre Anwendung in Zukunft updatefähig, auch wenn Twitter irgendwann die zur Verfügung stehende Zeichenanzahl verändern sollte.

8. Anmerkungen

Alle Methoden dieser Klasse, die für den Abruf von Informationen von Twitter erstellt wurden, verfügen über einen Mechanismus um die gelieferten Inhalte zu filtern. Die Inhalte werden überprüft, bereinigt und in ihrem korrekten Datentyp zurückgegeben. Dies soll Ihnen helfen die Anwendungssicherheit zu verbessern und spart Ressourcen wenn Sie die zurückgegebenen Datensätze weiter verarbeiten.

Die von Twitter bereitgestellten Daten enthalten unter anderem auch Zeitstempel. Die vorliegende Klasse konvertiert jeden originalen Zeitstempel in ein standardisiertes UNIX-Format um die weitere Arbeit mit den Datensätzen in PHP zu vereinfachen.

9. Twitter Einschränkungen

Twitter hat angemessene Beschränkungen eingeführt, die einem System- und Benutzermissbrauch vorbeugen sollen:

• 1000 Updates am Tag
• 1000 Direct Messages am Tag
• 100 API Requests pro Stunde
• Follow Limit

Twitter beschränkt die Anzahl von Benutzern die Ihnen folgen können nicht, es wurden aber Maßnahmen getroffen um zu verhindern, dass einzelne Benutzer massenhaft anderen folgen. Jeder Nutzer darf 2000 anderen folgen. Danach richtet sich das Follow Limit nach der Anzahl der eigenen Follower.

Die Follow Limits können von Twitter nicht abgeändert werden und jeder Benutzer muss sich danach richten. Dies betrifft auch hoch frequentierte Benutzer sowie API Accounts.

Bitte stellen Sie daher sicher, dass Sie diese Klasse vernünftig einsetzen und vermeiden Sie unnötige Requests.

Weitere Informationen zum Thema finden Sie in diesem Twitter Support Artikel.

10. Änderungen und Updates

Änderungen, die an dieser Software vorgenommen werden, werden in der Datei changelog.txt dokumentiert, die im Verzeichnis "/docs" der zur Verfügung gestellten zip-Datei zu finden ist.

Neue Versionen dieser Klasse werden immer auf der zugehörigen Projektseite auf Sourceforge.net zu finden sein. Diese Plattform hält Sie außerdem über aktuelle Entwicklungen und zukünftige Veröffentlichungen auf dem Laufenden.

Bitte kontaktieren Sie mich für Funktionserweiterungen oder falls Sie Fehler oder Bugs entdecken sollten.