KMYSQL-PHP DOCUMENTATION


Table of contents

  1. What is kmysql-php?
  2. Requirements
  3. Library documentation
    1. Installation
    2. Principles
    3. Reference
  4. A short example
  5. Current limits
  6. Contact


1. What is kmysql-php?

Current version is 0.1.0.

Kmysql-php is a PHP library permitting ultra-easy acces to KMySql forms via a browser, as standard HTML forms. Just three lines of PHP code are enough to provide full access to a form. A self-documented working example is also available in this package. For more information about KMySql, take a look at its web site.

Since KMySql 1.2.x forms work only with MySql servers, this library currently only works with MySql.

It will be integrated in the next version of KMySql (which is KSql 2.0), and since KSql will handle properly all database types, the ksql-php library will also do so.


2. Requirements

To make kmysql-php work properly, you will need the following packages installed on your system:


3. Library documentation

3.1. Installation

It couldn't be simpler: just copy kmysql.php3 under your web-server tree. If you wish to use the example as-is, you have to copy the example directory to the same place.

3.2. Principles

This library aims to provide a ultra-simple interface, and offers you simple functions to:

3.3. Reference

First of all, to use this library you must insert in your php code a line like: 


<?php
...
require("/path/to/kmysql.php3");
...
?>

Then you will have access to the following functions:

ksql_create_form(string host, string user, string passwd, string base, string form_name, string action)
Parameters:
host The name of the DB server
user A valid user name for the DB servere
password The associated password
base The name of the base containing the form you want to display
form_name The name of the form you want to display
action The URL that will be called when the form is submitted
Returns Nothing
Description: This function creates a complete HTML form corresponding to the kmysql form given by its name. This form has to be included in a complete HTML page. If an error occurs the function will die with the appropriate error message.

ksql_run_form(string host, string user, string passwd, string base, array post_vars)
Parameters:
host The name of the DB server
user A valid user name for the DB servere
password The associated password
base The name of the base containing the form
post_vars The variables transmitted using the POST method. In most cases you will pass the php variable $HTTP_POST_VARS here. Note that the PHP varaible php_track_vars must be set to use this variable.
Returns The result of the query generated by the form. See description for details.
Description: This function is used to treat the datas submitted via a form. It constructs the SQL query, sends it to the server, and returns the result an associative array, containing the following elements:
  • $result["type"] : The result type, one of the following values:
    • 0 : An error occured
    • 1 : Query OK (for INSERT, UPDATE, DELETE, ...)
    • 2 : Query OK with resulting rows (for SELECT)
  • $result["message"] : The success or error message as a string
  • $result["rows"] : When the query returns rows, this is an array of rows. Each row is a array of fields as strings
  • $result["fields"] : When the query returns rows, this is an array of strings representing the names of the columns
If an error occurs the function will die with the appropriate error message.

ksql_print_result_to_table(array result)
Parameters:
result The result of a query as returned by ksql_run_form().
Returns Nothing
Description: Prints out the result as an HTML table. The passed result must contains rows (type = 2).

ksql_print_result(array result)
Parameters:
result The result of a query as returned by ksql_run_form().
Returns Nothing
Description: Prints out the result depending of its type. If the result contains arrays, this calls ksql_print_result_to_table(). Otherwise it prints a error or success message.


4. A short example

Let's say we want to run the kmysql form named "My form", which is in the base "my_base" hosted by a mysql server name "mysqlhost.domain.com". We suppose that the user "bob" as access to this base with the password "xxxx".

We will create two PHP pages:

Here is the code for the first page: form.php3. 


<html>

<body>

<h1> Here is my form: </h1>

<?php

require("/path/to/kmysql.php3");

ksql_create_form("mysqlhost.mydomain.com", "bob", "xxxx", "my_base", "My form", "result.php3");

?>

</body>

</html>

Here is the code for the second page: result.php3. 


<html>

<body>

<h1> Here is the result: </h1>

<?php

require("/path/to/kmysql.php3");

$result = ksql_run_form("mysqlhost.mydomain.com", "bob", "xxxx", "my_base", $HTTP_POST_VARS);

ksql_print_result($result);

?>

</body>

</html>

That's all!


5. Current limits


6. Contact

The author's mail: Frédérik Bilhaut
The K(My)Sql site: ksql.sourceforge.net
The KSql project has mailing lists. Please prefer to use them to reach the kmysql team.