Introduction to PEAR_PackageUpdate
About PEAR::PackageUpdate
PEAR::PackageUpdate gives other packages or applications the ability to automatically keep themselves up-to-date by checking their channel server for the latest release and self-updating with the user's permission. Auto-update features help developers by reducing the number of different versions of a package which are currently used. This reduces the likely hood of bugs related to outdated versions being reported.
This package automates the update process but still allows the user to remain in control of their computer. PEAR::PackageUpdate respects a user's preferences and allows the user to decide not only if the package should be updated but also when to be alerted to new updates. The user can decide to only be notified when a new release has a certain state or release type (bug fix, feature enhancement, or major version). The user can even turn off the updating features. All of these settings are on a package-by-package basis.
PEAR::PackageUpdate is designed to be a backend for other packages which provide different interface types. For example, this package can be used to drive a PHP-GTK 2, CLI or HTML frontend.
Usage Example
<?php
class Foo {
function __construct()
{
// Try to update the package if needed.
require_once 'PEAR/PackageUpdate.php';
// Load the PHP-GTK 2 driver to check for updates for pear://Foo
$ppu = PEAR_PackageUpdate::factory('Gtk2', 'Foo', 'pear');
// Check for trouble loading the driver.
if ($ppu !== false) {
// See if a new version is available (respects user prefs).
if ($ppu->checkUpdate()) {
// Ask for permission to update.
if ($ppu->presentUpdate()) {
if ($ppu->update()) {
// The update was a success. The app must be
// restarted.
$ppu->forceRestart();
}
}
}
}
// ...
}
// ...
}
?>
How to check warnings and/or errors
Rather than stop on first error/warning encountered, as it's done by other PHP4 PEAR packages, PEAR::PackageUpdate used the PEAR_ErrorStack for advanced error handling.
PEAR_ErrorStack implements error raising and handling using a stack pattern. So, to determine whether there are any errors on the stack, you should use the PEAR_PackageUpdate::hasErrors(). And to retrieve each error/warning, one by one, from the stack, you have to use the PEAR_PackageUpdate::popError().
See example below:
Usage of error levels with PEAR_PackageUpdate::hasErrors() is only available since version 0.7.0
<?php
class Foo {
function __construct()
{
// Try to update the package if needed.
require_once 'PEAR/PackageUpdate.php';
// Load the Cli driver to check for updates for pear://Foo
$ppu = PEAR_PackageUpdate::factory('Cli', 'Foo', 'pear');
// Check for trouble loading the driver.
if ($ppu !== false) {
// See if a new version is available (respects user prefs).
if ($ppu->checkUpdate()) {
// Ask for permission to update.
if ($ppu->presentUpdate()) {
if ($ppu->update()) {
// The update was a success. The app must be
// restarted.
$ppu->forceRestart();
} else {
// Error handling
if ($ppu->hasErrors('warning')) {
// Warning: specifying error levels is only allowed since version 0.7.0
// Retrieve only first warning, not all
$error = $ppu->popError();
echo "Warning occured when trying to update: pear/Foo package\n";
echo "Message: " . $error['message'] ."\n";
}
if ($ppu->hasErrors()) {
// Retrieve only first error, not all
$error = $ppu->popError();
echo "Error occured when trying to update: pear/Foo package\n";
echo "Message: " . $error['message'] ."\n";
if (isset($error['context']) {
// context is available
echo "*** Context: ***\n";
echo "File: " . $error['context']['file'] ."\n";
echo "Line: " . $error['context']['line'] ."\n";
echo "Function: " . $error['context']['function'] ."\n";
echo "Class: " . $error['context']['class'] ."\n";
}
exit();
}
}
}
}
}
// ...
}
// ...
}
?>