|
|
|
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.
|
<?php
define('myPrefix_ConnectionString', 'host=HOST dbname=DATABASE user=USER password=PWD'); |
Code generator settings
The PHP for PostgreSQL code generator has the following properties:
| generateWS |
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:
{ "ID":1,
"myString":"just a string",
"myInt":14,
"myDate":"2007-05-06T00:00:00",
"myBool":true} | |
| Date format |
Dates are passed as strings in ISO 8601 format, e.g. 2010-02-01T14:25 |
| Binary data |
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:
<?php
class MyClass{
public function __construct() {
}
public function MyMethod($myArg) {
// Do something
return (object)array("myRetVal"=>"just a string");
}
}
|
or in case the custom method is specified to use the database
<?php
class MyClass{
public $conn;
public function __construct($conn) {
$this->conn = $conn;
}
public function MyMethod($myArg) {
// Do something with $conn
return (object)array("myRetVal"=>"just a string");
}
} |
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).
// ... place or include this code in your configuration file
class MyPrefixTicket
{
public static function Verify($conn, $ticket)
{
// Your code to verify the ticket, return true if ok
return FALSE;
}
}
class MyPrefixLogin
{
public static function Verify($conn, $userid, $password)
{
// Your code to verify the userid and password, return true if ok
return FALSE;
}
} | 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. |
|
|
|
|
