onpubarticles_tutorial.php

<?php

/* To run this tutorial on your own system, save this file as
 * onpubarticles_tutorial.php in a directory where Onpub is installed (or
 * adjust the include path below), then on a command line type:
 * php onpubarticles_tutorial.php
 */

/* Include the OnpubAPI classes.
 * Assumes Onpub is installed in the same directory as this file.
 * Adjust the include path below if Onpub is installed elsewhere on your
 * system.
 */
include "onpub/api/onpubapi.php";

/* Now we want to initialize the connection to the database by constructing
 * a PDO (PHP Data Object). Here we're connecting to a MySQL database running
 * on localhost. We're choosing to use the database called "test". The username
 * we're connecting with is also called "test" and the password is "test". You
 * can modify these parameters to test this script on your own system. Also
 * note that the PDO constructor will throw an exception if it can't establish
 * a connection to the database. We will catch the exception in that case and
 * display the error message.
 */
try {
     $pdo = new PDO( "mysql:host=localhost;dbname=test", "test", "test" );
}
catch ( PDOException $e ) {
    echo $e->getMessage() . "\n\n";
    exit(1); // Abort the script because we couldn't connect to the database.
}

/* Before we start managing articles in the database we first want to check to
 * see if the database is setup correctly. The OnpubDatabase class provides
 * methods to do this. Since this is a tutorial that is designed to run on any
 * system with Onpub installed, we first have to check to see if the Onpub
 * database schema is installed in the "test" database we just connected to.
 * To do this we'll instantiate a new OnpubDatabase article using the PDO
 * object we just constructed above.
 */
$odatabase = new OnpubDatabase( $pdo );

/* Let's call the status() method to check to see if the Onpub database schema
 * is installed.
 */
if ( is_array( $odatabase->status() ) ) {
    // The schema is not installed yet, call the install() method to install it
    // in the "test" database. install() will throw an exception if there's an
    // error.
    try {
        $odatabase->install();
    }
    catch ( PDOException $e ) {
        echo $e->getMessage() . "\n\n";
        exit(1); // Couldn't install the schema, abort the script.
    }
}

/* If we reach this point, the Onpub tables/schema should now be installed in
 * the "test" database. Now we're ready to start using the OnpubArticles class
 * to manage articles in the database. Onpub itself uses the OnpubArticles
 * class to manage articles in the database. Any change you make to the articles
 * in the database using the OnpubArticles class will be refelected when
 * viewed in Onpub. In turn, any changes you make to articles with Onpub will
 * be reflected when accessing the data with OnpubAPI (provided you're
 * connecting to the same database in both instances). Anyway, now we're ready
 * to start showing you how the various OnpubArticles methods work to manipulate
 * articles in the database. First we'll construct an OnpubArticles object using
 * the database connection we created above. Everytime an OnpubArticles method
 * is called, the PDO object will be used to communicate with the connected
 * database.
 */
$oarticles = new OnpubArticles( $pdo );

/* Now that we have a properly initialized database and OnpubArticles object,
 * we're ready to start showing you how to use the methods in the OnpubArticles
 * class to manipulate articles in the database. First, let's create a new
 * article and insert it into the database.
 */
$article1 = new OnpubArticle();

/* Note above that we just constructed an OnpubArticle object. In OnpubAPI each
 * class that uses a plural in its name or ends with the character 's'
 * basically represents a table in the database, and provides methods for
 * manipulating the various fields and/or data types in that table. Each one
 * of the OnpubAPI classes which represent a table in the Onpub database
 * schema have a corresponding singular class name (in this example an
 * OnpubArticle). These corresponding class names which don't end with an 's'
 * basically represent a single row in the corresponding table. In this example
 * the OnpubArticle class is a single row in the OnpubArticles table.
 * Abstractly an OnpubArticle object is simply an article. And an OnpubArticles
 * object is simply the database table which contains multiple articles. This
 * will become more clear as the tutorial moves along. Now that we have an
 * OnpubArticle object, we want to set some of it's properties before we insert
 * it into the database.
 */
$article1->title = "Zelig"; // Set the article's title.
$article1->content = "I have an interesting case. I'm treating two sets of " .
                     "Siamese twins with split personalities. I'm getting " .
                     "paid by eight people."; // Set the article's content.

/* Now that we've defined the article's title and we've given it some content,
 * we're ready to insert the article into the database. The insert() method
 * will throw an exception if there's any database error when inserting the
 * article.
 */
try {
    $ID = $oarticles->insert( $article1 );
}
catch ( PDOException $e ) {
    echo $e->getMessage() . "\n\n";
    exit(1); // Couldn't insert the article, abort.
}

/* The article should now be saved in the database in the table called
 * OnpubArticles. If you were now to log in to the "test" database running
 * on localhost with Onpub you would be able to view and edit this article
 * that we just inserted. One of the nice features of OnpubAPI is that if you
 * were to run this script over and over, the code will detect that this
 * this article is already in the database and will not insert a duplicate
 * copy. Also, note that insert returns the ID of the article we just
 * inserted. Every row in the Onpub database is identified by a numeric ID. We
 * use these IDs to target our edits to specific rows in the database. Let's
 * output the article's ID to let the user of this script know that the article
 * was successfully inserted into the database. By the way, the ID is also
 * useful because it will never change, so this article can always be
 * identified in Onpub and OnpubAPI using its ID number.
 */
echo '<< Insert new articles into the database >>' . "\n\n";

echo 'OnpubArticle with title "' . $article1->title . '" has ID ' . $ID .
     ' in the OnpubArticles table.' . "\n\n";

/* Let's insert a couple more articles into the database so we can demonstrate
 * the select() method, which selects multiple articles from the database at a
 * time. First we construct the OnpubArticle objects we're going to insert.
 */
$article2 = new OnpubArticle();
$article2->title = "Aquemini";
$article2->content = "My mind warps and bends floats the wind count to " .
                     "ten meet the twin Andre Ben. welcome to the lion's " .
                     "den";

$article3 = new OnpubArticle();
$article3->title = "GITS";
$article3->content = "Any way you look at it, all the information that a " .
                     "person accumulates in a lifetime is just a drop in " .
                     "the bucket.";

/* Now we're ready to insert these two new articles into the database. Note
 * that we can insert both these articles with 1 call to insert() by adding
 * the articles to an array.
 */
try {
    $IDs = $oarticles->insert( array( $article2, $article3 ) );
}
catch ( PDOException $e ) {
    echo $e->getMessage() . "\n\n";
    exit(1); // Couldn't insert the articles, abort.
}

/* Note that when you insert multiple articles at once, insert() returns the
 * IDs of the articles in an array ordered by the order the articles were
 * inserted into the database.
 */
echo 'OnpubArticle with title "' . $article2->title .
     '" has ID ' . $IDs[0] . ' in the OnpubArticles table.' . "\n\n";

echo 'OnpubArticle with title "' . $article3->title .
     '" has ID ' . $IDs[1] . ' in the OnpubArticles table.' . "\n\n";

/* Now that we have multiple articles in the database, we're ready to show you
 * how the select() method works. Calling select() with no arguments will
 * return all articles in the database ordered by ID in ascending order. The
 * return type for this method is an array of OnpubArticle objects.
 */
$articles = $oarticles->select();

/* Now we'll print out all the articles which we just selected from the
 * database.
 */
echo '<< Select all articles in the database >>' . "\n\n";

foreach ( $articles as $article ) {
    echo 'OnpubArticle with title "' . $article->title .
         '" has ID ' . $article->ID . ' and content:' . "\n" .
         wordwrap( $article->content, 80 ) . "\n\n";
}

/* Now we'll see how to use the OnpubQueryOptions object to control what order
 * select() returns the articles in. First we'll show you how to select all
 * articles by title in ascending alphabetical order.
 */
$queryOptions = new OnpubQueryOptions();
$queryOptions->orderBy = "title"; // Order results by title
$queryOptions->order = "ASC"; // Order results in ascending order, A-Z

/* Now we call select() again and we pass the OnpubQueryOptions object as the
 * first argument.
 */
$articles = $oarticles->select( $queryOptions );

/* Now we'll print out the articles we just selected, they should output in the
 * order we specified above.
 */
echo '<< Select all articles by title in ascending order >>' . "\n\n";

foreach ( $articles as $article ) {
    echo 'OnpubArticle with title "' . $article->title .
         '" has ID ' . $article->ID . '.' . "\n\n";
}

/* Now we'll demonstrate the update() method, which updates articles already
 * existing in the database. In this example we'll add an author to each one
 * of the articles we created above. First we have to construct the OnpubAuthor
 * objects and then add them to their respective articles.
 */
$author1 = new OnpubAuthor();
$author1->displayAs = "Woody Allen";

$author2 = new OnpubAuthor();
$author2->displayAs = "Outkast";

$author3 = new OnpubAuthor();
$author3->displayAs = "Mamoru Oshii";

/* Now we'll call authors[] =) on each article to add/associate the authors
 * with their respective articles.
 */
$article1->authors[] = $author1;
$article2->authors[] = $author2;
$article3->authors[] = $author3;

/* Now we'll call update() for each article to save the above changes to the
 * database.
 */
$oarticles->update( $article1 );
$oarticles->update( $article2 );
$oarticles->update( $article3 );

?>