~GSoC 2010: Dwi's Installer Process

This is the documentation of ThinkUp’s Installer Process. This page is in-progress and will be updated frequently to reflect new changes on Dwi’s work for ThinkUp’s Installer. If you want to know what is being done and in-progress on ThinkUp’s Installer see the ThinkUp’s Installer Milestones. To know how the Installer works, read the ThinkUp’s Installer Overview and ThinkUp’s Installer Structure. On each ThinkUp’s release there may be an update on table structure or new version of library requirements, in this case ThinkUp’s Installer should be updated and there’s a guide for this case.

ThinkUp’s Installer Milestones

Milestone #1

• Able to install ThinkUp easily from fresh source » DONE
• Able to repair ThinkUp easily from existing ThinkUp » DONE
• Port existing MySQL-only to DAO DONE
• Unit tests on install and repair » DONE

Milestone #2

• Able to upgrade ThinkUp easily » NOT YET
• Update notification and automatically upgrade the ThinkUp to newer version without the need to touch the source » NOT YET
• Unit tests for upgrade, update notification and auto upgrade NOT YET

ThinkUp’s Installer Overview

There are three classes related to ThinkUp Installer:
Gina: As per the code style guide, each class should be in its own file.
Dwi: Done

1. InstallerError in webapp/model/class.InstallerError.php. This class extends Exception to handle errors related to Installation process. There’s only one method defined on this class, it’s showError. This method must be called after error has been thrown and catched. Here’s a typical usage on how InstallerError::showError() should be used:
   

   try {
     Installer::$db->exec($query);
   } catch (InstallerError $e) {
     $e->showError();
   }

   Gina: Should InstallerError extend the PHP Exception class?
   Dwi: Absolutely yes.
2. Loader in webapp/model/class.Loader.php. A lazy loading approach to auto load classes on demand and remove a bunch of require_once calls. See
   Create project-wide class autoloader issue. Using the Loader is simply by adding one line:
   

   Loader::register();

   Now we can instantiate classes reside inside the /thinkup/webapp/model/ (and further version will add other class locations) without calling require_once to the class’s file.
   Gina: Let’s definitely move the Loader class into its own file and use it project-wide.
   Dwi: Done. The init.php now is clean enough from require_once calls.
3. Installer in webapp/model/class.Installer.php. This is the main class for installation process. This class implemented singleton pattern, so there’s only one instance of Installer being instantiated by calling Installer::getInstance(). To know how the install page uses Installer class see /thinkup/webapp/install/index.php and /thinkup/webapp/model/class.Loader.php. To know how the repair page uses Installer class see /thinkup/webapp/install/repair.php. Here’s an example on how install page uses the Installer class:
   

   define('DS', DIRECTORY_SEPARATOR);
   // Define absolute path to thinkup's directory
   define('THINKUP_ROOT_PATH', dirname(dirname(dirname(__FILE__))) . DS);
   // Define absolute path to thinkup's webapp directory
   define('THINKUP_WEBAPP_PATH', dirname(dirname(__FILE__)) . DS);
   // Define base URL, the same as $THINKUP_CFG['site_root_path']
   define('THINKUP_BASE_URL', substr($_SERVER['PHP_SELF'], 0, strpos( $_SERVER['PHP_SELF'], basename(dirname(__FILE__)))));
   require_once '../model/class.Installer.php';
   $installer = Installer::getInstance();
   ...

   Before using the Installer class, you must define three paths : THINKUP_ROOT_PATH, THINKUP_WEBAPP_PATH and THINKUP_BASE_URL. Then instantiate the Installer class by calling Installer::getInstance(). Why we need those three named constants? Because there’s case, install freshly, where a config.inc.php file is not available yet, so we can’t use global variable $THINKUP_CFG or Config’s class.

Installer uses Smarty to render the view. The caching is disabled on Installer (see Installer::getInstance ) . The view files for installer, repairer and upgrader pages will be named with installer.*.tpl convention, e.g., installation process on step 1 has a view named installer.step.1.tpl and repair page has a view named installer.repair.tpl. For more information of Installer files, see ThinkUp’s Installer Structure.

Gina: This class is so similar to SmartyThinkUp, let’s delete it, and overload the existing SmartyThinkUp constructor to take a $override_cache_setting parameter that defaults to false.
Dwi: Done.

The underlying works of ThinkUp Installer is much inspired by the famous WordPress “famous 5-minute install”. In fact, the Installer class borrows some Wordpress logic functions, e.g., Installer::examineQueries which is a modified wp’s dbDelta() function. But, the ThinkUp Installer is stick to OOP way rather than the procedural way and in the further version ThinkUp and its installer are going to support multiple databases by using PDO. To know how the installer works, consider the following cases:

1. Install ThinkUp from fresh source (either by using git clone or download from the archieves.
2. Repair ThinkUp from previous installed ThinkUp
3. Upgrade existing ThinkUp to newer version automatically
4. Upgrade existing ThinkUp to newer version manually

Install ThinkUp from fresh source either by using git clone or download from the archieves

Say you’ve downloaded ThinkUp source either by using git clone or download from the archives. And you’ve setup your development environment and ThinkUp is accessible via http://localhost/. This will execute the index.php located in /thinkup/webapp/index.php. The /thinkup/webapp/index.php will include /thinkup/webapp/init.php. The installation process begin on the execution of /thinkup/webapp/init.php. First, the init.php is defined three paths needed by the Installer class and then instantiate the Installer class. Then it will include /thinkup/webapp/model/class.Loader.php and calls Loader::register(). There’s nothing happened until a class is being instantiated. When a class is instantiated, a Loader::load($class) will handle file file inclusion for class $class. There are special classes that have different file name convention, class that reside inside other class’ file, interface and Config class. Loader class handles Config class differently. When a Config class is being instantiated, Loader will try to load an instance of Installer and include /thinkup/webapp/config.inc.php. If the /thinkup/webapp/config.inc.php file doesn’t exist, it will call Installer::diePage($message, 'Error') and the following error page will be shown:

Figure 1.1 Error page.

The diePage($message, $subtitle) method is a method to render a page when error on ThinkUp Installer occurs. In Figure 1.1, the error shown is triggered by a missing config.inc.php that happens when init.php tried to instantiate Config’s class. When “Start Installation!” button is clicked, we enter installation step #1 (requirements check).

Figure 1.2 Installation step #1 (requirements check).

Install pages (step 1 to 3) is located at /thinkup/webapp/install/index.php.The view rendered on install pages (step 1 to 3) are set by Installer::installPage($step) where $step being passed is an int type of a step context (1 to 3). From figure 1.2, we can see that every requirements are met and Installer is able to go to the next step. But whenever your environment is not meet Installer requirements, you wouldn’t able to go to next installation steps. Figure 1.3.a shows an error happens when Installer is not able using cURL and Figure 1.3.b shows an error happens when logs and template related path are not writeable by the webserver.

Figure 1.3.a Installation step #1 Error (cURL is not installed).

Figure 1.3.b Installation step #1 Error (logs and template related path are not writeable by the webserver).

When requirements are met, we’re ready to enter the next installation step (setup database and site configuration). Figure 1.4 shows installation step #2. In this step, we are asked to enter database informations (database name, user, password, host, socket, port and table_prefix) and site informations (site name, administration name and email and country). These informations will be set into configuration file (config.inc.php) and administration account in owners table.

Figure 1.4 Installation step #2 (setup database and site configuration).

After we filled the form and clicked the Next Stop » there may be some conditions happen. If you have just cloned or downloaded ThinkUp and your webserver is able to write config.inc.php into ThinkUp’s webapp directory, you will get something similiar with figure 1.5.a below. You will be shown your administration account.

Figure 1.5.a Installation step #3 (finish).

If your webserver is not able to write config.inc.php into ThinkUp’s webapp directory, you will get something similiar with figure 1.5.b below. Now you are required to create config.inc.php manually and then copy paste the configuration information shown in the textarea.

Figure 1.5.b Install error page (file configuration error)

If you’re trying to Install ThinkUp in an environment that already have ThinkUp with the same version installed you will get something similiar with figure 1.5.c below.

Figure 1.5.c Install error page (ThinkUp already installed)

Repair ThinkUp from previous installed ThinkUp

Installer class also provides repair functionalities. Right now, there are three types of repairs:

1. Repair database
2. Create admin user
3. Repair database and create admin user

If you have your ThinkUp accessible via http://localhost/thinkup, repair page can be visited by hitting http://localhost/thinkup/install/repair.php. Or, if you’re trying to install ThinkUp from already installed ThinkUp enviroment (see figure 1.5.c) you’ll find the repair’s link.
The repair page is looked like figure 2.1.b. But before visiting repair page you must define $THINKUP_CFG['repair'] = true; in config.inc.php (figure 2.1.a).

Figure 2.1.a Repairing Configuration Error

Figure 2.1.b Repairing

When you clicked the Repair database link (http://localhost/thinkup/install/repair.php?db=1), you’ll get a page like below (figure 2.2). The Installer::repairPage($params) method will check if $_GET['db'] is set or not, if it sets then execute the Installer::repairTables() method to check missing tables and INDEX KEY by calling Installer::populateTables(). After tables are complete, Installer::repairTables() will check every table by executing REPAIR TABLE query.
Depending on your table condition you’ll get a page after reparing looked like figure 2.3.a (tables are complete before repairing) or 2.3.b (there some missing tables and index).

Figure 2.2 Repairing Database (Attention)

Figure 2.3.a Repairing Database on Non-missing Table (Finish)

Figure 2.3.b Repairing Database on Missing Table and Index Key (Finish)

Repair page also can be used to create an admin user (see figure 2.4). The difference between register page at thinkup/webapp/session/register.php and repair page on create admin user is in the register ThinkUp doesn’t set the is_admin field to 1.

Figure 2.4 Repairing to Create Admin User

After creating admin user, you’ll be shown a page looked like figure 2.5.

Figure 2.5 Repairing to Create Admin User (Finish)

The last functionialties is a combination to repair database and create an admin user (figure 2.6).

Figure 2.6 Repairing Database and Create Admin User

After repairing database and creating an admin user you’ll be shown a page looked like figure 2.7.

Figure 2.7 Repairing Database and Create Admin User (Finish)

Upgrade existing ThinkUp to newer version automatically

In-progress

Upgrade existing ThinkUp to newer version manually

In-progress

ThinkUp’s Installer Structure

Files related to ThinkUp’s Installer.

ThinkUp’s What-must-be-updated on Each Release of ThinkUp

Document what files related on ThinkUp’s Installer that must be modified on each release of ThinkUp