Recipe 15.5. Throwing SOAP Faults

Recipe 15.5. Throwing SOAP Faults 15.5.1. Problem You want to generate a SOAP fault, which is the mechanism SOAP uses to indicate errors. 15.5.2. Solution Call the SOAPServer::fault( ) method: <?php class pc_SOAP_return_time { public function return_time() { $date = date('Ymd\THis'); if ($date === false) { $GLOBALS['server']->fault(1, 'Bad dates.'); } return $date; } } $server = new SOAPServer(null,array('uri'=>'urn:pc_SOAP_return_time')); $server->setClass('pc_SOAP_return_time'); ?> Or throw a SOAPFault: <?php class pc_SOAP_return_time { public function return_time() { $date = date('Ymd\THis'); if ($date === false) { throw new SOAPFault(1, 'Bad dates.'); } return $date; } } $server = new SOAPServer(null,array('uri'=>'urn:pc_SOAP_return_time')); $server->setClass('pc_SOAP_return_time'); ?> You can also return a SOAPFault instead of throwing it. 15.5.3. Discussion The SOAP specification has a standard way of indicating errors: SOAP faults. SOAP faults are very similar to the OO concept of exceptions. In fact, ext/soap allows you to treat SOAP faults, from both a SOAP server and SOAP client perspective, in a very similar manner to how PHP handles exceptions. While you can indicate SOAP faults in a number of ways, the easiest is to tHRow an instance of the SOAPFault class, passing an error code and an error string to the constructor, as shown in Example 15-8. Throwing a SOAP fault <?php class pc_SOAP_return_time { public function return_time() { $date = date('Ymd\THis'); if ($date === false) { throw new SOAPFault(1, 'Bad dates.'); } return $date; } } $server = new SOAPServer(null, array('uri'=>'urn:pc_SOAP_return_time')); $server->setClass('pc_SOAP_return_time'); $server->handle(); } ?> In Example 15-8, you throw a SOAPFault when date( ) returns false. The error code is 1, and in a moment of Indiana Jonesinspired whimsy, the error message is Bad dates.. These two values are mapped to the SOAP 1.1 specification's faultcode and faultstring elements, respectively. At the time of this writing, there is not support for SOAP 1.2style SOAP faults. Normally, the error code is used to allow a program to process the error, while the error message is used to let a human understand what occurred'usually through a logfile or by printing it out. Unlike HTTP and status codes, there is no convention for SOAP error codes. For example, the 500 block is not reserved for server errors. You have the freedom to make up whatever set of codes you want. However, the SOAP extension will automatically set the HTTP status code to 500 when you issue a SOAP fault. This is required by the SOAP specification. You cannot use an HTTP status code other than 500. Besides throwing a SOAPFault, you can also return one from your method, or invoke the SOAPServer::fault( ) method. These all generate the same SOAP fault data, so it's a matter of personal preference or coding situation. Instead of using SOAPFault directly, you can also subclass it and use that class instead. This allows you to implement an integrated logging system, for example: <?php class pc_My_SOAPFault extends SOAPFault { public function __construct($code, $string) { parent::__construct($code, $string); error_log($this); } } ?> SOAP faults are automatically generated when you do something that generates an error, such as calling an undefined function. 15.5.4. See Also Recipe 14.10 for catching SOAP faults in a SOAP client.