Serenity AP has a unique data access architecture. The data access follows a logical pattern, and is modeled after Java's Hibernate system. Instead of a database connection outlook, Serenity's data system focuses on creating objects from database tables.

Let's add a simple database call to the Hello World application.

Start by adding the server information to the config.php file in your web root. Open the file and add the following block at the end of the file, substituting your server & database details for the examples:

$INFO['app_hello']['driver'] = 'mysql';
$INFO['app_hello']['host'] = 'localhost';
$INFO['app_hello']['port'] = '';
$INFO['app_hello']['user'] = 'USER';
$INFO['app_hello']['pass'] = 'PASS';
$INFO['app_hello']['dbname'] = 'DATABASE';
$INFO['app_hello']['output_driver'] = 'sgen';

Save the file. Next you need to create the table mapping. Create a new file under the sources/sql/ folder with the name of your application, in this case:

sources/sql/app_hello.php

In the file, you will need to create an array of shorthand table names to the actual database table. In this example, we'll create a table called app_hello_text. Your app_hello.php file will look like this:

<?php
$SQL[ 'Hello.table' ] = array( 'app_hello_text', array() );
?>

Currently the empty array() is necessary, but will be removed in future versions.

Save the file, and create the app_hello_text table in the database you specified in the config.php file with the following columns:

id - INT(11) - auto_increment - primary key
text - VARCHAR(64)

Now, open up your index handler under sources/applications/app_hello/app_index.php. For starters, we'll just pull up a single row. Insert some dummy text into the table, and then change your index handler code to this ( the code portion inside the App() function:

$Hello = Serenity::data()->open( 'Hello.table' );
$Hello->add_restriction( 'id=1' );
$Hello->get();
 
print $Hello->text;

Save the file, and refresh your application. The text from the text column in the table will print out.

Let's change the text after printing it. Add this snippet of code after the print call:

$Hello->text( 'I just changed the text!' );
$Hello->store();
 
print $Hello->text;

Now refresh again. The original text will print first, and then your changed text. The store() call saved the changes back to the database, so next time you refresh, your changed text will print both times.

Let's pull some more rows, without any restrictions. Add some more dummy inserts to the table, and replace the App() code with this:

$Hello = Serenity::data()->open( 'Hello.table' );
$Hello->get();
 
while( $Hello->rows() )
{
    print $Hello->text . '<br />';
}

Now each row's text will output to the browser. If you're wondering, yes you can call store() inside the loop to change each row in the table, the data layer is 100% flexible in that regard.

After you are done with the table connection, call the free() function to remove the connection from memory and free the result pointer:

$Hello = Serenity::data()->free();

That's all for the Hello World tutorial. The data layer obviously has more functions, such as limiting the result set, sorting rows, and deleting. We'll cover that in the API reference section. </code>