2.3. PHP basics

Midgard Web application server uses the PHP engine as its scripting language solution. PHP is a popular scripting language used in over a million Web servers (Netcraft Web server survey, March 2000).

It is not in the scope of this manual to be a generic PHP tutorial, and users wanting to learn more about the language should refer to the excellent PHP Manual on http://www.php.net/manual/.

Midgard brings some additions and modifications to the standard PHP syntax. The rest of this section is dedicated for familiarizing the reader with these additions.

2.3.1. Midgard functions

In addition to the standard PHP functions, Midgard provides the developer with an additional function set that can be used for manipulating data in the Midgard database. For easier identification, these functions all contain the mgd_ prefix.

The Midgard functions can be divided into four basic categories based on what kind of operation they perform. The usage of Midgard's functions is similar with all Midgard record types for simplified operation.

2.3.1.1. List functions

The list functions return a set of records from the database. They are given a variable set of arguments to specify the search and sort criteria used in querying the database. The list functions return a php object whose member variable N contains the number of returned records and the method fetch() fills the object fields with information of the records each in turn. The type of the records determines the set of fields that are returned. The list functions generally only return simple and short fields of the records. You need to use a mgd_get function to access the rest of the record.

2.3.1.2. Get functions

The get functions return the contents of a database record. They take the record id as argument and return the contents of the record as a php object. Access rights are checked to determine how much information of the record is returned to the user.

2.3.1.3. Create functions

The create functions add records to the database. They are given a set of field values as arguments and they return the id number of the created record on success or zero on failure. The functions only create the record if the user has proper privileges and there are not yet record's with the same name and properties in the database. The functions also set the creation timestamps and creator information.

2.3.1.4. Update functions

The update functions modify records in the database. They are given the record id and a set of field values as arguments and they return true if the record was successfully modified. Only users with enough access rights are allowed to modify records. The modification timestamp and revision information of the record is also updated. Normally the update functions allow users to change only a restricted set of fields of a record. For example the type code of an article or the name of a user preference is set at creation time and cannot be changed afterwards. There are also a few extra update functions that update a special set of fields of a record. Examples of such extra functions are mgd_update_password and mgd_update_article_score.

2.3.1.5. Delete functions

The delete functions remove records from the database. They all take a record id as an argument and return true if the given record was successfully removed from the database. A user is allowed to remove a record only if he has appropriate privileges and there are no links pointing to the record.

2.3.1.6. Object-oriented data handling

Note: Please note that the OOP-style data handling is supported only in Midgard 1.4 'Bifrost' and later releases.

The OOP-style functions simplify the handling of Midgard records. They allow you to set the record fields first and then just call a no-argument method to update the database contents. No more need to copy or reset all unused extra fields. Consider the difference:

Old style:

<?php
mgd_create_article(0, $topic, '', $title, $abstract, $content,
                     $midgard->user, '', '', 0, 0, 0, 0,
                     '', '', '', 0);
?>

OOP style:

<?php
  $article=mgd_get_article();
  $article->topic=$topic;
  $article->title=$title;
  $article->abstract=$abstract;
  $article->content=$content;
  $article->author=$midgard->user;
  $article->create();
?>

Yes, it is more lines, but the code is a lot clearer and easier to write. Another, even better example, setting an extra field of an article:

Old style:

<?php
  $article=mgd_get_article($id);
  mgd_update_article($id, $article->topic, $article->name,
                     $article->title, $article->abstract, 
                     $article->content, $article->author,
                     $article->url, $article->calstart,
                     $article->caldays, $article->icon, 
                     $article->view, $article->print,
                     $extra, $article->extra2, $article->extra3);
?>

OOP style:

<?php
  $article=mgd_get_article($id);
  $article->extra1=$extra;
  $article->update();
?>

The new OOP functions are attached to the returned objects in mgd_get_xx. Currently only person, preference, group, member, article and topic records are supported. Each record type is assigned the three member functions create, update and delete. These methods call the corresponding mgd_create_xx, mgd_update_xx and mgd_delete_xx functions with the fields of the record object as arguments. In addition there are methods setScore and settype defined for article records and setscore for topic records.

<?php
  $record->create();
?>

Creates a new record in the database. The fields of the record object are used as arguments to the corresponding mgd_create_xx function. If the record was successfully created, then the id field of the object is set and the id number is returned. Zero (false) is returned on failure.

<?php
  $record->update();
?>

Updates the contents of a record in the database. The fields of the record object are used as arguments to the corresponding mgd_update_xx function. True is returned on success, false otherwise. The record object (in PHP) is not modified.

Warning

Bug in the current update() method implementation causes Apache process to segfault. Use mgd_update_xx instead until the bug is fixed.

<?php
  $record->delete();
?>

Deletes the record from the database. True is returned on success, false otherwise. The record object (in PHP) is not modified nor deleted.

<?php
  $article->setscore($score);
  $article->settype($type);
  $topic->setscore($score);
?>

These functions first set the given field of the record object and then call mgd_update_article_score, mgd_update_article_type and mgd_update_topic_score respectively to update the database contents. True is returned on success, false otherwise.

2.3.2. Syntax additions

Midgard adds a new language construct to PHP which allows you to include the value of a variable in HTML with the use of an ?> echo $var; <? construct. You can now simply use &(variablename); directly in HTML. Note the absence of the "$". Object variables that would normally be accessed in PHP code as $object->field can be inserted as &(object.field);.

The way the value is inserted can be specified by adding a modifier after the variable name: &(variable:modifier);. The modifiers are:

Modifiereffect
hadd value as HTML. This will escape " to &quot;, & to &amp;, < to &lt;, > to &gt;. Everything between [< and >] is added verbatim with the [< and >] dropped. PHP code embedded in such a section is executed.
padd value as PHP (HTML embedding allowed). This will escape " to &quot;, & to &amp;, < to &lt;, > to &gt;. Everything between [< and >] is added verbatim with the [< and >] dropped. PHP code embedded in such a section is executed.
Hadd value as HTML. Everything is included verbatim.
f add value as formatted text. The plain text input is formatted as HTML on the fly. Lines starting with "-" will be transformed to unnumbered lists, <p> will be added between paragraphs delimited by an empty line. Everything between [< and >] is added verbatim with the [< and >] dropped. PHP code embedded in such a section is executed.
F add value as formatted text. The plain text input is formatted as HTML on the fly. Lines starting with "-" will be transformed to unnumbered lists, <p> will be added between paragraphs delimited by an empty line. Additionally, lines after an empty line with less than 10 words that do not end in a period are formatted as <h2> Everything between [< and >] is added verbatim with the [< and >] dropped. PHP code embedded in such a section is executed.
u add the value urlencoded, replacing non-safe URI characters with their %code equivalents.

Table 2-1. Inline variable display modifiers