Creole is inspired by Java’s JDBC API. If you are familiar with this API, then no doubt much of this will look similar.

Class Methods

Please visit the Creole Webiste for more information.

General Usage

Example: Using Creole API

$conn = self::creole();

// prepared statement
$stmt = $conn->prepareStatement("SELECT * FROM `news_items` WHERE group_id = ?");
$stmt->setInt(1, $groupId);
$stmt->setLimit(10);
$stmt->setOffset(5);

$stmt->executeQuery();

The first parameter to !Model::creole() is a flags parameter. The following flags are currently supported by Creole:

These flags are bits, so you may specify more than one by adding (or using bitwise | operator) them together. Example:

$conn = self::creole(self::PERSISTENT | self::COMPAT_ASSOC_LOWER);

Getting Column Values

The default method to get column values is to use the appropriate get*() method for the column data type. E.g. use getString() to return data from a CHAR/VARCHAR/TEXT column. Creole will perform any unescaping and type conversions. For example:

while($rs->next()) {
         // returns PHP string
        echo "n" . $rs->getString("name");

         // returns PHP int/long
        echo "n" . $rs->getInt("id");

         // returns formatted date
        echo "n" . $rs->getTimestamp("stamp", "m/d/y H:i:s");
}

You can also use the generic !ResultSet::get() method, if you do not want to perform any type conversions on the data you are returning:

while($rs->next()) {
        print $rs->get("name") . " (" . $rs->get("id") . ")";
}

And finally, you can also use the getRow() to return an associative array of the current row:

while ($rs->next()) {
        $row = $rs->getRow();
        foreach ($row as $key => $value) {
                echo $key . ": " . $value;
        }
}

Scrolling ResultSet Methods

Scrolling ResultSet features are supported well in MySQL, PostgreSQL, and SQLite. For Oracle, however, this behaviour has to be emulated. For this reason, reverse scrolling is not currently supported in Oracle.

// Move to first record
$rs->first();

// Move ahead 3 rows
$rs->relative(3);

// Scroll backwards
$rs->previous();

// Move to last position
$rs->last();

ResultSetIterator

In addition to using the traditional scrolling functions, you can also use an SPL Iterator to iterate over the query results. Some drivers (e.g. SQLite) have optimized iterators that will be as fast or faster than the traditional scrolling methods.

foreach ($rs as $row) {
        // $row is an assoc array
        print_r($row);
}

This method of iterating over a ResultSet exists for convenience, and does not provide any type-conversion methods.

The Creole Wrapper class provides methods for interacting with Creole easily and securely.

Class Methods

select ( string statement [, array placeholder] )

mixed
Executes the SQL SELECT statement in a PreparedStatement object and returns the ResultSet generated by the query.

insert ( string table_name, array record [, bool on_duplicate_key_update] )

mixed
Executes the SQL INSERT statement in a PreparedStatement object.

update ( string table_name, array record, array where_clause )

mixed
Executes the SQL UPDATE statement in a PreparedStatement object.

delete ( string table_name, array where_clause )

mixed
Executes the SQL DELETE statement in a PreparedStatement object.

selectAndPaginate ( string statement, int current_page [, int results_per_page] )

mixed
Executes the SQL SELECT statement in a PreparedStatement object, add the LIMIT clause and returns the resultset generated by the query.

getTotalRows ()

int
Returns the total number of rows returned by the last executed query.

getInsertId ()

int
Returns the last inserted id.

getLastQuery ()

string
Returns the last executed query.

General Usage

Example: SELECT prepared statement

$statement = "SELECT * FROM `news_items` WHERE `year` = ? AND `group_id` = ?";
$placeholder = array("2007", 4);

// Returns a resultset on success or false on failure
$this->db()->select($statement, $placeholder);

You should always use the “?” place holder to add values to a statement, as this will prevent SQL injection attacks by ensuring that data is converted to the proper type, and when appropriate escaped and quoted.

Example: INSERT prepared statement

$fields = array(
        "user_id" => 12,
        "activation_key" => "38su2373js92"
);

$onDuplicateKeyUpdate = true;

// Returns the affected rows on success or false on failure
$this->db()->insert("activation_code", $field, $onDuplicateKeyUpdate);

Example: UPDATE prepared statement

$fields = array(
        "password" => $userId,
        "salt" => $activationCode
);

$where = array(
        "statement" => "`user_id` = ?",
        "placeholder" => array(12)
);

// Return the affected rows on success or false on failure
$this->db()->update("user", $fields, $where);

Example: DELETE prepared statement

$where = array(
        "statement" => "`user_id` = ? AND `user_id` = ?",
        "placeholder" => array(12, 13)
);

// Returns the affected rows on success or false on failure
$this->db()->delete("users", $where);

Getting Column Values

The default method to get column values is to use the appropriate get*() method for the column data type. E.g. use getString() to return data from a CHAR/VARCHAR/TEXT column. Creole will perform any unescaping and type conversions. For example:

while($rs->next()) {
         // returns PHP string
        echo "n" . $rs->getString("name");

         // returns PHP int/long
        echo "n" . $rs->getInt("id");

         // returns formatted date
        echo "n" . $rs->getTimestamp("stamp", "m/d/y H:i:s");
}

You can also use the generic !ResultSet::get() method, if you do not want to perform any type conversions on the data you are returning:

while($rs->next()) {
        print $rs->get("name") . " (" . $rs->get("id") . ")";
}

And finally, you can also use the getRow() to return an associative array of the current row:

while ($rs->next()) {
        $row = $rs->getRow();
        foreach ($row as $key => $value) {
                echo $key . ": " . $value;
        }
}

Scrolling ResultSet Methods

Scrolling ResultSet features are supported well in MySQL, PostgreSQL, and SQLite. For Oracle, however, this behaviour has to be emulated. For this reason, reverse scrolling is not currently supported in Oracle.

// Move to first record
$rs->first();

// Move ahead 3 rows
$rs->relative(3);

// Scroll backwards
$rs->previous();

// Move to last position
$rs->last();

ResultSetIterator

In addition to using the traditional scrolling functions, you can also use an SPL Iterator to iterate over the query results. Some drivers (e.g. SQLite) have optimized iterators that will be as fast or faster than the traditional scrolling methods.

foreach ($rs as $row) {
        // $row is an assoc array
        print_r($row);
}

This method of iterating over a ResultSet exists for convenience, and does not provide any type-conversion methods.

Zend_Mail, supported by Zend_Mime, creates and sends e-mail messages with the format text or HTML. Zend_Mime is a support set for handling multipart MIME messages. Zend_Mail allows e-mail to be sent in an easy form while preventing mail injection.

General Usage

Example: Simple email with Zend_Mail

$mail = new Zend_Mail();
$mail->setBodyText("This is the text of the mail");
$mail->setFrom("somebody@example.com", "Some Sender");
$mail->addTo("somebody_else@example.com", "Some Recipient");
$mail->setSubject("Test Subject");
$mail->send();

For security reasons, Zend_Mail filters all header fields to prevent header injection with newline (\n) characters. You also can use most methods of the Zend_Mail object with a convenient fluent interface. A fluent interface means that each method returns a reference to the object on which it was called, so you can immediately call another method.

Example: Zend_Mail fluent interface

$mail = new Zend_Mail();
$mail->setBodyText("This is the text of the mail.")
    ->setFrom("somebody@example.com’, ‘Some Sender")
    ->addTo("somebody_else@example.com", "Some Recipient")
    ->setSubject("TestSubject")
    ->send();

Zend_Mail messages can be sent via SMTP, so Zend_Mail_Transport_SMTP needs to be created and registered with Zend_Mail before the send() method is called.

Example: Sending email via SMTP

$tr = new Zend_Mail_Transport_Smtp("mail.example.com")
Zend_Mail::setDefaultTransport($tr);

$mail = new Zend_Mail();
$mail->setBodyText("This is the text of the mail.");
$mail->setFrom("somebody@example.com", "Some Sender");
$mail->addTo("somebody_else@example.com", "Some Recipient");
$mail->setSubject("Test Subject");
$mail->send();

Example: Sending multiple emails per SMTP connection.

$mail = new Zend_Mail();
$tr = new Zend_Mail_Transport_Smtp("mail.example.com");
Zend_Mail::setDefaultTransport($tr);

$tr->connect();
for ($i = 0; $i < 5; $i++) {
        $mail->setBodyText("This is the text of the mail.");
        $mail->setFrom("somebody@example.com", "Some Sender");
        $mail->addTo("somebody_else@example.com", "Some Recipient");
        $mail->setSubject("Test Subject");
        $mail->send();
}
$tr->disconnect();

To send an e-mail in HTML format, set the body using the method setBodyHTML() instead of setBodyText(). The MIME content type will automatically be set to text/html then. If you use both HTML and Text bodies, a multipart/alternative MIME message will automatically be generated:

Example: Sending an HTML email

$mail = new Zend_Mail();
$mail->setBodyText("My Nice Test Text");
$mail->setBodyHtml("My Nice Test Text");
$mail->setFrom("somebody@example.com", "Some Sender");
$mail->addTo("somebody_else@example.com", "Some Recipient");
$mail->setSubject("TestSubject");
$mail->send();

Learn more about Zend_Mail

The Cache component is a little cache system. It’s optimized for high traffic websites so it is really fast and safe, it uses file locking and/or anti-corruption tests.

This component was originally developed by Fabien Marty.

General usage

Every module of Cache follows the same philosophy. Parameters, others than default ones, are set using the setOptions() method. A cache file is identified by a cache ID (and eventually a group). For obvious flexibility reasons, the logic of ID’s choice is left to the developer.

Example: The data is built then recovered in an unique variable

// Set a id for this cache
$id = "123";

if ($data = $this->cache()->get($id)) {
        echo "Data found: " . $data;
} else {
        echo "No valid cache found. Saving data";
        $this->cache()->save($data);
}

Example: Setting options

// This options are set by default
$options = array(
    "cacheDir" => $this->cache()->getCacheDir(),
    "lifeTime" => intval(24*60*60),
);

// Set options
$this->cache()->setOptions($options);

Available options

You can use the setOptions() method to pass an associative array as an argument and set any of the following options:

cacheDir: /cache
string

Directory where to put the cache file (with a trailing slash at the end).

caching: TRUE
boolean

Enable / disable caching.

lifeTime: 24*60*60
integer

Cache lifetime in seconds (you can use a null value for an eternal cache lifetime).

fileLocking: TRUE
boolean

Enable / disable file locking. Can avoid cache corruption under bad circumstances.

writeControl: TRUE
boolean

Enable / disable write control. Enable write control will lightly slow the cache writing but not the cache reading. Write control can detect some corrupt cache files but maybe it’s not a perfect control.

readControl: TRUE
boolean

Enable / disable read control. If enabled, a control key is embeded in cache file and this key is compared with the one calculated after the reading.

readControlType: crc32
string

Type of read control (only if read control is enabled). Must be ‘md5′ (for a md5 hash control (best but slowest)), ‘crc32′ (for a crc32 hash control (lightly less safe but faster)) or ’strlen’ (for a length only test (fastest)).

fileNameProtection: TRUE
boolean

File Name protection (if set to true, you can use any cache id or group name, if set to false, it can be faster but cache ids and group names will be used directly in cache file names so be careful with special characters).

automaticSerialization: FALSE
boolean

Enable / disable automatic serialization (it can be used to save directly data’s which aren’t strings but it’s slower).

memoryCaching: FALSE
boolean

Enable / disable “Memory Caching” (NB : there is no lifetime for memory caching, only the end of the script).

onlyMemoryCaching: FALSEboolean

Enable / disable “Only Memory Caching” (if enabled, files are not used any more).

memoryCachingLimit: 1000
integer

Max number of records to store into memory caching.

automaticCleaningFactor: 0
integer

Disable / Tune the automatic cleaning process. The automatic cleaning process destroy too old (for the given life time) cache files when a new cache file is written. 0 means “no automatic cache cleaning”, 1 means “systematic cache cleaning” (slow), x>1 means “automatic cleaning randomly 1 times on x cache writes”. A value between 20 and 200 is maybe a good start.

hashedDirectoryLevel: 0
integer

Set the hashed directory structure level. 0 means “no hashed directory structure”, 1 means “one level of directory”, 2 means “two levels”… This option can speed up Cache only when you have many thousands of cache file.