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

<?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.)


5. 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'
    ));
    
    
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(...);
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.



?>