Index: trunk/docs/codebase_v1-to-v2_upgrade_checklist.txt
===================================================================
--- trunk/docs/codebase_v1-to-v2_upgrade_checklist.txt	(revision 236)
+++ trunk/docs/codebase_v1-to-v2_upgrade_checklist.txt	(revision 236)
@@ -0,0 +1,289 @@
+<?php 
+
+=====================================================================
+In General
+=====================================================================
+
+1. Include methods have changed. Instead of accessing file paths absolutely, all files are searched in the include_path. So, instead of:
+
+    include SITE_BASE . '/_templates/header.ihtml';
+    
+do this:
+
+    include 'header.ihtml';
+    
+
+2. CODE_BASE is a defunct constant. The location of the codebase is no longer important as long as it can be found in the currently configured include_path. This will usually include the local site directory (where the codebase normally would be found) as well as the server-wide /usr/lib/php directory where the codebase might be included for the whole server. So now, instead of this:
+
+    require_once CODE_BASE . '/lib/Utilities.inc.php';
+    
+do this:
+
+    require_once 'codebase/lib/Utilities.inc.php';
+    
+3. $CFG-> variables are gone. Most of these should be converted into their $app and $auth equivelents. If a $CFG variable is NOT something used by the codebase but is still needed by the website application, I suggest converting these values to a $cfg array. For example, this:
+
+    $CFG->gallery_images_url = '/gallery_images';
+    
+should become:
+
+    $cfg['gallery_images_url'] = '/gallery_images';
+    
+(And of course change the code where they are used to support the array instead of object-properties. If the array is inside of double-quotes it should be written like "{$cfg['gallery_images_url']}/my/path".)
+
+4. $CFG->site_url is not needed when referencing URLs. Change this:
+
+    <a href="<?php echo ohref("$CFG->site_url/my/file.php"); ?>">
+    
+to this:
+
+    <a href="<?php echo $app->ohref("/my/file.php"); ?>">
+    
+(In otherwords, the URL should be a not-fully-qualified URL starting with a slash.)
+    
+
+    
+
+=====================================================================
+App
+=====================================================================
+
+The _config.inc.php file is 99% different. Start over from scratch using codebase/docs/example_config.inc.php.
+
+---------------------------------------------------------------------
+$CFG global variables are converted to object properties specific to their usage.
+    
+For example:
+
+    $CFG->ssl_domain = 'www.example.com';
+    $CFG->login_timeout = 21600;
+
+are converted to:
+
+    $app->setParam(array(
+        'ssl_domain' => 'www.example.com'
+    ));
+    $auth->setParam(array(
+        'login_timeout'     => 21600,
+    ));
+
+---------------------------------------------------------------------
+Convert functions to methods.
+
+raiseMsg(...)                           $app->raiseMsg(...)
+logMsg(...)                             $app->logMsg(...)
+include 'message_header.ihtml';         $app->printRaisedMessages();
+$carry_queries = array(...);            $app->carryQuery(...);
+ohref(...)                              $app->ohref(...)
+printHiddenSession();                   $app->printHiddenSession();
+dieURL(...);                            $app->dieURL(...);
+dieBoomerangURL(...);                   $app->dieBoomerangURL(...);
+setBoomerangURL(...);                   $app->setBoomerangURL(...);
+getBoomerangURL(...);                   $app->getBoomerangURL(...);
+validBoomerangURL(...);                 $app->validBoomerangURL(...);
+deleteBoomerangURL(...);                $app->deleteBoomerangURL(...);
+sslOn();                                $app->sslOn();
+sslOff();                               $app->sslOff();
+
+
+=====================================================================
+DB
+===================================================================== 
+
+dbQuery(...)                            $db->query(...)
+dbTableExists(...)                      $db->tableExists(...)
+addslashes(...)                         $db->escapeString(...)
+
+
+=====================================================================
+Auth_SQL
+=====================================================================
+
+$auth->clearAuth()                      $auth->clear()
+$auth->setVal(...)                      $auth->set(...)
+$auth->getVal(...)                      $auth->get(...)
+$auth->setFeature(...)                  $auth->setParam(...)
+$auth->getFeature(...)                  $auth->getParam(...)
+
+
+=====================================================================
+ImageThumb
+=====================================================================
+
+$thumb->setSourceDirectory(...)         $thumb->setParam(array('source_dir' => ...))
+$thumb->createDestDirs(...)             $this->_createDestDirs(...) NOW PRIVATE!
+$thumb->validFileExtension(...)         $this->_validFileExtension(...) NOW PRIVATE!
+
+=====================================================================
+MySQLSessionHandler
+=====================================================================
+
+Renamed to DBSessionHandler.inc.php
+Interface totally changed. See example in App.inc.php.
+
+=====================================================================
+Navigation
+=====================================================================
+
+Renamed to Navigation.inc.php
+
+$nav->addPage(...)                      $nav->add(...)
+$nav->setFeature(...)                   $nav->set(...)
+$nav->getFeature(...)                   $nav->get(...)
+$nav->getTitle()                        $nav->get('title')
+$nav->printTitle()                      echo $nav->get('title')
+$nav->getPath()                         $nav->get('path')
+$nav->printPath()                       echo $nav->get('path')
+$nav->getBreadcrumbs()                  $nav->getBreadcrumbs()
+$nav->printBreadcrumbs()                echo $nav->getBreadcrumbs()
+
+=====================================================================
+PEdit
+=====================================================================
+
+Massive changes. See quinn.
+
+=====================================================================
+Prefs
+=====================================================================
+
+$prefs = new Prefs($dbh, $params)       $prefs = new Prefs('namespace')
+NOTE: new instantiation interface
+
+$prefs->setDefault(...)                 $prefs->setDefaults(array(...))
+NOTE: plurality - function need not be called once-per-default.
+
+$prefs->setValue(..., $scope)           $prefs->set(...)
+$prefs->getValue(..., $scope)           $prefs->get(...)
+$prefs->clearValue(..., $scope)         $prefs->delete(...)
+NOTE: $scope no longer used in the above methods.
+
+$prefs->retrieve()                      $prefs->load()
+
+=====================================================================
+Lock
+=====================================================================
+
+Renamed from RecordLock.inc.php to Lock.inc.php
+
+Only one major interface change: instead of calling $lock->dieErrorPage() you will wrap the header/footer includes around the method call $lock->printErrorHTML().
+
+Also, change instantiation call from:
+
+    $lock = new RecordLock($GLOBALS['_admin']);
+    
+to:
+
+    global $lock;
+    $lock =& Lock::getInstance($auth);
+     
+And instantiate the original global $lock object in _config.inc.php as follows:
+
+    // Global record-locking object.
+    $lock =& Lock::getInstance($auth);
+    $lock->setParam(array(
+        'timeout' => 0,
+        'auto_timeout' => 1800,
+        'error_url' => '/lock.php',
+    ));
+
+
+=====================================================================
+Version
+=====================================================================
+
+Renamed from RecordVersion.inc.php to Version.inc.php
+
+Change usage from:
+
+    $version = new RecordVersion();
+    
+to:
+
+    $version = Version::getInstance($auth);
+
+
+=====================================================================
+Cache
+=====================================================================
+
+Renamed from SessionCache.inc.php to Cache.inc.php
+
+Changed all method calls to now require object calls rather than static calls. In other words, change this:
+
+    if (SessionCache::isCached('mydata')) { 
+        $list = SessionCache::getCache('mydata');
+    }
+
+to:
+
+    if ($cache->exists('mydata')) {
+        $node_list = $cache->get('mydata');
+    }
+
+And have $cache instantiated in _config.inc.php like this:
+
+    // Global cache object.
+    $cache = new Cache('global');
+    $cache->setParam(array('enabled' => true));
+
+
+SessionCache::putCache($val, $key)      $cache->set($key, $val)
+NOTE: notice method arguments have been reversed.
+
+SessionCache::getCache(...)             $cache->set(...)
+SessionCache::isCached(...)             $cache->exists(...)
+SessionCache::breakCache(...)           $cache->delete(...)
+
+
+=====================================================================
+Upload
+=====================================================================
+
+Change all object properties from direct access to method-access:
+
+$file->allow_overwriting = true;        $file->setParam('allow_overwriting', true);
+$file->valid_file_extensions = true;        $file->setParam('valid_file_extensions', true);
+$file->$dest_file_perms = true;        $file->setParam('$dest_file_perms', true);
+...etc.
+
+$file->setUploadPath(...)               $file->setParam(array('upload_path' => ...))
+
+
+=====================================================================
+Utilities
+=====================================================================
+
+humanFileSize($size, $unit, $format)    humanFileSize($size, $format, $max_unit)
+NOTE: changed interface
+
+dbArrayToList(...)                      escapedList(...)
+NOTE: The functionality of this has changed, better check output is valid.
+
+
+=====================================================================
+HINTS
+=====================================================================
+
+1. Expect formatting incosistencies! When doing global search-replace expect whitespace to be erratic, variable names to change, and lines to be otherwise inconsistent. Here's a good example of a safe way to match a line:
+
+Searching for "$CFG->ssl_domain = 'www.example.com';":
+
+    $CFG->(\w+)\s*=\s*['"](\w+)['"];
+
+Replace:
+
+    $app->setParam(array(
+        '\1' => '\2'
+    ));
+    
+2. Many classes now require object-method calls, and the object must be globally scoped. For example, to call the $cache->exists() method inside a function, be sure to add:
+
+    global $cache;
+    
+at the top of the function.
+
+3. 
+
+
+?>
