Manual

Introduction to PEAR_PackageUpdate

Introduction to PEAR_PackageUpdate – A package to make adding self updating functionality to other packages or applications easy.

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();
                           }
                       }
                   }
               }
           }
           // ...
       }
       // ...
   }
   ?>

PEAR_PackageUpdate::factory

PEAR_PackageUpdate::factory – Factory method for creating PEAR_PackageUpdate frontend instances.

Synopsis

require_once 'PEAR/PackageUpdate.php';

mixed PEAR_PackageUpdate::factory ( string $driver , string $packageName , string $channel , string $user_file = '' , string $system_file = '' , string $pref_file = '' )

Description

Factory method for creating PEAR_PackageUpdate frontend instances.

Parameter

string $driver: The name of a frontend driver class. Must be one of Gtk2, Cli, or Web.

string $packageName: The name of the package to be updated. Example: PEAR_PackageFileManager_Web.

string $channel: The name of the channel $packageName is hosted on. This may be a fully qualified channel name such as pear.php.net or a short channel name like pear.

string $user_file: The path to the file to read PEAR user-defined options from.

string $system_file: The path to the file to read PEAR system-wide defaults from.

string $pref_file: The path to the file to read user's preferences from.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_NONEXISTENTDRIVER, when invalid driver name is used (i.e. Gtk2, Cli, Web).

Note

since 0.4.0a1

This function should be called statically.

Return value

mixed - reference to a new object or FALSE if the object could not be created (i.e. invalid driver name).

PEAR_PackageUpdate::isIncludable

PEAR_PackageUpdate::isIncludable – Determines whether or not a file is includable.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::isIncludable ( string $path )

Description

Determines whether or not a file is includable. This method is used to ensure that the driver class file can be found and included.

Parameter

string $path: The path to the file to check. The path should be a subdirectory of one of the directories in the include path.

Note

since 0.4.2

This function can be called statically.

Return value

boolean - TRUE if the file is includable, FALSE otherwise.

PEAR_PackageUpdate::loadPreferences

PEAR_PackageUpdate::loadPreferences – Loads the user's preferences from the preference file.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::loadPreferences ( string $pref_file = '' )

Description

Loads the user's preferences from the preference file.

If the user is on a Windows machine, the file will be in the PEAR_CONFIG_SYSCONFIG directory and named ppurc.ini. If the user is on any other operating system, the preferences file will be stored in the user's home directory as the file .ppurc. The file contains a serialized array of preferences for each package that has been checked for updates so far.

Since version 0.7.0, you could also choose another directory and name for your preference file. Use then the optional parameter $pref_file.

Parameter

string $pref_file: The path to the file to read user's preferences from.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_PREFFILE_READACCESS, when user's preference file has no READ access right.

throws PEAR_PACKAGEUPDATE_ERROR_PREFFILE_CORRUPTED, when user's preference file has invalid contents.

throws PEAR_PACKAGEUPDATE_ERROR_INVALIDINIFILE, when user's preference file given by parameter $pref_file does not exist.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preferences were loaded successfully, FALSE otherwise.

PEAR_PackageUpdate::determinePrefFile

PEAR_PackageUpdate::determinePrefFile – Returns the path to the preferences file.

Synopsis

require_once 'PEAR/PackageUpdate.php';

string PEAR_PackageUpdate::determinePrefFile ( )

Description

Returns the path to the preferences file.

The preferences file holds information about whether or not the user would like to be notified about updates for individual packages. If the user is on a Windows machine, the file will be in the PEAR_CONFIG_SYSCONFIG directory and named ppurc.ini. If the user is on any operating system, the preferences file will be stored in the user's home directory as the file .ppurc.

Note

since 0.4.0a1

This function can be called statically.

Return value

string - The full path to the preferences file.

PEAR_PackageUpdate::checkUpdate

PEAR_PackageUpdate::checkUpdate – Checks to see if an update is available and the user has asked not to be notified about the update.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::checkUpdate ( )

Description

Checks to see if an update is available and the user has asked not to be notified about the update.

This method takes the user's preferences in consideration when determining if an update is available. If a new bug fix release is available but the user has asked not to be notified until the next major release of the package, this method will return FALSE.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if an update is available and the user has asked to be notified about the update, FALSE otherwise.

PEAR_PackageUpdate::getPackageInfo

PEAR_PackageUpdate::getPackageInfo – Loads the latest package information from the channel server.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::getPackageInfo ( )

Description

Loads the latest package information from the channel server.

This method contacts the packages channel server using a PEAR_Remote instance. If any errors are encountered (channel server does not host the package, bad package name, etc.) they will be pushed onto the error stack.

Since version 0.5.2, protocol REST 1.0 is also supported. So we try to contact the packages channel server using a PEAR_REST instance, if this channel support the protocol, rather than default protocol XMLRPC.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_NOPACKAGE, if package name was set to empty.

throws PEAR_PACKAGEUPDATE_ERROR_NOCHANNEL, if channel was set to empty.

throws PEAR_PACKAGEUPDATE_ERROR_NOINFO, when there are no information available about the package name hosted on the channel server.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the information was retrieved successfully, FALSE otherwise. Errors will be pushed onto the error stack.

PEAR_PackageUpdate::getPackagePreferences

PEAR_PackageUpdate::getPackagePreferences – Returns the update preferences for the current package.

Synopsis

require_once 'PEAR/PackageUpdate.php';

array PEAR_PackageUpdate::getPackagePreferences ( )

Description

Returns an array of update preferences for the current package. This method is used to ensure that users are not asked about updates they do not want to be asked about.

The array returned may have up to four elements:

PEAR_PACKAGEUPDATE_PREF_NOUPDATES: if TRUE the user does not want to know about any new updates.

PEAR_PACKAGEUPDATE_PREF_NEXTRELEASE: if set, the user does not want to be asked until a version greater than the value of this element has been released.

PEAR_PACKAGEUPDATE_PREF_TYPE: if set, the user does not want to be notified unless the release is at least the given type (one of PEAR_PACKAGEUPDATE_TYPE_BUG, PEAR_PACKAGEUPDATE_TYPE_MINOR, PEAR_PACKAGEUPDATE_TYPE_MAJOR).

PEAR_PACKAGEUPDATE_PREF_STATE: if set, the user does not want to be notified unless the release has at least the given state (one of PEAR_PACKAGEUPDATE_PREF_STATE_DEVEL, PEAR_PACKAGEUPDATE_PREF_STATE_ALPHA, PEAR_PACKAGEUPDATE_PREF_STATE_BETA, PEAR_PACKAGEUPDATE_PREF_STATE_STABLE).

Note

since 0.4.0a1

This function can not be called statically.

Return value

array - an array of user preferences.

PEAR_PackageUpdate::savePreferences

PEAR_PackageUpdate::savePreferences – Saves the user preferences to the preference file.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::savePreferences ( string $pref_file = '' )

Description

Saves the user's preferences to the preference file.

Parameter

string $pref_file: The path to the file to save user's preferences to.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_PREFFILE_WRITEACCESS, when user's preference file has no WRITE access right.

throws PEAR_PACKAGEUPDATE_ERROR_PREFFILE_WRITEERROR, when an I/O error occured while writing user's preference file contents.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the user's preferences were saved successfully, FALSE othewise.

See

PEAR_PackageUpdate::determinePrefFile()

PEAR_PackageUpdate::preferencesAllowUpdate

PEAR_PackageUpdate::preferencesAllowUpdate – Checks whether or not the user's preferences allow an update to the latest version of the package.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::preferencesAllowUpdate ( )

Description

Checks whether or not the user's preferences allow an update to the latest version of the package. The user's preferences may define restrictions such as: don't update at all, don't update until a new version has been released (remembers the last version asked), only ask for certain states such as beta or stable, only ask for minor or higher version updates (no bug fixes), or only ask for major version updates.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the user's preferences allow an update for the latest version of the package, FALSE otherwise.

See

PEAR_PackageUpdate::getPackagePreferences()

PEAR_PackageUpdate::releaseType

PEAR_PackageUpdate::releaseType – Returns the release type of the most recent version of the package compared to the installed version.

Synopsis

require_once 'PEAR/PackageUpdate.php';

string PEAR_PackageUpdate::releaseType ( )

Description

Returns the release type of the most recent version of the package compared to the installed version. The result will be one of PEAR_PACKAGEUPDATE_TYPE_MAJOR, PEAR_PACKAGEUPDATE_TYPE_MINOR, or PEAR_PACKAGEUPDATE_TYPE_BUG.

This value is used to determine if the user's preferences allow an update for the current release.

Note

since 0.4.0a1

This function can not be called statically.

Return value

string - The release type (bug|minor|major).

PEAR_PackageUpdate::getInstalledRelease

PEAR_PackageUpdate::getInstalledRelease – Loads the latest package information from the current installation.

Synopsis

require_once 'PEAR/PackageUpdate.php';

mixed PEAR_PackageUpdate::getInstalledRelease ( )

Description

Loads the informations about current installed version of the package.

string version: The version of installed package name.

string license: The license this package is released under.

string summary: A short description about the package.

string description: A long description about the package.

string releasedate: The date of the release of the version installed.

string releasenotes: Description about changes on the package from previous release.

string state: The state of the package release installed (snapshot|devel|alpha|beta|stable).

array deps: The list of dependencies for this release of the package.

string xsdversion: The version of the XML package used to install this release (1.0 or 2.0).

string packagerversion: The version of the PEAR packager that was used to build this release.

Note

since 0.6.0

This function can not be called statically.

Return value

boolean - FALSE if the information was not available.

array - informations about the current installed version of the package (version, license, summary, description, releasedate, releasenotes, state, deps, xsdversion, packagerversion).

PEAR_PackageUpdate::getLatestRelease

PEAR_PackageUpdate::getLatestRelease – Loads the latest package information from the channel server.

Synopsis

require_once 'PEAR/PackageUpdate.php';

mixed PEAR_PackageUpdate::getLatestRelease ( )

Description

Loads the informations from the channel server.

string license: The license the latest package version is released under.

string summary: A short description about the package.

string description: A long description about the package.

string releasedate: The date of the latest release available from the channel server.

string releasenotes: Description about changes on the package from previous release.

string state: The state of the package release installed (snapshot|devel|alpha|beta|stable).

array deps: The list of dependencies for this release of the package.

string version: The version of the latest release available from the channel server.

Note

since 0.6.0

This function can not be called statically.

Return value

boolean - FALSE if the information was not available.

array - informations about the current installed version of the package (license, summary, description, releasedate, releasenotes, state, deps, version).

PEAR_PackageUpdate::setDontAskAgain

PEAR_PackageUpdate::setDontAskAgain – Sets the user's "Don't Ask Again" preference for the package.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setDontAskAgain ( boolean $dontAsk )

Description

Sets the user's "Don't Ask Again" preference to $dontAsk. If $dontAsk is TRUE the user will not be asked to update the package again.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preference was set properly, FALSE otherwise.

PEAR_PackageUpdate::setDontAskUntilNextRelease

PEAR_PackageUpdate::setDontAskUntilNextRelease – Sets the user's "Don't Ask Again Until Next Release" preference for the package.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setDontAskUntilNextRelease ( boolean $dontAsk )

Description

Sets the user's "Don't Ask Again Until Next Release" preference to $dontAsk. If $dontAsk is TRUE the user will not be asked to update the package again until a new version is released.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_NOINFO, when there are no information available about the package name hosted on the channel server.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preference was set properly, FALSE otherwise.

PEAR_PackageUpdate::setMinimumReleaseType

PEAR_PackageUpdate::setMinimumReleaseType – Sets the user's preference for asking about release types.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setMinimumReleaseType ( string $minType )

Description

Sets the user's preference for asking about minimum release types.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_INVALIDTYPE, when invalid type of release is used (bug|minor|major).

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preference was set properly, FALSE otherwise.

PEAR_PackageUpdate::setMinimumState

PEAR_PackageUpdate::setMinimumState – Sets the user's preference for asking about release states.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setMinimumState ( string $minState )

Description

Sets the user's preference for asking about minimum release state.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_INVALIDSTATE, when invalid state of release is used (snapshot|devel|alpha|beta|stable).

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preference was set properly, FALSE otherwise.

PEAR_PackageUpdate::setPreference

PEAR_PackageUpdate::setPreference – Sets the given preference to the given value.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setPreference ( string $pref , string $value )

Description

Sets one of the given preference to the given value. Both preference and value, should have valid values.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_INVALIDPREF, when invalid preference is used (PEAR_PACKAGEUPDATE_PREF_NOUPDATES, PEAR_PACKAGEUPDATE_PREF_NEXTRELEASE, PEAR_PACKAGEUPDATE_PREF_TYPE, PEAR_PACKAGEUPDATE_PREF_STATE).

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the preference was set properly, FALSE otherwise.

PEAR_PackageUpdate::setPreferences

PEAR_PackageUpdate::setPreferences – Sets all preferences at once.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::setPreferences ( array $preferences )

Description

Sets a group of preference with associated values, all at once. Invalid preference is ignored (no error raised).

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if all the preferences were set properly, FALSE otherwise.

PEAR_PackageUpdate::update

PEAR_PackageUpdate::update – Updates the source for the package.

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::update ( )

Description

Updates your current installation with the new source for the package.

Throws

throws PEAR_PACKAGEUPDATE_ERROR_NOTINSTALLED, if the package is not already installed.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if the update was successful, FALSE otherwise.

PEAR_PackageUpdate::popError

PEAR_PackageUpdate::popError – Pops an error off the error stack.

Synopsis

require_once 'PEAR/PackageUpdate.php';

array PEAR_PackageUpdate::popError ( )

Description

Pops an error off the error stack.

This method is just for collecting errors that occur while checking for updates and updating a package. The child class is responsible for displaying all errors and handling them properly. This is because the way errors are handled varies greatly depending on the driver used.

Note

since 0.4.0a1

This function can not be called statically.

Return value

array - details of an error or warning (with debug context if available).

See

PEAR_PackageUpdate::hasErrors()

PEAR_PackageUpdate::hasErrors

PEAR_PackageUpdate::hasErrors – Returns whether or not errors have occurred (and been captured).

Synopsis

require_once 'PEAR/PackageUpdate.php';

boolean PEAR_PackageUpdate::hasErrors ( mixed $level = false )

Description

Returns whether or not errors , and or, warnings (version 0.7.0 or better) have occurred.

Parameter

mixed $level: The level of errors to pop off of the stack (warning|error). Use FALSE if you want all errors and warnings at once.

Note

since 0.4.0a1

This function can not be called statically.

Return value

boolean - TRUE if errors(/warnings) have been captured, FALSE othewise.

See

PEAR_PackageUpdate::popError()