The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

1. Introduction
1.1.Installation
1.2.Glossary
2.Examples
2.1.The structure of a Service Component
2.2.Obtaining a reference to another Service Component
2.3.Calling another Service Component
2.4.Locating and calling services from a script which is not an SCA Component
2.5.Exposing a Service Component as a Web service
2.6.Deploying an SCA component
2.7.Obtaining the WSDL for an SCA component offering a Service as a Web service
2.8.Understanding how the WSDL is generated
2.9.Working with data structures
2.10.Error handling
3.PHP Annotations
3.1.@binding.*
3.2.@types
3.3.@param
3.4.@reference
3.5.@return
3.6.@service
4.Unsupported

1. Introduction

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

SCA for PHP makes it possible for a PHP programmer to write reusable components, which can be called in a variety of ways, with an identical interface and with a minimum of fuss. At present components can call each other either locally or in several ways over the Web, and it is expected that new ways will be added over time. It provides the programmer with a way of doing this which will look as natural as possible in PHP. At the time of writing, components can call each other:

locally, within the same instance of the PHP engine, on the same call stack
using soap-based web services
using XML-RPC
using JSON-RPC

and the business logic within the component does not need to know or care which method is being used. A component can make itself available as a service using any of the methods above, all at the same time. Almost any set of methods can be offered or consumed as a service.

SCA also provides a number of specialised bindings to allow components to consume services on the Web that have a more closely defined set of methods or data encoding. These are:

an rss feed
some REST-style interfaces
most specific of all, an interface that uses SOAP web services to work with eBaY.

Other bindings are under development.

SCA components use phpDocumentor-style (see http://www.phpdoc.org/) annotations to declare dependencies on other SCA components or Web services. The SCA for PHP runtime resolves these dependencies at runtime on behalf of the components, and thus allows the PHP programmer to focus on the business logic rather than on locating and obtaining references to dependencies.

Components also use annotations to define the interface which they expose as a service. These annotations are a natural extension to those provided by phpDocumentor. The SCA for PHP runtime will automatically generate service descriptions from these annotations, so that an SCA component is easily exposed as a web service. An example of a service description that SCA will generate is the WSDL file that defines a SOAP web service. SCA will also generate Service Method Description files for components that offer a JSON-RPC interface, and system.describe data for components that offer an XML-RPC interface. Consequently, deploying a Web Service can be as simple as placing a PHP component under the document root of a web server and allowing SCA to generate service descriptions on demand.

Components also use annotations to specify data structures (expressed using XML schema complex types) which are then handled using Service Data Objects (SDOs).

PHP scripts that are not SCA components can nevertheless make use of or be used by SCA components. A PHP script which is not an SCA component and which contains no annotations can still use the services of an SCA component. A PHP script which is a component can also make calls to services that are not provided by an SCA component, but using the same system of annotations to obtain a reference.

1.1. Installation

See http://www.php.net/sdo#sdo.installation for installing the SCA_SDO package from PECL. The SCA code must be on the include path of your PHP installation, for example if it is installed as /usr/local/lib/php/SCA, the include_path directive must include /usr/local/lib/php.

Prerequisites

SCA requires the SDO extension v1.0.4 or later and PHP 5.2.0 or later. If you want to use the SOAP web service support then PHP must be built with the soap extension enabled. If you want to use the REST support then PHP must be built with libcurl extension enabled.

If you just want to use local components, and do not wish to use the Web service bindings, then this version of SCA for PHP will also run with PHP 5.1.6.

Limitations (aka Known problems)

There is a known problem using the SCA to pass an SDO to a web service with WSDL that uses the rpc-encoded style. This can cause PHP to crash. For example, a script like the following is known to fail:

$remote_service = SCA::getService("<some rpc-encoded wsdl that defines a type called inType>");
$do = $remote_service->createDataObject('http://example.org/types', 'inType');
$do->a = 2.11;
$do->b = 33.4;
$ret = $remote_service->call($do);

1.2. Glossary

The following terms are used throughout this document:

Component: the name "component" is used in this document to refer to an implementation artifact (a PHP script containing a PHP class) which provides a Service to other components. This is consistent with the SCA use of the term "component" to describe a configured instance of an implementation, since the script contains both the implementation of the business logic, expressed in PHP code, and the configuration information, expressed through annotations.
Service: A service is a set of one or more operations made available for calling by other components. These might be operations which can be called locally (i.e. PHP script directly to PHP script), or operations callable remotely via a Web service.
Service Component: Used as a synonym for Component.
Web service: Unless specifically stated otherwise, the term Web service is used to refer to a service available on the web which might be offered by a number of different means, not just SOAP style web services.

2. Examples

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

The examples in the subsequent sections illustrate the following aspects of PHP for SCA:

How PHP annotations are used to define PHP classes as SCA components, and how annotations are used to define the services.
How an SCA component can be exposed as a Web service
How an SCA component can consume a Web service, whether provided by another SCA component or by some other service which knows nothing of SCA
How an SCA component can call another SCA component locally (within the same process and on the same call stack)
How a client script which is not an SCA component can use the getService call to obtain a reference to an SCA component.
How data structures such as Addresses, or Puchase Orders, are represented as Service Data Objects, and handled.
How SCA components are deployed, and in particular how and when WSDL is generated for a service.
How parameters are always passed by value (and not by reference) between components, even when the calls are local. This ensures that the semantics of a call do not change depending on the location of a component.
How positional parameters to a service are supported, even when the underlying WSDL is document literal wrapped, and naturally supports only named parameters.
How business and runtime exceptions are handled.
Lifecycle issues such as when two successive calls to a component can be relied upon to be calling the same instance of that component and when they cannot.

First we show a single SCA component, "ConvertedStockQuote" which illustrates many of the features of SCA for PHP. It has one method, "getQuote()", which given a stock "ticker" obtains a price quote for that stock, converted to a given currency. We shall be using this example as a basis for explaining the SCA for PHP throughout the rest of this document.

<?php

include "SCA/SCA.php";

/**
 * Calculate a stock price for a given ticker symbol in a given currency.
 *
 * @service
 */
class ConvertedStockQuote {

    /**
     * The currency exchange rate service to use.
     *
     * @reference
     * @binding.php ../ExchangeRate/ExchangeRate.php
     */
    public $exchange_rate;

    /**
     * The stock quote service to use.
     *
     * @reference
     * @binding.soap ../StockQuote/StockQuote.wsdl
     */
    public $stock_quote;

    /**
     * Get a stock quote for a given ticker symbol in a given currency.
     *
     * @param string $ticker The ticker symbol.
     * @param string $currency What currency to convert the value to.
     * @return float The stock value is the target currency.
     */
    function getQuote($ticker, $currency)
    {
        $quote  = $this->stock_quote->getQuote($ticker);
        $rate   = $this->exchange_rate->getRate($currency);
        return  $rate * $quote;
    }
}
?>

In this example, we see that an SCA component is implemented by a script containing a PHP class and includesSCA.php. The class contains a mixture of business logic and references to other components or services. In the illustrated getQuote() method there is only business logic, but it relies on the instance variables $stock_quote and $exchange_rate having been initialized. These are references to two other components and will be initialized by the SCA runtime whenever this component executes. The annotations for these two services show one to be a local component, which will be called within the same PHP runtime, and one to be a remote component which will be called via a SOAP request. This component also exposes the getQuote() method both locally and as a web service, so it in turn can be called either locally or remotely.

2.1. The structure of a Service Component

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

A service component is implemented by a class. To identify it as a service component, it contains an @service annotation.
The SCA runtime will use the file name of the script to determine the component name, by convention. The class and script file must therefore share the same name.

PHP SCA components always expose a service, and there is no way for a component to be invoked other than to be called as a result of a Web service request, or called directly from another component or from a script. For this reason a valid PHP SCA component will always contain an @service annotation and at least one public method.

Each SCA Component requires that the SCA.php script is included. As well as containing the definition of the SCA class, this script contains executable PHP code that will run whenever the script is called, and which will be responsible for making the component behave as needed. It is very important that if your file contains other includes, they come before the include for SCA.php. If there are includes after the include for SCA.php, they will not have been processed when the SCA runtime runs your class.

The example below illustrates this overall structure

Example - must be in the file ConvertedStockQuote.php:

<?php

// any includes

include "SCA/SCA.php

/**
 * @service
 */

class ConvertedStockQuote {

       // instance variables, business logic, including at least one public method

}
?>

2.2. Obtaining a reference to another Service Component

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

One SCA component can call the service provided by another SCA component. The service a component provides is made up of all of its public methods. SCA for PHP currently provides two ways for one component to call another: either locally (i.e. within the same PHP run-time, and on the same call stack) or remotely if the called component exposes a Web service binding.

In order for one component to call another, the calling component needs a reference to the called component. This reference is usually an instance variable in the calling component, though references can also be obtained with the SCA::getService() call, as we shall see later. When a component is constructed, proxies are constructed for any instance variable which is a reference to another component, and these proxies are "injected" into the instance variables. Proxies are always used, whether the component is local or remote, in order to provide identical calling behavior between remote and local calls (for example, local calls are made to always pass data by-value). The proxies know how to locate the required component and to pass the calls made on to them.

Instance variables which are intended to hold references to services are indicated by the two PHPDocumentor-style annotations, @reference and @binding. Both annotations are placed in the documentation section for a class instance variable, as shown by the code below.

The @reference annotation before an instance variable indicates that that instance variable is to be initialized with a proxy to a component.

The @binding annotation has two forms, @binding.php and @binding.soap, and indicates that the reference is either to a local component or to a Web service respectively. For both @binding.php and @binding.soap, the annotation identifies the instance variable as a reference to another component and gives a target URI.

At the moment, with the annotation-based method of specifying dependencies, the only way to alter the intended target of a reference is to alter the annotation within the component.

In our ConvertedStockQuote example, the $exchange_rate instance variable will be initialized with a proxy to the local ExchangeRate component whenever an instance of the ConvertedStockQuote is constructed.

Example:

/**
     * The currency exchange rate service to use.
     *
     * @reference
     * @binding.php ../ExchangeRate/ExchangeRate.php
     */
    public $exchange_rate;

For @binding.php, the URI identifies the location of the script containing the implementation of the component. The component will be called locally. The service provided is the set of public methods of the component. The URI must be a simple pathname, either absolute or relative. The component will be loaded with the PHP include directive, after testing to see if it is already loaded with class_exists(). If the URI is a relative path, it is resolved relative to the component containing the annotation. Note that this is different from the normal PHP behaviour where scripts would be looked for along the PHP include_path, This is intended to provide some location-independence for cross-component references.

If this ExchangeRate service were remote and to be called as a Web service, only the @binding line changes. Instead of giving the location of a PHP class, it gives the location of the WSDL describing the web service. In our example component, this is illustrated by the second reference:

Example:

/**
     * The stock quote service to use.
     *
     * @reference
     * @binding.soap ../StockQuote/StockQuote.wsdl
     */
    public $stock_quote;

The StockQuote component will be called via a Web service request. In this case the URI for the WSDL can be a simple pathname, or may contain a PHP wrapper and begin, for example, with file:// or http://. In the event that it is a simple pathname, it can be absolute or relative, and if relative will be resolved relative to the component containing the annotation. Note that this is like the behaviour for @binding.php, and different from the normal PHP behaviour where the file would be looked for relative to the PHP current working directory, which would usually be the location of the first script to be called. This behaviour is intended to give consistency across the different bindings and to provide some location-independence for cross-component references.

2.3. Calling another Service Component

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

The ConvertedStockQuote example also calls the two components to which it has acquired references.

$quote  = $this->stock_quote->getQuote($ticker);
    $rate   = $this->exchange_rate->getRate($currency);

The call to the StockQuote service is a call to a local service; the call to the ExchangeRate service is a call to a remote service. Note that the way the call is made looks the same regardless of whether the call is to a local service or a remote one.

The proxies which have been injected ensure that the way calls to components look and behave are the same way regardless of whether they are to a local or remote service, so that components are not sensitive to whether a call is to a local or a remote service. For example, the proxy for a local service takes copies of the arguments and passes only those copies, to ensure that calls are made to be pass-by-value, as they would be for a remote call. Also, the proxy for a remote service takes the arguments from a positional parameter list and ensures they are packaged properly in a SOAP request and converted back to a positional parameter list at the far end.

In the example above, the $ticker and $currency are clearly PHP scalar types. Components can pass the PHP scalar types string, integer, float and boolean, but data structures on service calls are always passed as Service Data Objects (SDOs); A later section describes how a component can create an SDO to pass on a local or Web service call, or how a component can create an SDO to return. The PHP SDO project documentation describes how to work with the SDO APIs (see http://www.php.net/sdo).

2.4. Locating and calling services from a script which is not an SCA Component

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

Within a component, components obtain references to other components or services as instance variables annotated with @reference, but this is not possible for a script that is not itself also a component. A client script which is not a component must use the SCA::getService static method to obtain a reference to a service, either local or remote. The getService method takes a URI as the argument. Typically this is the location of a local PHP script containing a component, or of a wsdl file, and is used in exactly the same way as the targets of the @binding annotations described in the previous section; that is relative URIs are resolved against the location of the client script and not against the PHP include_path or current working directory.

For example, a script that needed to obtain references to the ExchangeRate and StockQuote services but was not a component would use the getService method as follows:

$exchange_rate = SCA::getService('../ExchangeRate/ExchangeRate.php');

or

$stock_quote = SCA::getService('../StockQuote/StockQuote.wsdl');

Methods on services can then be called on the returned object, just as they can in a component.
Example:

$quote  = $stock_quote->getQuote($ticker);
$rate   = $exchange_rate->getRate($currency);

2.5. Exposing a Service Component as a Web service

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

SCA for PHP can generate WSDL from the annotations within a service component, so that it can be easily deployed and exposed as a Web service, and called either from another SCA component, or from a client program that knows nothing of SCA. To provide SCA with the information it needs to generate the WSDL, it is necessary to add the annotation @binding.soap under the @service annotation and to specify the parameters and return values of the methods using the @param and @return annotations. These annotations will be read when WSDL is generated, and the order and types of the parameters determine the contents of the <schema> section of the WSDL.

SCA for PHP always generates document/literal wrapped WSDL for components that are exposing a Web service. However, components can consume Web services documented with WSDL written in a different style.

The scalar types which can be used in the @param annotation are the four common PHP scalar types: boolean, integer, float and string. These are simply mapped to the XML schema types of the same name in the WSDL. The example below, which is a trivial implementation of the StockQuote service that the ConvertedStockQuote component calls, illustrates string and float types.

Example:

<?php

include "SCA/SCA.php";

/**
 * Scaffold implementation for a remote StockQuote Web service.
 *
 * @service
 * @binding.soap
 *
 */
class StockQuote {

    /**
     * Get a stock quote for a given ticker symbol.
     *
     * @param string $ticker The ticker symbol.
     * @return float The stock quote.
     */
    function getQuote($ticker) {
        return 80.9;
  }
}
?>

WSDL much like the following (though with a service location other than 'localhost', probably) would be generated from this service:

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xsi:type="tDefinitions"
    xmlns:tns2="http://StockQuote" xmlns:tns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns3="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" targetNamespace="http://StockQuote">
  <types>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
      targetNamespace="http://StockQuote">
      <xs:element name="getQuote">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="ticker" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="getQuoteResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="getQuoteReturn" type="xs:float"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  </types>

  <message name="getQuoteRequest">
    <part name="getQuoteRequest" element="tns2:getQuote"/>
  </message>
  <message name="getQuoteResponse">
    <part name="return" element="tns2:getQuoteResponse"/>
  </message>
  <portType name="StockQuotePortType">
    <operation name="getQuote">
      <input message="tns2:getQuoteRequest"/>
      <output message="tns2:getQuoteResponse"/>
    </operation>
  </portType>
  <binding name="StockQuoteBinding" type="tns2:StockQuotePortType">
    <operation name="getQuote">
      <input>
        <tns3:body xsi:type="tBody" use="literal"/>
      </input>
      <output>
        <tns3:body xsi:type="tBody" use="literal"/>
      </output>
      <tns3:operation xsi:type="tOperation" soapAction=""/>
    </operation>
    <tns3:binding xsi:type="tBinding" transport="http://schemas.xmlsoap.org/soap/http" style="document"/>
  </binding>
  <service name="StockQuoteService">
    <port name="StockQuotePort" binding="tns2:StockQuoteBinding">
      <tns3:address xsi:type="tAddress" location="http://localhost/StockQuote/StockQuote.php"/>
    </port>
  </service>
</definitions>

<!-- this line identifies this file as WSDL generated by SCA for PHP. Do not remove -->

2.6. Deploying an SCA component

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

There are no special steps needed to deploy a PHP SCA component. It is sufficient to place the component PHP script in its proper place under the web server document root, just like any other PHP script. It is the SCA::initComponent() executable line within each component that will be executed whenever the script is called, and which will be responsible for making the component respond appropriately to Web service calls, local calls, or requests for WSDL.

2.7. Obtaining the WSDL for an SCA component offering a Service as a Web service

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

SCA components that expose a Web service interface (i.e. have an @binding.soap annotation) will return their WSDL definition in response to an HTTP request with a get parameter of "wsdl". The usual way to obtain this is with "?wsdl" on the end of a URL. The example below uses file_get_contents to obtain WSDL from a service and writes it to a temporary file before then obtaining a reference to the service in the usual way, although you might choose to obtain the WSDL in a browser, or by some other means, and save the file yourself.

Example:

$wsdl 	= file_get_contents('http://www.test.com/Services/Example.php?wsdl');
file_put_contents("service.wsdl",$wsdl); //write the wsdl to a file
$service = SCA::getService('service.wsdl');

NOTE: If the wsdl requires imported xsds, these will need to be fetched separately.

2.8. Understanding how the WSDL is generated

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

SCA for PHP generates WSDL for components which contain an @binding.soap annotation after the @service annotation (do not confuse this with the @binding.soap annotation after an @reference, which refers to a dependency, not to exposing an interface). To generate WSDL, the SCA runtime reflects on the component and examines the @param and @return annotations for each public method, as well as any @types annotations within the component.

These annotations are used to generate document/literal wrapped WSDL to expose this component as a Web service. SCA for PHP always generates document/literal wrapped WSDL for components that are exposing a Web service; however, components can consume Web services documented with WSDL written in a different style.

2.8.1. Location attribute of the <service> element

At the bottom of the WSDL is the <service> element which uses the location attribute to identify the URL of the service. For example this might look as follows:

<service name="ConvertedStockQuote"
...
location="http://localhost/ConvertedStockQuote/ConvertedStockQuote.php"/>

Note that this location is relative to the document root of the web server, and cannot be worked out in advance. It can only be worked out once the component is in its proper place under a running web server, when the hostname and port can be known and placed in the WSDL. Detail from the URL that requests the WSDL is used, so for example if the WSDL is generated in response to a request to http://myserver:1111/ConvertedStockQuote/ConvertedStockQuote.php?wsdl, a location of http://myserver:1111/ConvertedStockQuote/ConvertedStockQuote.php is what will be inserted into the location attribute in the WSDL.

2.8.2. Document/literal wrapped WSDL and positional parameters

SCA for PHP generates WSDL in the document/literal wrapped style. This style encloses the parameters and return types of a method in 'wrappers' which are named after the corresponding method. The <types/> element at the top of the WSDL defines each of these wrappers. If we consider the getQuote method of the ConvertedStockQuote example:

/**
     * Get a stock quote for a given ticker symbol in a given currency.
     *
     * @param string $ticker The ticker symbol.
     * @param string $currency What currency to convert the value to.
     * @return float The stock value is the target currency.
     */
    function getQuote($ticker, $currency)
    {
        $quote  = $this->stock_quote->getQuote($ticker);
        $rate   = $this->exchange_rate->getRate($currency);
        return  $rate * $quote;
    }

The WSDL generated to define this method will name both the method and the parameters, and give an XML schema type for the parameters. The types section of the WSDL looks like this:

<types>
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
      targetNamespace="http://ConvertedStockQuote">
      <xs:element name="getQuote">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="ticker" type="xs:string"/>
            <xs:element name="currency" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="getQuoteResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="getQuoteReturn" type="xs:float"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  </types>

The SCA run-time has special processing to handle how positional parameter lists in the interface are converted to XML containing named parameters in the soap request, and then back to positional parameter lists again. To see why this matters, consider how a PHP script which used a different interface to make a SOAP call would need to construct the parameter list. A PHP script using the PHP SoapClient, for example, would need to pass the SoapClient a single parameter giving the values for "ticker" and "currency", perhaps as an associative array. To insist that SCA components construct parameter lists to make Web service calls in this way would be to make local and remote calls look different, so a different approach is needed.

When SCA generates WSDL for an SCA component it includes a comment in the WSDL which marks that WSDL as being the interface for an SCA component. In this case, when one SCA component calls another through a Web service, the SCA runtime on the calling end takes the positional parameter list from the call and assigns the values one by one to the named elements in the soap message. For example a call to the getQuote() method defined above that passes the values 'IBM' and 'USD' and looks like this:

$quote = $remote_service->getQuote('IBM','USD');

will result in a soap message containing the following:

<getQuote>
  <ticker>IBM</ticker>
  <currency>USD</currency>
</getQuote>

On the service providing end, the SCA run-time takes the parameters one by one from the soap message and forms a positional parameter list from them, re-forming the argument list ('IBM','USD')

At both ends the SCA runtime relies on the order in which the parameters appear in the soap message being the same as that in the target method's parameter list. This is ultimately determined by the order of the @param annotations: this determines the order in which the parameters appear in the WSDL and thereby the order in which they appear in the soap message. Therefore it is essential that the order of the @param annotations matches that of the parameters in the method's parameter list.

2.9. Working with data structures

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

SCA components can pass and return the four PHP scalar types boolean, integer, real and string, but to pass or return data structures, SCA components use Service Data Objects (SDOs). Readers familiar with SDOs will know that they are suitable for representing the sort of structured and semi-structured data that is frequently modeled in XML, and that they serialize very naturally for passing between remote components, or in Web services. SDOs are the only supported way to pass and return data structures. It is not possible to pass or return any other sort of PHP object, or PHP arrays.
The SCA runtime always assures data is passed by-value, even for local calls, so the SCA runtime copies any SDOs in the parameter list before passing them on, just as it does for scalar types.

2.9.1. How data structures are defined to SCA components

Currently the only mechanism for specifying the location of a data structure definition is by specifying the types in an XML schema file. However, in the future it may be possible to define types in other ways, such as based on PHP classes or interfaces, or based on definitions expressed as associative arrays.

To illustrate the use of SDOs we introduce a new component. The PortfolioMangement service below returns an SDO representing a stock portfolio for a given customer.

<?php

include 'SCA/SCA.php';

/**
 * Manage the portfolio for a customer.
 *
 * @service
 * @binding.soap
 *
 * @types http://www.example.org/Portfolio PortfolioTypes.xsd
 *
 */
class PortfolioManagement {

    /**
     * Get the stock portfolio for a given customer.
     *
     * @param integer $customer_id The id for the customer
     * @return Portfolio http://www.example.org/Portfolio The stock portfolio (symbols and quantities)
     */
    function getPortfolio($customer_id) {
        // Pretend we just got this from a database
        $portfolio = SCA::createDataObject('http://www.example.org/Portfolio', 'Portfolio');
        $holding = $portfolio->createDataObject('holding');
        $holding->ticker = 'AAPL';
        $holding->number = 100.5;
        $holding = $portfolio->createDataObject('holding');
        $holding->ticker = 'INTL';
        $holding->number = 100.5;
        $holding = $portfolio->createDataObject('holding');
        $holding->ticker = 'IBM';
        $holding->number = 100.5;
        return $portfolio;
    }

}
?>

The @types annotation:

@types http://www.example.org/Portfolio PortfolioTypes.xsd

indicates that types in the namespace http://www.example.org/Portfolio will be found in the schema file located by the URI PortfolioTypes.xsd. The generated WSDL would reproduce this information with an import statement as follows:

<xs:import schemaLocation="PortfolioTypes.xsd"
                      namespace="http://www.example.org/Portfolio"/>

so the URI, absolute or relative, must be one that can be resolved when included in the schemaLocation attribute.

2.9.2.Creating SDOs

Readers familiar with SDOs will know that they are always created according to a description of the permitted structure (sometimes referred to as the 'schema' or 'model') and that, rather than creating them directly using 'new', some form of data factory is needed. Often, an existing data object can be used as the data factory, but sometimes,and especially in order to get the first data object, a different data factory is needed.

In SCA, either the SCA runtime class or the proxies for services, whether local or remote, can act as the data factories for SDOs. The choice of which to use, when, is described in the next two sections.
We switch to a new example in order to illustrate the creation of SDOs both the pass to a service, and to be returned from a service.
1.2.9.3. Creating an SDO to pass to a service
A caller of a service which requires a data structure to be passed in to it uses the proxy to the service as the data factory for the corresponding SDOs.
For example, suppose a component makes use of a reference to a service provided by a local AddressBook component.

/**
 * @reference
 * @binding.local AddressBook.php
 */
$address_book;

The AddressBook component that it wishes to call is defined as follows:

/**
* @service
* @binding.soap
* @types http://addressbook ../AddressBook/AddressBook.xsd
*/
class AddressBook {

    /**
     * @param personType $person http://addressbook/info (a person object)
     * @return addressType http://addressbook/info (the address object for the person object)
     */
    function lookupAddress($person)  {
    		  ...
    }
}

The AddressBook component provides a service method called lookupAddress() which uses types from the http://addressbook namespace. The lookupAddress method takes a personType data structure and returns an addressType. Both types are defined in the schema file AddressBook.xsd.

Once the component that wishes to use the AddressBook component has been constructed, and the $address_book instance variable initialized, the calling component can use the initialized proxy in $address_book to create the person SDO, as shown below

$william_shakespeare = $address_book->createDataObject('http://addressbook','personType');
 $william_shakespeare ->name="William Shakespeare";
 $address = $address_book->lookupAddress($william_shakespeare);

Note, the use of the proxy as the means to create the SDO is not limited to SCA Components. If a service is being called from a general PHP script, and the reference was obtained with getService() then the same approach is used.

$address_book = SCA::getService('AddressBook.php');
$william_shakespeare = $address_book->createDataObject('http://addressbook','personType');
...

2.9.4.Creating an SDO to return from a component

A component that needs to create a data object for return to a caller uses the createDataObject static method on SCA.php. The component can only create SDOs which conform to a data structure that is defined in an @types annotation. Hence if the AddressBook component described above needed to create an object of type addressType within the namespace personNS, it might do so as follows:

$address = SCA::createDataObject('http://addressbook','addressType');

Readers familiar with the SDO API will recognize these two parameters as the same two parameters that would be passed to an SDO data factory such as the XML DAS.

2.10. Error handling

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

This section describes how errors are handled. There are two types of errors:

SCA runtime exceptions are those that signal problems in the management of the execution of components, and in the interaction with remote services. These might occur due to network or configuration problems.
Business exceptions are those that are defined by the programmer. They extend the PHP Exception class, and are thrown and caught deliberately as part of the business logic.

2.10.1. Handling of Runtime exceptions

There are two types of SCA runtime exception:

SCA_RuntimeException - signals a problem found by or perhaps occurring within the SCA runtime. This can be thrown for a variety of reasons, many of which can occur regardless of whether a connection is being made to a local or a remote service: an error in one of the annotations within a component, a missing WSDL or php file, and so on.
In the case of Web services, an SCA_RuntimeException can also be thrown if a SoapFault is received from a remote Web service and the fault code in the SoapFault indicates that a retry is unlikely to be successful.
SCA_ServiceUnavailableException - this is a subclass of SCA_RuntimeException and signals a problem in connecting to or using a remote service, but one which might succeed if retried.
In the case of Web services, this exception is thrown if a SoapFault is received with a fault code that indicates that a retry might be successful.

2.10.2. Handling of Business exceptions

Business exceptions may be defined and thrown by a component in the normal way, regardless of whether the component has been called locally or remotely. The SCA runtime does not catch business exceptions that have been thrown by a component called locally, so they will be returned to a caller in the normal way. If a component has been called via a Web service, on the other hand, the SCA runtime on the service providing end does catch business exceptions, and will ensure these are passed back to the calling end and re-thrown. Assuming that the calling end has a definition of the exception (that is, is able to include a file containing the PHP class defining the exception) the re-thrown exception will contain the same details as the original, so that the getLine() and getFile() methods for example will contain the location where the exception was thrown within the business logic. The exception will be passed in the detail field of a soap fault with a fault code of "Client".

3. PHP Annotations

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

This section provides definitions of all the annotations which PHP for SCA supports.

3.1. @binding.*

There are two values for this annotation: binding.soap and binding.php. Extra values may be defined in the future, to match the additional bindings being developed in the SCA collaboration.

There are two places in which this annotation is used.

When a @binding.soap annotation immediately follows an @service annotation at the top of a class definition, this indicates that the methods of this class are to be exposed as a Web Service via SOAP. Document/literal wrapped WSDL will be generated automatically for this service.

@binding annotations may also immediately follow an @reference annotation. In this case @binding.soap and @binding.php indicate that the reference is to either a web service or a local binding (a direct call, on the same call stack) respectively.

Examples:

@binding.soap  wsdl=<the location of the WSDL>
@binding.php <the location of a PHP script containing a component>

3.2. @types

The @types annotation is needed when parameters or return types to or from any of the methods are SDOs. The annotation provides a namespace URI, and the location of an XML schema file containing the definitions of the complex types. These values will be used in the generated WSDL if this component is exposed through a web service. Comments are added in parentheses rather than using the // syntax.

Example:

@types http://addressbook ../AddressBook/AddressBook.xsd

3.3. @param

The @param annotation identifies the type and name of a parameter to the method of a service. The first argument to the annotation is the type of the parameter. The second is the name. This syntax matches the use of @param to document method signatures with phpDocumentor.

Example:

@param string $ticker The company ticker symbol

The method parameters can be the scalar PHP types string, integer, real and boolean, or if the method parameter is a data structure, the type, parameter name and namespace of the type. The namespace must have been specified in an @types annotation and the type must be a complex type defined by the schema associated with that types prefix.

Example:

@param personType $person http://addressbook/info (a person object)

3.4. @reference
The @reference annotation indicates that the instance variable that follows is a reference to a service, which may be provided by a local class, or a remote Web service. The @binding annotation that immediately follows indicates which of these sorts of reference this is, and how to bind to it. In each case, a proxy for the target service will be filled in, by dependency injection, whenever an instance of the class is created.

In the future it will be possible to externally rewire references. The SCA Assembly Model specifies how such wires are defined. The source of a wire is of the form <component name>/<reference name> which in SCA for PHP terms will map to <class name>/<instance variable name>.

Example:

@reference

3.5. @return

The @return annotation identifies the type of the return value from a method. The first argument ot the annotation is the type of the return value. If the type is one of the PHP scalar types string, integer, float or boolean, then the annotation matches that of phpDocumentor.

Example:

@return float (the stock quote value)

If the return value is a data structure then the first argument specifies a type name of a non-scalar type and a second argument specifies the namespace of the type. The namespace must have been declared in an @types annotation and the type must be a complex type defined by the schema identified by the same annotation.

Example:

@return Portfolio http://www.example.org/Portfolio The stock portfolio (symbols and quantities)

3.6. @service

The @service annotation is used in the declaration at the head of a class and indicates that the class is to be exposed as a service. The @binding annotations that follow will indicate through which bindings the class is to be exposed.
Example:

@service

A service is potentially the target of a wire (i.e. the URI specified in a binding for a reference). Because SCA for PHP only supports one service per component, it is not necessary to specify a service name and therefore wires simply target the component, identified by its PHP script. See Calling another Service Component for a description of wiring to a service.

4. Unsupported

The most up to date documentation is to be found on the php.net site, at http://www.php.net/manual/en/book.sca.php for example

The following SCA concepts are not currently specified. It is expected that this list will shorten over time, based largely on community requirements. The goal is to start small and gain early community feedback in order to help define the approach and scope of SCA for PHP. Feedback will be solicited around an open source implementation.

Asynchronous: Support for asynchronous service interactions, for example one-way non-blocking calls, and callbacks, is not currently specified.
Bidirectional Interfaces/Peer-to-peer: There is no support for peer-to-peer communications (e.g. bi-directional interface).
Scopes: The concept of scopes is not supported. A subset of those scopes supported by SCA for Java is also relevant to scenarios in PHP (e.g. session), and it is expected this limitation will eventually be removed.
SCDL: PHP SCA components are fully self-configuring (i.e. they require no external configuration such as wires in order to function correctly). However the programming model has been designed in such a way as to support their use in a runtime based on SCDL. Support for definitions in SCDL, and not just annotations, is being considered, and its inclusion would support concepts such as external rewiring, Properties, and Composites.
Pass-by-reference: The SCA for PHP design is focused primarily on the requirements for loosely-coupled SOA solutions, rather than fine-grained component assembly. Consequently, all service communications are pass-by-value.
Additional Bindings: Currently only local and Web service bindings are supported. Additional SCA bindings will be included based on community requirements.
QoS: Qualities of service, such as security and reliable messaging are not supported.

Page Operations

Browse Space

Contents

1. Introduction

1.1. Installation

Prerequisites

Limitations (aka Known problems)

1.2. Glossary

2. Examples

2.1. The structure of a Service Component

2.2. Obtaining a reference to another Service Component

2.3. Calling another Service Component

2.4. Locating and calling services from a script which is not an SCA Component

2.5. Exposing a Service Component as a Web service

2.6. Deploying an SCA component

2.7. Obtaining the WSDL for an SCA component offering a Service as a Web service

2.8. Understanding how the WSDL is generated

2.8.1. Location attribute of the <service> element

2.8.2. Document/literal wrapped WSDL and positional parameters

2.9. Working with data structures

2.9.1. How data structures are defined to SCA components

2.9.2.Creating SDOs

2.9.4.Creating an SDO to return from a component

2.10. Error handling

2.10.1. Handling of Runtime exceptions

2.10.2. Handling of Business exceptions

3. PHP Annotations

3.1. @binding.*

3.2. @types

3.3. @param

3.5. @return

3.6. @service

4. Unsupported