PHP for PostgreSQL code generator

The RISE PHP for PostgreSQL code generator renders PHP source code for database access. The generated code implements the classes and methods corresponding to the information interfaces specified in the RISE model. This includes classes for database access and, optionally, classes implementing SOAP/JSON web services and proxy classes assisting the implementation of a PHP SOAP client. The generated code is solely intended to be used with a PostgreSQL database based on the same RISE model, see the PostgreSQL code generator. If you are new to RISE, please read more in the RISE Resource Center and if you haven't done so yet, download RISE it's Free!

The generated code is based on the PHP PostgreSQL extension. This extension is available by default in newer installations of PHP. All methods, arguments and return values in the generated code are named in accordance with the RISE model and its naming convention.

The generated code relies on data types being decided by PHP at runtime.

Configuration

The code generator renders a configuration file <prefix>.config.php. The configuration file contains a constant that's passed to the PostgreSQL database extension when connecting to the database. You need to modify the configuration file in order to connect to your database. The connection string format is the one specified by the pg_connect function. and you may, for instance, add a port=NUMBER argument if needed.

Instructs the code generator to generate web service source code for all public interfaces and methods in the RISE model.

supportJSON

Instructs the code generator to add support for JSON-style web services, see compliance below. This option is only applicable when generateWS is set.

supportTicket

When this option is set all web services methods have a "string ticket" argument prepended to their argument list. Read more on this topic below. This option is only applicable when generateWS is set.

userLogin

When this option is set all web services methods has the "string userid, string password" arguments prepended to their argument list. Read more on this topic below. This option is only applicable when generateWS is set.

Notes on JSON compliance

The code generator creates code relying entirely on built-in PHP utilities and web service support. SOAP (Simple Object Access Protocol) usage is properly standardized and, thus, there are no compliance issues with respect to RISE. JSON usage, however, is a slightly different matter. You need to pay attention to following specifics introduced by the json_decode and json_encode PHP functions.

Strict input

PHP json_decode isn't as forgiving as the implementation found in web browsers; names must be quoted and quoting, of both names and strings, must use ".

Result packaging

json_encode generates an object containing members matching the method return set, e.g. the JSON result for a RISE Get method could look like:

BLOBs are passed as strings(!). Thus, binary data isn't supported but you may handle text only BLOBs.

Custom code extensions

RISE support definition of custom methods as part of the model. The interface of a custom method is generated by the code generator where as the implementation is not.

Suppose we've got a model in which we add the custom method MyMethod that accepts myArg and returns myRetVal. For MyMethod, we specify that it's implemented using MyClass in MyInclude. The code generator will generate code assuming the specified include file, class and method are all available in our project. Thus, we need to provide the implementation. It should be placed in a file named MyInclude.php and look something like:

Session management

RISE generates support for session management in all PHP web services. This method allows you to execute a block of code before an incoming call (SOAP/JSON) is dispatched to your RISE interfaces, for instance allowing you to set up or verify a session. This mechanism is handy when implementing a standalone PHP web service, i.e. when your front-end is implemented on another platform.

To make use of the session management mechanism you need to implement a class with a static method, Start, that's available to (included by) your web services. We suggest you put your implementation in the MyPrefix.config.php file.

// ... place or include this code in your configuration file

class MyPrefixInit

{

public static function Start()

{

session_start();

// ... or do something else

}

}

Ticket and user login

There are two authentication mechanisms available that you may turn on to rapidly secure your PHP web services: tickets and user login. In both case, these mechanisms instructs the code generator to add extra arguments to your web service methods and make all methods invoke a custom authentication solution. For this to work, your solution must implement the expected authentication methods.

The implementation should be provided using a static method named Verify. The method should reside in class named by your model prefix and the selected mechanism. Finally, these methods must be available to the web service implementation. We suggest you place the authentication implementation in the configuration file (MyPrefix.config.php).

If your implementation returns false the web service will terminate the execution and raise an exception. The database connection is passed to the Verify methods solely for convenience, in case your implementation somehow relies on the database for the actual authentication.

Uploading and downloading files

The PHP code generator supports chunked uploading and downloading of BLOBs (files). See our article on handling BLOBs for further details on how to make use of these methods.

The generated database access classes will use the directory returned by sys_get_temp_dir() during file/BLOB transfer. Each transfer occurs via a uniquely named file. The transfer file is named according to '.RISEBLOB'.md5(uniqid(rand(), TRUE)), however, the actual file name is decided by the tempnam(..) function.

Note! You shouldn't deploy openly available web services containing file upload/download methods in the public domain (Internet) or in an, otherwise, untrusted environment. Instead, mark these methods as private, to exclude them from the web services, and use the generated database access classes in a server-side PHP solution.