PHP WSDL Generation

WSDL generation in WSO2 WSF/PHP is done using PHP reflection and an annotation parser. To generate a WSDL from a given WSO2 WSF/PHP service, a ?wsdl request should be sent to the server. For example, if you want to generate the WSDL for the service echoService.php, a request should be sent as,

http://localhost/services/echoService.php?wsdl

Upon receiving the request, the relevant WSDL is generated. If the PHP script that implements the service contains annotations provided by the programmer, they will be used for WSDL generation. If the annotations are missing or if there is a syntax error, the WSDL will be generated using reflection and XSD:Any as the type for the parameters.

1. Annotation Syntax

Parameter types and return types should be annotated for a PHP function using the following syntax.

1.1. Parameters

Syntax:

 @param PHP_parameter_type $parameterName
 ( xs:XSDType )

Example:

/**
 * @param string $name your first name
 * (maps to the xs:string XML schema type)
 */

You can add your own comments only after the $parameterName

1.2. Return Type

Syntax:

 @return PHP_return_type $returnValueName
 ( xs:XSDType )

Example:

/**
 * @return int $t your lucky number
 * (maps to the xs:int XML schema type )
 */

You can add your own comments only after the $returnValueName

1.3. Example 1

/** 
 * The purchaseOrder function
 * @param int $itemNo ID of the item to be purchased
 * (maps to the xs:int XML schema type )
 * @param string $date Date that the purchase order was done
 * (maps to the xs:gDate XML schema type)
 * @return int $price total price
 * (maps to the xs:nonNegativeInteger schema type )
 */
 function purchaseOrder ($itemNo, $date)
 {
    // some logic
    return $Price;
 }

1.4. Array types

Syntax:

 @param array of PHP_parameter_type $paramterName
 ( xs:XSDType )

You can add your own comments only after the $parameterName similar to the early cases

Example:

/**
 * @param array of string $items item list
 * (maps to the xs:string)
 */

In a case you want to specify minOccurs and maxOccurs explicitly you can use the following syntax..

Syntax:

 @param [minOccurs, maxOccurs] PHP_parameter_type $paramterName
 ( xs:XSDType )

Here minOccurs can only be digits, maxOccurs can be either digits or the string "unbounded"

1.5. Types, maps to PHP Classes

Syntax:

 @param object PHP_class_name $paramterName

Example:

/**
 * @param object Purchase $purchase the purchase object
 */
In order to work this, you need to put doc comments in the class and the class variables it self. Following two section describes how you can do that.

1.6. PHP Class to use as an Schema Type

Syntax:

 @namespace Schema_type_custom_namespace 

If the @namespace is not given, the schema type will have the default namespace http://www.wso2.org/php/xsd

Example:

/**
 * @namespace http://custom.host/custom/location
 */

1.7. PHP Class Variables

Syntax:

   @var PHP_parameter_type $parameterName
 ( xs:XSDType )

Here PHP_parameter_type may contain "object" or "array of" phrases similar to @param and @return

Example:

/**
 * @var String $name
 */

1.8. Example 2: Demonstrates how complex types and arrays are get generated

/**
 * The function to register students for a course
 * @param string $course the course to register
 * (maps to xs:string)
 * @param array of object Student $students students list
 * @return boolean $success
 * (maps to xs:boolean)
 */
function registerStudents($course, $students) {
    
}

/**
 * @namespace http://my.university/my/faculty
 */
class Student {
    /**
     * @var string $name student name
     */
    public $name;

    /**
     * @var int $age student age
     */
    public $age;

}

1.9. Example 3: Using Classmap API

If you use the same scenario in the Example 2 to use with the classmap API, you need to declare both the request and response types as PHP Classes like shown in the following code segment

NOTE: You are using classmap API, if you provide the "classmap" option in the WSService constructor.

/**
 * The function to register students for a course
 * @param object RegisterStudents $RegisterStudents
 * @return object RegisterStudentsResponse $RegisterStudentsResponse
 */
function registerStudents($RegisterStudents) {
    
}

/**
 * @namespace http://my.university/my/faculty
 */
class RegisterStudents {
    /**
     * @var string $course the course to register
     * (maps to xs:string)
     */
     public $course;

    /**
     * @var array of object Student $students students list
     */
     public $students;
}

/**
 * @namespace http://my.university/my/faculty
 */
class RegisterStudentsResponse {
  /**
   * @var boolean $success whether the operation successful or not
   * (maps to xs:boolean)
   */
    public $success;
}

/**
 * @namespace http://my.university/my/faculty
 */
class Student {
    /**
     * @var string $name student name
     */
    public $name;

    /**
     * @var int $age student age
     */
    public $age;

}

2. PHP to Schema Type Mapping

Since PHP is a weakly-typed language in nature, the following type mapping is required to map the PHP types to the XML Schema types.

Schema Type PHP Type
string string
boolean boolean
double float
float float
int int
integer int
byte int
decimal string
base64Binary string
hexBinary string
anyType soap var object
any soap var object
QName string
dateTime string
date string
time string
unsignedLong int
unsignedInt int
unsignedShort int
unsignedByte int
positiveInteger int
negativeInteger int
nonNegativeInteger int
nonPositiveInteger int
gYearMonth string
gMonthDay string
gYear string
gMonth string
gDay string
duration string
Name string
NCName string
NMTOKEN string
NOTATION string
NMTOKENS string
ENTITY string
ENTITIES string
IDREF string
IDREFS string
anyURI string
language string
ID string
normalizedString string
token string

3. WSDL Versions

Both WSDL 1.1 as well as WSDL 2.0 are supported.

To get WSDL 1.1 use '?wsdl'. To get WSDL 2.0 use '?wsdl2'

Example,

For WSDL 1.1 - http://localhost/services/echoService.php?wsdl

For WSDL 2.0 - http://localhost/services/echoService.php?wsdl2

4. Binding Style

The SOAP binding style should be set in a PHP service option array. If the SOAP style is not set, then the document style is assumed as the default.

Example,

$service = new WSService(array("operations"=>$operations, "bindingstyle"=>"rpc"))
Binding Style Parameter
Document literal doclit
RPC encoded rpc

Example: Generating Message elements and a schema for the document literal style .

/** The LuckyNo function
 * @param string $yr year of your birthday
 * (maps to the xs:gYear XML schema type )
 * @param string $name your first name
 * (maps to the xs:string XML schema type)
 * @return int $t your lucky number
 * (maps to the xs:int XML schema type )
 */
 function luckyNoFunction($yr,$name)
 {
    // some logic
    return $t;
 }

In the generated WSDL, the operation named "luckyfunction" has two messages.

    <operation name="luckyNoFunction">
        <input message="s0:luckyNoFunctionInput"/>
        <output message="s0:luckyNoFunctionOutput"/>
    </operation>

In message elements,

    <message name="luckyNoFunctionInput">
        <part name="parameters" element="luckyNoFunction"/>
    </message>
    <message name="luckyNoFunctionOutput">
        <part name="parameters" element="luckyNoFunctionResponse"/>
    </message>

Therefore, the generated schema that can be accessible on the server side is,

    <element name="luckyNoFunction">
        <complexType>
            <sequence>
                <element name="yr" type="xsd:gYear"/>
                <element name="name" type="xsd:string"/>
            </sequence>
        </complexType>
    </element>
    <element name="luckyNoFunctionResponse">
        <complexType>
            <sequence>
                <element name="t" type="xsd:int"/>
            </sequence>
        </complexType>
    </element>

Example, for RPC style:

The message elements are,

    <message name="luckyNoFunction">
        <part name="yr" type="xsd:gYear"/>
        <part name="name" type="xsd:string"/>
    </message>
        <message name="luckyNoFunctionResponse">
        <part name="t" type="xsd:int"/>
    </message>


5. Service Name

You can specify a name for the service for generating WSDL. If you have not provided the service name then will generate a service name based on the address location

Example,

$service = new WSService(array("operations"=>$operations, "serviceName"=>"sampleService"))