Dieses Tutorial gibt einen Einblick in die Erstellung von SOAP Webservices für TYPO3 Flow Anwendungen auf Basis des Flow Pakets TYPO3.Soap. Neben der Erstellung von speziellen Service-Klassen geht es außerdem um automatische Generierung von WSDL für Service Definitionen und das Testing der Services mit einem SOAP Client. SOAP Services wirken vielleicht auf den ersten Blick ein wenig veraltet, aber es ist eine bekannte und sehr verbreitete Technik. Hält man sich dabei an das WS-I Basis Profil (http://ws-i.org/Profiles/BasicProfile-1.2-2010-11-09.html) sind sie außerdem direkt vollständig kompatibel zu vielen Sprachen und Umgebungen (.NET, Java, usw.).

Voraussetzungen

Für dieses Tutorial benötigst Du eine lauffähige aktuelle Version von Flow (aktuell 1.1). Eine fertige Applikation ist allerdings nicht notwendig, denn wir werden zu Demonstrationszwecken ein einfaches Paket erstellen. In Deiner PHP Installation sollte allerdings die soap Erweiterung installiert und aktiviert sein.

Das TYPO3.Soap Paket installieren

Öffne ein Terminal (Kommandozeile) und gehe in das Root-Verzeichnis der Flow Applikation. Ein Paket kann mit dem package:import Kommando durch folgenden Aufruf installiert werden:

./flow3 package:import TYPO3.Soap

Nach dem Import solltest Du das neue Paket sehen, wenn du den Befehl package:list aufrufst.

Damit die WSDL Generierung funktioniert (dazu später mehr) müssen noch die Sub-Routen des Pakets TYPO3.Soap unter Configuration/Routes.yaml in Deine globalen Routen eingefügt werden:

...

##
# TYPO3.Soap subroutes
#

-
  name: 'TYPO3.Soap'
  uriPattern: '<SoapSubroutes>'
  subRoutes:
    SoapSubroutes:
      package: TYPO3.Soap

##
# FLOW3 subroutes
#

-
  name: 'FLOW3'
  uriPattern: '<FLOW3Subroutes>'
  defaults:
    '@format': 'html'
  subRoutes:
    FLOW3Subroutes:
      package: TYPO3.FLOW3

Ein Beispiel-Paket erstellen

Nutze den package:create Befehl, um ein Beispiel-Paket zu erstellen:

./flow3 package:create Test.Soap

Der komplette Code des Tutorials wird in diesem Paket abgelegt. Es sollte sich innerhalb Deines Anwendungs Root Pfades befinden, in: Packages/Application/Test.Soap.

Eine einfache Service-Klasse

Zur Bereitstellung eines SOAP Webservices kann ein beliebiges Singleton-Objekt aus Flow genutzt werden. Per Default werden alle Klassen-Namen, die nach dem Namens-Schema [VendorName]\[PackageName]\Service\Soap\[ServiceName]Service benannt sind, automatisiert in einen SOAP Webservice exportiert. Erstellen wir also ein Service-Objekt und exportieren eine einfache Methode für ein SOAP-basiertes "Hello World":

<?php
namespace Test\Soap\Service\Soap;

use TYPO3\FLOW3\Annotations as FLOW3;

/**
 * A simple SOAP test service
 *
 * @FLOW3\Scope("singleton")
 */
class TestService {

	/**
	 * Greet someone
	 *
	 * @param string $name The name to be greeted
	 * @return string A nice welcome message
	 */
	public function hello($name) {
		return 'Hello, ' . $name;
	}

}
?>

Wie man dabei sieht, ist es nicht notwendig eine spezielle Super-Klasse zu erweitern. Ein SOAP Service-Objekt ist lediglich ein einfaches Singleton innerhalb des Service\Soap Namespaces dessen Klassen-Name mit ...Service endet. Alle Webservice-Operationen werden durch Methoden in der Service-Klasse implementiert. Das SOAP-Paket untersucht automatisch die PHPDoc der Methoden und generiert daraus die entsprechenden Service Definitionen (WSDL). Es ist daher wichtig, dass Du darauf achtest, Kommentare mit korrekte Typ-Definitionen für Parameter und Rückgabewerte zu erstellen.

Das TestService Singleton definiert eine hello Methode die einen Parameter für den Namen entgegen nimmt und "Hello, [name]" als Rückgabewert liefert. Das ist natürlich ein kleines bisschen mehr, als das klassische "Hello World", aber es wäre auch ein wenig zu langweilig einfach nur einen statischen Wert zurück zu geben.

Du kannst Dir die WSDL des exportierten Webservices anschauen, indem Du die folgende URL im Browser öffnest: localhost. Die SOAP-Adresse für den Port des Services wird automatisch an folgende Position exportiert: localhost. Die meisten SOAP-Tools oder -Clients können aus der WSDL die korrekte Anfrage für den Aufruf der Service-Operationen erstellen.

Erhältst Du im Browser eine vergleichbare Ausgabe, wie die folgende verkürzte WSDL, sind wir so weit, dass wir den Service über einen Aufruf mit einem SOAP-Client testen können.

<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
	xmlns:tns="http://tempuri.org/service/soap/test.soap/test"
	xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	name="TestService"
	targetNamespace="http://tempuri.org/service/soap/test.soap/test">

	...

	<wsdl:message name="helloRequest">
		<wsdl:part name="name" type="xsd:string">
			<wsdl:documentation>The name to be greeted</wsdl:documentation>
		</wsdl:part>
	</wsdl:message>

	<wsdl:message name="helloResponse">
		<wsdl:part name="returnValue" type="xsd:string">
			<wsdl:documentation>A nice welcome message</wsdl:documentation>
		</wsdl:part>
	</wsdl:message>


	<wsdl:portType name="TestServiceSoapPort">
		<wsdl:documentation>Interface for TestService</wsdl:documentation>
		<wsdl:operation name="hello">
			<wsdl:documentation>Greet someone</wsdl:documentation>
			<wsdl:input message="tns:helloRequest" />
			<wsdl:output message="tns:helloResponse" />
		</wsdl:operation>

	</wsdl:portType>

	...

	<wsdl:service name="TestService">
		<wsdl:port binding="tns:TestServiceSoapBinding" name="TestServiceSoapPort">
			<soap:address location="http://soap-demo.dev/service/soap/test.soap/test" />
		</wsdl:port>
	</wsdl:service>
</wsdl:definitions>

Um den Service aufzurufen, kannst Du den SOAP-Client nutzen den PHP mitliefert oder ein Tool wie SoapUI, das einen etwas besseren Überblick über den SOAP Webservice liefert und zudem automatisch generierte Anfragen für Operationen mitliefert. In diesem Tutorial nutzen wir für die Webservice-Tests SoapUI. Erstelle dafür einfach ein neues Projekt in dem Programm (File -> New Project) und definiere dort die WSDL URI. Mit den Standard Einstellungen wird SoapUI für jede Operation Beispiel-Requests erstellen.

Lade den Beispiel-Request durch einen Doppelklick und gebe einen Namen ein:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:test="http://tempuri.org/service/soap/test.soap/test">
	<soapenv:Header/>
	<soapenv:Body>
		<test:hello>
			<name>Christopher</name>
		</test:hello>
	</soapenv:Body>
</soapenv:Envelope>

Jetzt kann der Request über das grüne Icon ausgeführt werden. Das Feld mit der Response sollte dann das Ergebnis anzeigen:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://tempuri.org/service/soap/test.soap/test">
   <SOAP-ENV:Body>
      <ns1:helloResponse>
         <returnValue>Hello, Christopher</returnValue>
      </ns1:helloResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Glückwunsch! Du hast einen funktionierenden SOAP-Webservice mit Flow.

Mit komplexere Daten arbeiten

Strings sind natürlich einfach zu nutzen, aber alle normalen Service-Klassen in Flow werden in irgendeiner Form mit Objekten arbeiten. Wir nutzen für die Nachrichten Argumente daher Data Transfer Objects (DTO):

Classes/Service/Soap/TestService.php

<?php
namespace Test\Soap\Service\Soap;

use TYPO3\FLOW3\Annotations as FLOW3;

/**
 * A simple SOAP test service
 *
 * @FLOW3\Scope("singleton")
 */
class TestService {

	...

	/**
	 * Greet a person
	 *
	 * @param \Test\Soap\Service\Soap\Dto\Person $person The personto be greeted
	 * @return string A welcome message
	 */
	public function helloPerson(\Test\Soap\Service\Soap\Dto\Person $person) {
		return 'Hello, ' . $person->getFirstname() . ' ' . $person->getLastname();
	}

}
?>

Hinweis: Erhälst Du bei dem Aufruf der helloPerson-Operation einen Fehler, solltest Du Deinen lokalen WSDL-Cache von PHP prüfen.

Bei einem Blick auf die generierte WSDL fällt auf, dass der WSDL-Generator für das Person DTO einen komplexen Typ, mit allen verfügbaren Eigenschaften, erstellt hat.

<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
	xmlns:tns="http://tempuri.org/service/soap/test.soap/test"
	xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	name="TestService"
	targetNamespace="http://tempuri.org/service/soap/test.soap/test">

	...

	<wsdl:types>
		<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://tempuri.org/service/soap/test.soap/test">
			<xsd:complexType name="Person">
				<xsd:sequence>
					<xsd:element name="firstname" type="xsd:string" minOccurs="0" maxOccurs="1" >
					</xsd:element>
					<xsd:element name="lastname" type="xsd:string" minOccurs="0" maxOccurs="1" >
					</xsd:element>
					<xsd:element name="salutation" type="xsd:string" minOccurs="0" maxOccurs="1" >
					</xsd:element>
				</xsd:sequence>
			</xsd:complexType>
		</xsd:schema>
	</wsdl:types>

	...
</wsdl:definitions>

Der Abschnitt wsdl:types enthält ein Schema (Du kannst Deine eigene targetNamespace URI definieren) mit komplexen Typ-Definitionen für die generierten komplexen Typen.

Das Domain-Model anbinden

In den meisten Fällen wirst Du bereits ein Domain-Model mit Entities haben und möchtest über einen Webservice bestimmte Operationen ansprechen. Um dein Domain-Model von dem Webservice getrennt zu halten (um spätere Anpassungen zu ermöglichen) ist es sinnvoll auf Deinen Models mit Data Transfer Objects und einem seperaten Domain Service für die Operationen zu arbeiten.

Damit dieses Tutorial nicht ausufert, schauen wir uns eine einfache Service-Klasse an, die direkt auf einem Entity arbeitet und eine Repository-Abhängigkeit hat. Wir starten mit dem Erstellen einer einfachen Entity Book mit einem Repository:

./flow3 kickstart:model Test.Soap Book title:string isbn:string description:string
./flow3 kickstart:repository Test.Soap Book

Wir fügen der Book-Entity ein paar Annotationen hinzu, um Validierungs-Eigenschaften für den Titel und die ISBN-Nummer zu definieren. Die Annotation @Identity markiert die Eigenschaft isbn als eindeutig und ermöglicht so einen guten Entity-Identifier für Service-Operationen (in den meisten Fällen möchte man die Interne UUID nicht ansprechen). Anschließend sollte eine solche Klasse zur Verfügung stehen (getters und setters ausgelassen):

<?php
namespace Test\Soap\Domain\Model;

/*                                                                        *
 * This script belongs to the FLOW3 package "Test.Soap".                  *
 *                                                                        *
 *                                                                        */

use TYPO3\FLOW3\Annotations as FLOW3;
use Doctrine\ORM\Mapping as ORM;

/**
 * A Book
 *
 * @FLOW3\Entity
 */
class Book {

	/**
	 * The title
	 * @var string
	 * @FLOW3\Validate(type="NotEmpty")
	 */
	protected $title;

	/**
	 * The isbn
	 * @var string
	 * @FLOW3\Identity
	 * @FLOW3\Validate(type="NotEmpty")
	 */
	protected $isbn;

	/**
	 * The description
	 * @var string
	 * @ORM\Column(type="text")
	 */
	protected $description;

	...

}
?>

Vergiss nicht ./flow3 doctrine:update aufzurufen, um das Datenbank-Schema zu aktualisieren (und konfiguriere Deine Datenbank korrekt in der Settings.yaml).

Ein einfacher Service, um die Bücher über einen SOAP Webservice zu verwalten, sollte das Anlegen und Anzeigen von Büchern unterstützen, wodurch auch die wichtigsten SOAP-Features gezeigt werden. Wir erstellen also zunächst ein Buch, denn unsere Buch-Tabelle sollte momentan noch leer sein:

<?php
namespace Test\Soap\Service\Soap;

use TYPO3\FLOW3\Annotations as FLOW3;

/**
 * A SOAP service for books
 *
 * @FLOW3\Scope("singleton")
 */
class BookService {

	/**
	 * @var \Test\Soap\Domain\Repository\BookRepository
	 * @FLOW3\Inject
	 */
	protected $bookRepository;

	/**
	 * @var \TYPO3\FLOW3\Persistence\PersistenceManagerInterface
	 * @FLOW3\Inject
	 */
	protected $persistenceManager;

	/**
	 * Create a book
	 *
	 * @param \Test\Soap\Domain\Model\Book $book The new book
	 * @return boolean TRUE if the book was created successfully
	 */
	public function create(\Test\Soap\Domain\Model\Book $book) {
		$this->bookRepository->add($book);
		$this->persistenceManager->persistAll();
		return TRUE;
	}

	...

?>

Wie schon zuvor nutzen wir einfach den PHP-Typ der create-Methode und das SOAP-Paket wird sich um das Mapping auf eine frische Book-Instanz kümmern. Im Vergleich zu einem Controller, müssen wir uns selber um den Aufruf von persistAll auf dem PersistenceManager kümmern. Das Gute daran ist, dass wir jegliche Exception hier selber anfangen und in ein übliches Webservice-Ergebnis konvertieren können.

Wenn Du nun den neuen Service in SoapUI oder einen anderen Client einfügst und die create-Operation testest, solltest Du ein Buch in der Datenbank vorfinden. Einfach, oder?

Die neue Website der Campus Suite, weiterhin basierend auf dem TYPO3 CMS, repräsentiert nun auch verstärkt die Wohlfühlatmosphäre, Frische & Qualität des Coffee Stores im Web. Bekannte Stilelemente wie z.B. der Campus Suite Schmetterling oder auch die Holz Struktur im Hintergrund sowie hochwertige Bilder der Produkte und Leckereien erinnern an die natürliche und geschmackvolle Inneneinrichtung der Stores und berühren den Besucher emotional.

Besondere animierte Elemente die auf JavaScript basieren sind zum einen der Bild-Slider auf der Eingangsseite, der mit den großen plakativen Buchstaben farbig passend zur CI die Produkte wie Snacks, Kaffee und auch die neue Collection der Campus Suite anteasert. Der Slider auf den Unterseiten dient zur Präsentation und Vorstellung der einzelnen Produkte mit jeweils passender Beschreibung, die immer zusammen mit dem Bild erscheint.

Mit dem von uns entwickelten Storefinder, auf Basis von Google Maps, ist es ab sofort auch möglich, von verschiedenen Bereichen aus nach einer Campus Suite Filiale in der Nähe zu suchen. Man muss lediglich seine PLZ/Ort eingeben und es wird einem die nächstliegende Filiale angezeigt oder die Anzahl an Stores die verfügbar sind.

Wir freuen uns darüber, seit bereits 2007 als Webagentur für die Campus Suite zu arbeiten und laden dazu ein, den neuen Auftritt unter www.campussuite.de zu besuchen oder über unsere TYPO3-Referenzen mehr über die Campus Suite zu erfahren.

Seit der Veröffentlichung des TYPO3 CMS und der Gründung der TYPO3 Association ist viel geschehen - die Community hat neue Produkte hervorgebracht, darunter nicht nur das PHP Framework FLOW3 sondern auch die Templating Engine Fluid, den FLOW3 Backport Extbase oder das Deployment Tool Surf (welches von uns gestartet wurde). Dieses Jahr wird das heiß erwartete neue Content Management System „TYPO3 Phoenix“ (Code Name) veröffentlicht werden und damit erhält die Community ein weiteres Produkt.

Im Angesicht dieser Entwicklung liegt es nahe, dass es Zeit wurde sich Gedanken über die TYPO3 Marke zu machen und zu überlegen wie es möglich ist, zwei unabhängige Content Management Systeme in dieser Marken-Welt unterzubringen. Als Co-Leader des TYPO3 Marketing Teams habe ich die Diskussion mit verfolgen können und vertrete auch persönlich die Ansicht, dass der gewählte Weg die richtige Entscheidung war.

Die neuen TYPO3 Branding Guidelines

Auch wenn es sich groß anhört, insbesondere für uns als TYPO3 Agentur wird der Umstieg im täglichen Umgang gar nicht sein: Der Kern der Umbenennungen besteht darin, dass TYPO3 nicht länger ein einziges System bezeichnet, sondern TYPO3 ab sofort der „Umbrella Brand“, also die Dachmarke ist. Hintergrund ist die Tatsache, dass sich TYPO3 als Marke zu etwas entwickelt hat auf das die Community stolz sein kann: es ist eine starke Marke, die bereits weit verbreitet ist und noch weiter verbreitet werden soll. Das Resultat besteht darin, dass die offiziellen Produkte alle den Namen TYPO3 enthalten werden:

• TYPO3 CMS (ehemals bekannt als TYPO3)
• TYPO3 Fluid
• TYPO3 Flow (ehemals bekannt als FLOW3)
• TYPO3 Extbase
• TYPO3 Surf

Und auch das neue CMS wird dieses Namensschema einhalten. Bislang war es bereits bekannt unter TYPO3 Phoenix. Auf der Konferenz T3CON, die Ende dieser Woche starten wird, soll der neue Name des neuen Systems bekannt gegeben werden.

TYPO3 Flow

Die wohl größte Änderung trifft damit das PHP Framework FLOW3, welches ab sofort TYPO3 Flow heißen wird. Die anstehende neue Version wird damit nicht mehr nur der Release TYPO3 Flow 1.2 sein, sondern durch den Wechsel des Namens und die Integration von Composer wird es eine neue Versions-Nummer geben: TYPO3 Flow 2.0.

Für TYPO3 Flow Entwickler ist der Aufwand allerdings nicht so groß, wir er sich auf den ersten Blick anhört, denn das Framework enthält einen Migrations-Mechanismus, mit welchem sich die Namespaces des Frameworks auch im eigenen Code einfach anpassen lassen.

Fazit

Die Entscheidung diesen Weg zu gehen ist die logische Konsequenz aus der Entwicklung der Community. Für uns als Agentur wird sich nicht viel ändern, ein paar Marketing Materialien müssen angepasst werden, aber insgesamt halten auch wir diesen Weg für den Richtigen.