Docs For Class PEAR_PackageUpdate

[line 164]
The package allows a developer to add a few lines of code to

their existing packages and have the ability to update their package automatically. This auto-update ability allows users to stay up to date much more easily than requiring them to update manually.

This package keeps track of user preferences such as "don't remind me again".

This package is designed to be a backend to different front ends written for this package. For example, this package can be used to drive a PHP-GTK 2, CLI or web front end. The API for this package should be flexible enough to allow any type of front end to be used and also to allow the package to be used directly in another package without a front end driver.

The interface for this package must allow for the following functionality:

allow user to confirm or cancel upgrade
download and install the package

don't ask again
don't ask until next release
only ask for state XXXX or higher

update channel automatically

PHP-GTK/CLI apps must exit to allow classes to reload
web front end could send headers to reload certain page

This class is simply a wrapper for PEAR classes that actually do the work.

EXAMPLE:

 <?php

  class Goo {
      function __construct()
      {
          // Check for updates...
          require_once 'PEAR/PackageUpdate.php';
          $ppu =& PEAR_PackageUpdate::factory('Gtk2', 'Goo', 'pear');
          if ($ppu !== false) {
              if ($ppu->checkUpdate()) {
                  // Use a dialog window to ask permission to update.
                  if ($ppu->presentUpdate()) {
                      if ($ppu->update()) {
                          // If the update succeeded, the application should
                          // be restarted.
                          $ppu->forceRestart();
                      }
                  }
              }
          }
          // ...
      }
      // ...
  }
 ?>

Author: Scott Mattocks
Version: Release: 0.5.1
Copyright: 2006 Scott Mattocks
Link: http://pear.php.net/package/PEAR_PackageUpdate
Since: Class available since Release 0.4.0a1
License: PHP License 3.01

__construct (Constructor) [line 252]

void __construct(
string
$packageName, string
$channel)

PHP 5 style constructor. Loads the user preferences.

Since: 0.4.0a1
Access: public

Parameters:

string	`$packageName`	—	The package to update.
string	`$channel`	—	The channel the package resides on.

[ Top ]

PEAR_PackageUpdate (Constructor) [line 238]

void PEAR_PackageUpdate(
string
$packageName, string
$channel)

PHP 4 style constructor. Calls the PHP 5 style constructor.

Since: 0.4.0a1
Access: public

Parameters:

string	`$packageName`	—	The package to update.
string	`$channel`	—	The channel the package resides on.

[ Top ]

checkUpdate [line 443]

boolean checkUpdate(
)

Checks to see if an update is available.

Respects the user preferences when determining if an update is avaiable. Returns true if an update is available and the user may want to update the package.

Return: true if an update is available.
Since: 0.4.0a1
Access: public

[ Top ]

determinePrefFile [line 417]

string determinePrefFile(
)

Returns the path to the preferences file.

Since: 0.4.0a1
Access: protected

[ Top ]

factory [line 296]

object An &factory(
string
$driver, string
$packageName, string
$channel)

Creates an instance of the given update class.

Return: instance of type PEAR_PackageUpdate_$driver
Throws: PEAR_PACKAGEUPDATE_ERROR_NONEXISTENTDRIVER
Since: 0.4.0a1
Access: public

Parameters:

string	`$driver`	—	The type of PPU to create.
string	`$packageName`	—	The package to update.
string	`$channel`	—	The channel the package resides on.

[ Top ]

forceRestart [line 947]

void forceRestart(
)

Redirects or exits to force the user to restart the application.

Abstract:
Since: 0.4.0a1
Access: public

[ Top ]

getPackageInfo [line 475]

boolean getPackageInfo(
)

Returns the latest information about the given package.

Return: true on success, false on error
Throws: PEAR_PACKAGEUPDATE_ERROR_NOPACKAGE, PEAR_PACKAGEUPDATE_ERROR_NOCHANNEL, PEAR_PACKAGEUPDATE_ERROR_NOINFO
Since: 0.4.0a1
Access: protected

[ Top ]

getPackagePreferences [line 553]

array getPackagePreferences(
)

Returns the preferences associated with the given package.

The preferences returned are an array with the folling values:

don't ask again
don't ask until next version
only ask for state x
bug/minor/major updates only

Since: 0.4.0a1
Access: public

[ Top ]

hasErrors [line 1083]

boolean hasErrors(
)

Returns whether or not errors have occurred (and been captured).

Since: 0.4.0a1
Access: public

[ Top ]

isIncludable [line 343]

boolean isIncludable(
string
$path)

Returns whether or not a path is in the include path.

Return: true if the path is in the include path.
Since: 0.4.2
Access: public

Parameters:

string $path —

[ Top ]

loadPreferences [line 372]

boolean loadPreferences(
)

Loads the user's preferences from a file.

The preferences are 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.

Return: true on success, false on error
Throws: PEAR_PACKAGEUPDATE_ERROR_PREFFILE_READACCESS, PEAR_PACKAGEUPDATE_ERROR_PREFFILE_CORRUPTED
Since: 0.4.0a1
Access: protected

[ Top ]

popError [line 1071]

object A popError(
)

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.

Return: PEAR_Error instance or false if no errors exist.
Since: 0.4.0a1
Access: public

[ Top ]

preferencesAllowUpdate [line 623]

boolean preferencesAllowUpdate(
)

Returns whether or not the user's preferences will allow an update to take place.

The user's preferences may define restrictions such as:

don't update
don't ask until next version (remembers last version asked)
only ask for state XXXX or higher
minor or higher (no bug fix)
major only

Return: true if the preferences will allow an update for the latest version.
Since: 0.4.0a1
Access: public

[ Top ]

presentUpdate [line 961]

boolean presentUpdate(
)

Presents the user with the option to update.

Return: true if the user wants to update
Abstract:
Since: 0.4.0a1
Access: public

[ Top ]

pushError [line 996]

PEAR_Error|array|Exception pushError(
int
$code, [string
$level = 'error'], [array
$params = array()], [string
$msg = false], [array
$repackage = false], [array
$backtrace = false])

Pushes an error onto an error stack.

Return: if compatibility mode is on, a PEAR_Error is also thrown. If the class Exception exists, then one is returned.
Since: 0.4.0a1
Access: public

Parameters:

int	`$code`	—	Package-specific error code
string	`$level`	—	Error level. This is NOT spell-checked
array	`$params`	—	associative array of error parameters
string	`$msg`	—	Error message, or a portion of it if the message is to be generated
array	`$repackage`	—	If this error re-packages an error pushed by another package, place the array returned from pop() in this parameter
array	`$backtrace`	—	Protected parameter: use this to pass in the http://www.php.net/debug_backtrace that should be used to find error context

[ Top ]

releaseType [line 685]

string releaseType(
)

Returns the type of release. (bug|minor|major);

Since: 0.4.0a1
Access: protected

[ Top ]

repackagePEAR_Error [line 1028]

mixed repackagePEAR_Error(

&$error, object
$error)

Repackages PEAR_Errors for use with ErrorStack.

Return: The return from PEAR::ErrorStack::push()
Author: Ian Eure
Since: 0.4.0a1
Access: public

Parameters:

object	`$error`	—	A PEAR_Error
	`&$error`	—

[ Top ]

savePreferences [line 571]

boolean savePreferences(
)

Saves the current prefernces to the RC file.

Return: true on success, false on error
Throws: PEAR_PACKAGEUPDATE_ERROR_PREFFILE_WRITEACCESS, PEAR_PACKAGEUPDATE_ERROR_PREFFILE_WRITEERROR
Since: 0.4.0a1
Access: public

[ Top ]

setDontAskAgain [line 711]

boolean setDontAskAgain(
boolean
$dontAsk)

Sets the user's preference for asking about all updates for this package.

Return: true on success, false on failure
Since: 0.4.0a1
Access: public

Parameters:

boolean $dontAsk —

[ Top ]

setDontAskUntilNextRelease [line 730]

boolean setDontAskUntilNextRelease(
boolean
$nextrelease)

Sets the user's preference for asking about updates again until the next release.

Return: true on success, false on failure
Throws: PEAR_PACKAGEUPDATE_ERROR_NOINFO
Since: 0.4.0a1
Access: public

Parameters:

boolean $nextrelease —

[ Top ]

setMinimumReleaseType [line 757]

boolean setMinimumReleaseType(
string
$minType)

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

Return: true on success, false on failure
Throws: PEAR_PACKAGEUPDATE_ERROR_INVALIDTYPE
Since: 0.4.0a1
Access: public

Parameters:

string $minType — The minimum release type to allow.

[ Top ]

setMinimumState [line 783]

boolean setMinimumState(
string
$minState)

Sets the user's preference for asking about release states.

Return: true on success, false on failure
Throws: PEAR_PACKAGEUPDATE_ERROR_INVALIDSTATE
Since: 0.4.0a1
Access: public

Parameters:

string $minState — The minimum release state to allow.

[ Top ]

setPreference [line 814]

boolean setPreference(
integer
$pref, mixed
$value)

Sets the given preference to the given value.

Don't take any chances. Anytime a preference is set, the preferences are saved. We can't rely on the developer to call savePreferences.

Return: true if the preference was set and saved properly.
Throws: PEAR_PACKAGEUPDATE_ERROR_INVALIDPREF
Since: 0.4.0a1
Access: protected

Parameters:

integer	`$pref`	—	One of the preference constants.
mixed	`$value`	—	The value of the preference.

[ Top ]

setPreferences [line 854]

boolean setPreferences(
array
$preferences)

Sets all preferences at once.

Return: true if the preferences were set and saved.
Since: 0.4.0a1
Access: public

Parameters:

array $preferences —

[ Top ]

update [line 898]

boolean update(
)

Updates the source for the package.

We have to update required dependencies automatically to make sure that everything still works properly.

It is the developers responsibility to make sure the user is given the option to update any optional dependencies if needed. This can be done by creating a new instance of PEAR_PackageUpdate for the optional dependency.

Return: true if the update was successful.
Throws: PEAR_PACKAGEUPDATE_ERROR_NOTINSTALLED
Since: 0.4.0a1
Access: public

[ Top ]

Class: PEAR_PackageUpdate

Class Overview

Author(s):

Version:

Copyright:

Variables

Methods

Inherited Variables

Inherited Methods

Class Details

Class Variables

$channel =

$errors =

$info = array()

$instVersion =

$latestVersion =

$packageName =

$preferences = array()

Method Detail

__construct (Constructor) [line 252]

Parameters:

PEAR_PackageUpdate (Constructor) [line 238]

Parameters:

checkUpdate [line 443]

determinePrefFile [line 417]

factory [line 296]

Parameters:

forceRestart [line 947]

getPackageInfo [line 475]

getPackagePreferences [line 553]

hasErrors [line 1083]

isIncludable [line 343]

Parameters:

loadPreferences [line 372]

popError [line 1071]

preferencesAllowUpdate [line 623]

presentUpdate [line 961]

pushError [line 996]

Parameters:

releaseType [line 685]

repackagePEAR_Error [line 1028]

Parameters:

savePreferences [line 571]

setDontAskAgain [line 711]

Parameters:

setDontAskUntilNextRelease [line 730]

Parameters:

setMinimumReleaseType [line 757]

Parameters:

setMinimumState [line 783]

Parameters:

setPreference [line 814]

Parameters:

setPreferences [line 854]

Parameters:

update [line 898]