Trying out PECL's SCA_SDO package

In order to start offering Web Services inside Dokeos, I (and Stefaan Vanbillemont) have been testing out the SCA_SDO package from PECL (for PHP), that reportedly offers the possibility to deploy web services from existing functions only by including a common file and adding a bit of documentation "PHPDocumentor style" to the code. As we are using PHPDocumentor-like comments already, and have a lot of existing functions possibly offering all the services we would like to offer as web services, I thought SCA_SDO was a perfect match. The SDO-part of the extension will not be used in our context though, so I will focus on a short and early analysis of what we need and what SCA has to offer, then will show a short example of what we can do with a Dokeos + SCA combination. I will be using information gathered from http://www.osoa.org/display/PHP/SCA+Documentation and http://www.php.net/manual/en/sca.examples.exposing-webservice.php Apparently, the latter is more up-to-date (so it might cut your research time), but it is less detailed in terms of theory about the SCA_SDO package. First of all, we need something to re-use the Dokeos code, not write new code, if at all possible. The SCA package offers that. However, it also depends on your code using a class structure, so you can't just use a functions library. That means we can't use functions like api_get_version(), just because it is outside of a class. Second, we need to be able to authenticate (or provide some way to limit the service to only secured sources) the service calls. However, SCA doesn't implement any kind of security. This is very bad in our context because we don't want to rewrite all methods just to be able to provide a secured service... However, if we ignore those two issues, deploying web services with SCA is very easy. As a test, we could use one of the PHP libraries in the form of a class, like UserManager. However, a series of problems might appear when trying to do that...

1. the file name needs to be the same as the class name (this will be a major hassle for most existing open-source projects), otherwise you get a blank page when asking for the wsdl.
2. the @param tags in the PHPDoc of each function need to be defined exactly as @param [type] [$variable] [comment], with the comment being optional, otherwise you get a blank page. The type can be 'int' or 'integer' (or any other simple type).
3. you *might* not be able to use complex types
4. all methods in the file must match the PHPDoc syntax exactly (in terms of @param and @return), otherwise you'll get a blank page (this is also a hassle).
5. the class header comments *must* absolutely be a space+star+space+@... form, otherwise you get a blank page.
6. you cannot use another file to include a class definition file, thus allowing you to rename your file (use UserManager.php to include usermanager.lib.php that defines UserManager class).

Apart from these restrictions, you can:

1. use a parameter variabe name in the comments which doesn't match the one in the function parameters
2. use underscores for the class' name and the methods' names
3. use normal '//' and '/** */' comments between two methods

Thus, we might end up with a system to re-use existing methods, but it wouldn't be at all that easy to make it work. An example of completely re-worked and partial usermanager.lib.php, renamed for the occasion as UserManager.php, would be:

<?php require_once 'SCA/SCA.php'; /**  * This library provides functions for user management.  * it in your code to use its functionality.  *  * @service  * @binding.soap  *  */ class UserManager {   /**   * Delete a user from the platform.   *   * @param integer $userId The user id.   * @return bool true if user is succesfully deleted, false otherwise.   */   function deleteUser($userId) {    return true;   } } ?>

However, even here there is a fundamental problem, as we still need to require global.inc.php from here (to get access to the database itself and to the database library). We're not really having a complete solution here...