source: trunk/docs/codebase_v1-to-v2_upgrade_checklist.txt

=====================================================================
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 equivalents. 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".

If the value used is now to be retrieved from a $object->getParam(...) method call, you'll need to do this:

    $object->getParam('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 other words, the URL should be a not-fully-qualified URL starting with a slash.)


// 5. Expect formatting inconsistencies! 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'
    ));


6. 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.



=====================================================================
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(...);  //call for each value in array
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();

The following regex will find any of the above:
(?<!raiseMsg|logMsg|include|ohref|printHiddenSession|dieURL|dieBoomerangURL|setBoomerangURL|getBoomerangURL|validBoomerangURL|deleteBoomerangURL|sslOn|sslOff)

Also convert all site config variables, as earlier:
$CFG->site_name                         $app->getParam('site_name')

=====================================================================
DB
=====================================================================

dbQuery(...)                            $db->query(...)
dbTableExists(...)                      $db->tableExists(...)
addslashes(...)                         $db->escapeString(...)

$dbh
$GLOBALS['dbh']                         $db->getDBH()

=====================================================================
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(array(...))            $nav->setParam(...)
$nav->getFeature(...)                   $nav->getParam(...)
$nav->getTitle()                        $nav->get('title')
$nav->printTitle()                      echo $nav->get('title')
$nav->getPath()                         $nav->get('path')
$nav->printPath()                       echo $nav->get('path')
$nav->printBreadcrumbs()                echo $nav->getBreadcrumbs()

$nav->path_delimiter                    $nav->getParam('path_delimiter')
NOTE: this applies to any object property that has been converted to a param.


=====================================================================
PEdit
=====================================================================

Massive changes. See Quinn.

=====================================================================
Prefs
=====================================================================

$prefs = new Prefs($dbh, $params)       $prefs = new Prefs('namespace')
NOTE: new instantiation interface

$prefs->setDefault(..., scope)                 $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;
    global $auth;
    $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')) {
        $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->get(...)
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 = 0666;        $file->setParam('dest_file_perms', 0666);
...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.

=====================================================================
FormValidator
=====================================================================

include_once 'form_error_header.ihtml';      $fv->printErrorMessages();