Yii Framework Official Guide Series 47 - Special Topic: Web Service

Web service is a software system designed to support mutual access between computers across a network. In a web application, it usually uses a set of APIs that can be accessed from the Internet and perform the requested services on the remote system host. Services required by the system host. For example, a Flex-based client might invoke functions to implement a web application running PHP on the server side. Web services rely on SOAP as the basic layer of the communication protocol stack.

Yii provides CWebService and CWebServiceAction to simplify the implementation of Web services in Web applications. These APIs are implemented in the form of classes, called service providers. Yii will generate a WSDL for each class, describing what API is available and how the client can invoke it. When a client invokes an API, Yii will instantiate the corresponding service provider and call the requested API to complete the request.

Note: CWebService relies on PHP SOAP extension. Please make sure you allow this extension before trying the examples in this section.

1. Defining Service Provider (Definition Service Provider)

As we mentioned above, service provider is a class definition that can be remotely invoked. Yii relies on doc comment and class reflection to identify which methods can be called remotely and their parameters and return values.

Let's start with a simple stock quote service. This service allows clients to request quotes for specified stocks. We determine the service provider as follows. Please note that we define the provider class StockController that extends CController. This is not required. We'll explain why this is done in a moment.

class StockController extends CController
{
    /**
     * @param string the symbol of the stock
     * @return float the stock price
     * @soap
     */
    public function getPrice($symbol)
    {
        $prices=array('IBM'=>100, 'GOOGLE'=>350);
        return isset($prices[$symbol])?$prices[$symbol]:0;
        //...return stock price for $symbol
    }
}

In the above, we declare it through the @soap tag in the documentation commentgetPriceThe method is a Web service API. Rely on documentation comments to specify input parameter data types and return values. Other APIs can be declared in a similar way.

2. Declaring Web Service Action (defining Web Service action)

The service provider has been defined, and we enable it to be accessed through the client. In particular, we're going to create a controller action that exposes this service. This can be done easily by defining a CWebServiceAction action in the controller class. For our example, we put it in StockController.

class StockController extends CController
{
    public function actions()
    {
        return array(
            'quote'=>array(
                'class'=>'CWebServiceAction',
            ),
        );
    }

    /**
     * @param string the symbol of the stock
     * @return float the stock price
     * @soap
     */
    public function getPrice($symbol)
    {
        //...return stock price for $symbol
    }
}

This is the Web service we need to build! If we try to access the action URL http://www.php.cn/, we will see a lot of XML content, which is actually the WSDL description of the Web service we defined.

Tip: By default, CWebServiceAction assumes that the current controller is a service provider. This is because we define the getPrice method in StockController.

3. Consuming Web Service

To complete this example, let us create a client to consume the Web service we just created. The client in the example is written in php, but it can be written in other languages, such as Java, C#, Flex, etc.

$client=new SoapClient('http://hostname/path/to/index.php?r=stock/quote');
echo $client->getPrice('GOOGLE');

Run the above script in the web page or console mode, we will see GOOGLE The price is 350.

4. Data Types

When the defined methods and properties are accessed remotely, we need to specify the data types of the input and output parameters. The following primitive data types can be used:

• str/string: corresponding to xsd:string;

• int/integer : Corresponds to xsd:int;

• float/double: Corresponds to xsd:float;

• bool/boolean: corresponds to xsd:boolean;

• date: corresponds to xsd:date;

• time: corresponds to xsd:time;

• datetime: corresponds to xsd:dateTime;

• array: corresponds to xsd:string;

• object: corresponds to xsd:struct;

• mixed: Corresponds to xsd:anyType.

If the type does not belong to any of the above primitive types, it is regarded as an attribute composed of composite types. The composite type is regarded as a class, and its properties are regarded as public member variables of the class, and are marked with @soap in documentation comments.

We can also use array types by appending [] after a primitive or composite type. This will define an array of the specified type.

The following is an example of defining the getPosts web API and returning an array of Post objects.

class PostController extends CController
{
    /**
     * @return Post[] a list of posts
     * @soap
     */
    public function getPosts()
    {
        return Post::model()->findAll();
    }
}

class Post extends CActiveRecord
{
    /**
     * @var integer post ID
     * @soap
     */
    public $id;
    /**
     * @var string post title
     * @soap
     */
    public $title;
}

5. Class Mapping

In order to get composite parameters from the client , the application needs to define the mapping from WSDL types to corresponding PHP classes. This is done by configuring the property classMap of CWebServiceAction.

class PostController extends CController
{
    public function actions()
    {
        return array(
            'service'=>array(
                'class'=>'CWebServiceAction',
                'classMap'=>array(
                    'Post'=>'Post',  // or simply 'Post'
                ),
            ),
        );
    }
    ......
}

6. Intercepting Remote Method Invocation (intercepting remote method invocation)

By implementing the IWebServiceProvider interface, the service provider can intercept remote method invocation. In IWebServiceProvider::beforeWebMethod, the service provider can obtain the current CWebService instance and the name of the method requested through CWebService::methodName. It can return false if the remote method should not be invoked for some reason (eg: unauthorized access).

The above is the content of Yii Framework Official Guide Series 47 - Special Topic: Web Service. For more related content, please pay attention to the PHP Chinese website (www.php.cn)!