Contract-First Web Services in practice - part 3 of 5 (PHP)

Welcome to the third article in this series of 5 where I'm putting contract-first service oriented architecture through its paces. For a recap, in article one I defined the rules of engagement, and article two I outlined the contract for the service to be developed. With this behind us, the next challenge is to begin the representation of this service in the 3 programming languages and PHP is first of the blocks.

There are several libraries for use in tackling SOAP in PHP (Pear, Nu Soap, PHP Soap). Not being my forte, I selected the inbuilt soap library PHP Soap that ships with PHP 5. I needed a simple approach that supported WSDL 1.1 and "document literal". I didn't think this would be too much to ask until I discovered that there was an affinity for "RPC encoded" style of web services which fits in well with positional parameters which are well supported in php.

The first step in implementing the service is to create the endpoint handler. This is the php file at the url which will respond to this service and is set in the soap:address element of the wsdl. In the example wsdl the endpoint is "http://localhost:8080/index.php", so the endpoint handler is the index.php. The content for this file is shown below:

view plaincopy to clipboardprint?

1. <?php
3. //cache the wsdl
4. ini_set("soap.wsdl_cache_enabled", "0");
6. //load the code for the service handler
7. require_once('./SampleServiceClass.php');
9. //create a new soap server. Refer to the wsdl file
10. $server = new SoapServer('SampleService.wsdl');
12. //set the class which will be handling the request
13. $server->setClass('SampleServiceClass');
15. //begin the server
16. $server->handle();
18. ?>

1. The first statement is a directive to cache the wsdl for better performance (suitable for production environments but reasonable in this case as it's contract first so we're taking the WSDL as given).
2. The next statement imports a file SampleServiceClass.php which we have not yet created. More on this soon.
3. The third statement creates a soap server instance. The constructor takes as one of its arguments, the wsdl file defined in article 2.
4. The fourth statement sets the class SampleServiceClass (yet to be defined in the file SampleServiceClass.php)
5. The final statement starts the server instance.

With those five statements, we're setting up the endpoint by tying in the wsdl to the service handler which we will create in the next step.

view plaincopy to clipboardprint?

1. <?php
3. //Exception Types
4. define('SERVICE_EXCEPTION', 'ServiceException'); //thow this error when the user does not exist
7. //Soap Exception Fault Codes
8. define('ERROR_CODE_CLIENT', "Client");
9. define('ERROR_CODE_SERVER', "Server");
11. /**
12. *
13. * This class handles the Sample Service Soap Requests
14. *
15. */
16. class SampleServiceClass
17. {
18. /**
19. * Create an exception
20. *
21. * <ns2:SampleException xmlns:ns2="http://kimenye.com/soap/">
22. * <message>Some weird error occurred</message>
23. * </ns2:SampleException>
24. *
25. * @param object $exception
26. * @return
27. */
28. function createException($exception,$message)
29. {
30. $typedException = new StdClass();
31. $typedException->message = $message;
32. $detail = null;
33. $error_code = ERROR_CODE_CLIENT;
35. if ($exception == SERVICE_EXCEPTION)
36. {
37. $detail->ServiceException = $typedException;
38. }
40. return new SoapFault($error_code,$exception,null,$detail,$exception);
41. }
43. /**
44. * This is the sample operation.
45. *
46. * @param object $SampleOperationRequest
47. *
48. * @return
49. */
50. function SampleOperation($SampleOperationRequest)
51. {
52. $num_of_args = func_num_args();
54. //In this example the custom fields are compulsory
55. if(func_num_args()<1)
56. {
57. return $this->createException(SERVICE_EXCEPTION, "SampleOperationRequest -Incorrect parameters passed in.");
58. }
60. $Demo = $SampleOperationRequest->DemoField;
61. $CustomFields = $SampleOperationRequest->SampleFields;
63. $num_custom_fields = count($CustomFields->SampleField);
65. /**
66. * This is to demonstate how to access the custom fields.
67. *
68. * If only one custom field is required, access is
69. *
70. * $fieldOne = $CustomFields->CustomField->FieldValue
71. */
72. if($num_custom_fields == 2)
73. {
74. if($CustomFields->SampleField[0]->FieldName == 'a field')
75. {
76. $fieldOne = $CustomFields->CustomField[0]->FieldValue;
77. $fieldTwo = $CustomFields->CustomField[1]->FieldValue;
78. }
80. if($CustomFields->SampleField[0]->FieldName == 'another field')
81. {
82. $fieldTwo = $CustomFields->CustomField[0]->FieldValue;
83. $fieldOne = $CustomFields->CustomField[1]->FieldValue;
84. }
85. }
88. $ro1 = new StdClass();
89. $ro1->DemoField = "Scott";
91. $custom_logo = new StdClass();
92. $custom_logo->FieldName = 'logo';
93. $custom_logo->FieldValue = 'A logo';
95. $nickname = new StdClass();
96. $nickname->FieldName = 'nickname';
97. $nickname->FieldValue = 'Scotty';
99. $custom_logo2 = new StdClass();
100. $custom_logo2->FieldName = 'logo';
101. $custom_logo2->FieldValue = 'A logo';
103. $nickname2 = new StdClass();
104. $nickname2->FieldName = 'nickname';
105. $nickname2->FieldValue = 'Scotty';
107. $custom_fields = array($custom_logo, $nickname);
108. $custom_fields2 = array($custom_logo2, $nickname2);
110. $ro2->SampleFields = $custom_fields;
112. $ro2 = new StdClass();
113. $ro2->DemoField = "Hello";
115. $ro2->SampleFields = $custom_fields2;
117. $objs = array($ro1, $ro2);
119. return $objs;
121. }
122. }
123. ?>

<?php //Exception Types define('SERVICE_EXCEPTION', 'ServiceException'); //thow this error when the user does not exist //Soap Exception Fault Codes define('ERROR_CODE_CLIENT', "Client"); define('ERROR_CODE_SERVER', "Server"); /** * * This class handles the Sample Service Soap Requests * */ class SampleServiceClass { /** * Create an exception * * <ns2:sampleexception ns2="http://kimenye.com/soap/"><br /> * <message>Some weird error occurred</message><br /> * </ns2:SampleException><br /> * <br /> * @param object $exception<br /> * @return <br /> */<br /> function createException($exception,$message)<br /> {<br /> $typedException = new StdClass();<br /> $typedException->message = $message;<br /> $detail = null;<br /> $error_code = ERROR_CODE_CLIENT;<br /> <br /> if ($exception == SERVICE_EXCEPTION)<br /> {<br /> $detail->ServiceException = $typedException;<br /> }<br /> <br /> return new SoapFault($error_code,$exception,null,$detail,$exception);<br /> }<br /> <br /> /**<br /> * This is the sample operation.<br /> * <br /> * @param object $SampleOperationRequest<br /> * <br /> * @return <br /> */<br /> function SampleOperation($SampleOperationRequest)<br /> {<br /> $num_of_args = func_num_args();<br /> <br /> //In this example the custom fields are compulsory<br /> if(func_num_args()<1)>createException(SERVICE_EXCEPTION, "SampleOperationRequest -Incorrect parameters passed in.");<br /> }<br /> <br /> $Demo = $SampleOperationRequest->DemoField;<br /> $CustomFields = $SampleOperationRequest->SampleFields;<br /> <br /> $num_custom_fields = count($CustomFields->SampleField);<br /> <br /> /**<br /> * This is to demonstate how to access the custom fields.<br /> * <br /> * If only one custom field is required, access is <br /> * <br /> * $fieldOne = $CustomFields->CustomField->FieldValue<br /> */<br /> if($num_custom_fields == 2)<br /> {<br /> if($CustomFields->SampleField[0]->FieldName == 'a field')<br /> {<br /> $fieldOne = $CustomFields->CustomField[0]->FieldValue;<br /> $fieldTwo = $CustomFields->CustomField[1]->FieldValue;<br /> }<br /> <br /> if($CustomFields->SampleField[0]->FieldName == 'another field')<br /> {<br /> $fieldTwo = $CustomFields->CustomField[0]->FieldValue;<br /> $fieldOne = $CustomFields->CustomField[1]->FieldValue;<br /> }<br /> }<br /><br /> <br /> $ro1 = new StdClass();<br /> $ro1->DemoField = "Scott";<br /> <br /> $custom_logo = new StdClass();<br /> $custom_logo->FieldName = 'logo';<br /> $custom_logo->FieldValue = 'A logo';<br /> <br /> $nickname = new StdClass();<br /> $nickname->FieldName = 'nickname';<br /> $nickname->FieldValue = 'Scotty';<br /> <br /> $custom_logo2 = new StdClass();<br /> $custom_logo2->FieldName = 'logo';<br /> $custom_logo2->FieldValue = 'A logo';<br /> <br /> $nickname2 = new StdClass();<br /> $nickname2->FieldName = 'nickname';<br /> $nickname2->FieldValue = 'Scotty';<br /> <br /> $custom_fields = array($custom_logo, $nickname);<br /> $custom_fields2 = array($custom_logo2, $nickname2);<br /> <br /> $ro2->SampleFields = $custom_fields;<br /> <br /> $ro2 = new StdClass();<br /> $ro2->DemoField = "Hello";<br /> <br /> $ro2->SampleFields = $custom_fields2;<br /> <br /> $objs = array($ro1, $ro2);<br /> <br /> return $objs;<br /> <br /> }<br />}<br />?><br />

This class is a lot more substantial than the previous as it handles the Soap requests.

1. First, is the definition of a couple of exception constants.
2. Second, the method "createException" throws the contract specified exception.
3. Finally, the SampleOperation method reads the input and returns the array output.

That's it!