PEAR_PackageUpdate
[ class tree: PEAR_PackageUpdate ] [ index: PEAR_PackageUpdate ] [ all elements ]

Class: PEAR_PackageUpdate

Source Location: /PEAR_PackageUpdate-1.1.0RC1/PackageUpdate.php

Class Overview


The package allows a developer to add a few lines of code to


Author(s):

Version:

  • Release: 1.1.0RC1

Copyright:

  • 2006-2009 Scott Mattocks, Laurent Laville

Variables

Methods


Child classes:

PEAR_PackageUpdate_Cli
This is the default CLI driver for PEAR_PackageUpdate.

Inherited Variables

Inherited Methods


Class Details

[line 266]
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:

          1.  <?php
          2.   class Goo {
          3.       function __construct()
          4.       {
          5.           // Check for updates...
          6.           require_once 'PEAR/PackageUpdate.php';
          7.           $ppu =PEAR_PackageUpdate::factory('Gtk2''Goo''pear');
          8.           if ($ppu !== false{
          9.               if ($ppu->checkUpdate()) {
          10.                   // Use a dialog window to ask permission to update.
          11.                   if ($ppu->presentUpdate()) {
          12.                       if ($ppu->update()) {
          13.                           // If the update succeeded, the application should
          14.                           // be restarted.
          15.                           $ppu->forceRestart();
          16.                       }
          17.                   }
          18.               }
          19.           }
          20.           // ...
          21.       }
          22.       // ...
          23.   }
          24.  ?>



          [ Top ]


          Class Variables

          $adapters = array()

          [line 375]

          List of adapters used to communicate with package channels
          • Since: 1.1.0a1
          • Access: public

          Type:   array


          [ Top ]

          $channel =

          [line 320]

          The channel the package is hosted on.
          • Since: 0.4.0a1
          • Access: public

          Type:   string


          [ Top ]

          $errors =

          [line 366]

          A collection of errors that have occurred.
          • Since: 0.4.0a1
          • Access: public

          Type:   object


          [ Top ]

          $info = array()

          [line 338]

          Information about the latest version of the package.
          • Since: 0.4.0a1
          • Access: public

          Type:   array


          [ Top ]

          $instInfo =

          [line 357]

          Informations about the current installed version of the package.
          • See: PEAR_Registry::packageInfo()
          • Since: 0.6.0
          • Access: protected

          Type:   array


          [ Top ]

          $instVersion =

          [line 347]

          The current installed version of the package.
          • Since: 0.4.0a1
          • Access: public

          Type:   string


          [ Top ]

          $latestVersion =

          [line 329]

          The latest version available for the given package.
          • Since: 0.4.0a1
          • Access: public

          Type:   string


          [ Top ]

          $packageName =

          [line 311]

          The name of the package.
          • Since: 0.4.0a1
          • Access: public

          Type:   string


          [ Top ]

          $preferences = array()

          [line 275]

          The user's update preferences.
          • Since: 0.4.0a1
          • Access: public

          Type:   array


          [ Top ]

          $pref_file =

          [line 284]

          The file to read PPU user-defined options from
          • Since: 0.7.0
          • Access: public

          Type:   string


          [ Top ]

          $system_file =

          [line 302]

          The file to read PEAR system-wide defaults from
          • Since: 0.7.0
          • Access: public

          Type:   string


          [ Top ]

          $user_file =

          [line 293]

          The file to read PEAR user-defined options from
          • Since: 0.7.0
          • Access: public

          Type:   string


          [ Top ]



          Method Detail

          __construct (Constructor)   [line 417]

          void __construct( string $packageName, string $channel, [string $user_file = ''], [string $system_file = ''], [string $pref_file = ''])

          PHP 5 style constructor. Loads the user preferences.
          • Throws: PEAR_PACKAGEUPDATE_ERROR_INVALIDINIFILE
          • Since: version 0.4.0a1 (2006-03-28)
          • Access: public

          Parameters:

          string   $packageName     The package to update.
          string   $channel     The channel the package resides on.
          string   $user_file     (optional) file to read PEAR user-defined options from
          string   $system_file     (optional) file to read PEAR system-wide defaults from
          string   $pref_file     (optional) file to read PPU user-defined options from

          [ Top ]

          PEAR_PackageUpdate (Constructor)   [line 393]

          void PEAR_PackageUpdate( string $packageName, string $channel, [string $user_file = ''], [string $system_file = ''], [string $pref_file = ''])

          PHP 4 style constructor. Calls the PHP 5 style constructor.
          • Since: version 0.4.0a1 (2006-03-28)
          • Access: public

          Parameters:

          string   $packageName     The package to update.
          string   $channel     The channel the package resides on.
          string   $user_file     (optional) file to read PEAR user-defined options from
          string   $system_file     (optional) file to read PEAR system-wide defaults from
          string   $pref_file     (optional) file to read PPU user-defined options from

          [ Top ]

          addAdapter   [line 1439]

          bool addAdapter( string $adapter, int $priority)

          Add an interface adapter

          Add an interface adapter to communicate with remote server. API 1.0.x did not support adapters yet API 1.1.0 support only 3 adapters (REST, XmlRPC and Soap) IMPORTANT: Soap adapter is not provided

          • Throws: PEAR_PACKAGEUPDATE_ERROR_WRONGADAPTER
          • Since: version 1.1.0a1 (2009-02-28)
          • Access: public

          Parameters:

          string   $adapter     Name of the adapter to use for remote access
          int   $priority     Priority level of usage to this adapter (the hightest level is used first)

          [ Top ]

          checkUpdate   [line 661]

          boolean checkUpdate( )

          Checks to see if an update is available.

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

          • Return: true if an update is available.
          • Since: version 0.4.0a1 (2006-03-28)
          • Access: public

          [ Top ]

          determinePrefFile   [line 624]

          string determinePrefFile( )

          Returns the path to the preferences file.
          • Since: version 0.4.0a1 (2006-03-28)
          • Access: protected

          [ Top ]

          factory   [line 486]

          object An &factory( string $driver, string $packageName, string $channel, [string $user_file = ''], [string $system_file = ''], [string $pref_file = ''])

          Creates an instance of the given update class.
          • Return: instance of type PEAR_PackageUpdate_$driver
          • Since: version 0.4.0a1 (2006-03-28)
          • Throws: PEAR_PACKAGEUPDATE_ERROR_NONEXISTENTDRIVER
          • 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.
          string   $user_file     (optional) file to read PEAR user-defined options from
          string   $system_file     (optional) file to read PEAR system-wide defaults from
          string   $pref_file     (optional) file to read PPU user-defined options from

          [ Top ]

          forceRestart   [line 1273]

          void forceRestart( )

          Redirects or exits to force the user to restart the application.
          • Abstract:
          • Since: version 0.4.0a1 (2006-03-28)
          • Throws: PEAR_PACKAGEUPDATE_ERROR_INVALIDDRIVER
          • Access: public

          Overridden in child classes as:

          PEAR_PackageUpdate_Cli::forceRestart()
          Cli driver does not redirects or exits to force the user to restart the application.

          [ Top ]

          getInstalledRelease   [line 949]

          array|bool getInstalledRelease( )

          Returns informations about current installed version of the package
          • Return: false on error, data array otherwise
          • Author: Laurent Laville
          • Since: version 0.6.0 (2007-01-11)
          • Access: public

          [ Top ]

          getLatestRelease   [line 1014]

          array|bool getLatestRelease( )

          Returns information on latest version available
          • Return: false on error, data array otherwise
          • Author: Laurent Laville
          • Since: version 0.6.0 (2007-01-11)
          • Access: public

          [ Top ]

          getPackageInfo   [line 694]

          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 PEAR_PACKAGEUPDATE_ERROR_WRONGADAPTER
          • Since: version 0.4.0a1 (2006-03-28)
          • Access: protected

          [ Top ]

          getPackagePreferences   [line 783]

          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: version 0.4.0a1 (2006-03-28)
          • Access: public

          [ Top ]

          hasErrors   [line 1417]

          boolean hasErrors( [string|array $level = false])

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

          Parameters:

          string|array   $level     Level name. Use to determine if any errors of level (string), or levels (array) have been pushed

          [ Top ]

          isIncludable   [line 536]

          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: version 0.4.2 (2006-04-20)
          • Access: public

          Parameters:

          string   $path     Path to filename to check if includable

          [ Top ]

          loadPreferences   [line 568]

          boolean loadPreferences( [string $pref_file = ''])

          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, PEAR_PACKAGEUPDATE_ERROR_INVALIDINIFILE
          • Since: version 0.4.0a1 (2006-03-28)
          • Access: protected

          Parameters:

          string   $pref_file     (optional) file to read PPU user-defined options from

          [ Top ]

          popError   [line 1400]

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


          [ Top ]

          preferencesAllowUpdate   [line 859]

          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


          [ Top ]

          presentUpdate   [line 1289]

          boolean presentUpdate( )

          Presents the user with the option to update.
          • Return: true if the user wants to update
          • Abstract:
          • Since: version 0.4.0a1 (2006-03-28)
          • Throws: PEAR_PACKAGEUPDATE_ERROR_INVALIDDRIVER
          • Access: public

          Overridden in child classes as:

          PEAR_PackageUpdate_Cli::presentUpdate()
          Cli driver does not present any frontend when an update is needed

          [ Top ]

          pushError   [line 1326]

          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.

          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: if compatibility mode is on, a PEAR_Error is also thrown. If the class Exception exists, then one is returned.
          • Since: version 0.4.0a1 (2006-03-28)
          • 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 924]

          string releaseType( )

          Returns the type of release. (bug|minor|major);
          • Since: version 0.4.0a1 (2006-03-28)
          • Access: protected

          [ Top ]

          repackagePEARError   [line 1357]

          mixed repackagePEARError( object &$error)

          Repackages PEAR_Errors for use with ErrorStack.
          • Return: The return from PEAR::ErrorStack::push()
          • Author: Ian Eure <ieure@php.net>
          • Since: version 0.4.0a1 (2006-03-28)
          • Access: public

          Parameters:

          object   &$error     A PEAR_Error

          [ Top ]

          savePreferences   [line 804]

          boolean savePreferences( [string $pref_file = ''])

          Saves the current preferences to the RC file.
          • Return: true on success, false on error
          • See: PEAR_PackageUpdate::determinePrefFile()
          • Throws: PEAR_PACKAGEUPDATE_ERROR_PREFFILE_WRITEACCESS, PEAR_PACKAGEUPDATE_ERROR_PREFFILE_WRITEERROR
          • Since: version 0.4.0a1 (2006-03-28)
          • Access: public

          Parameters:

          string   $pref_file     (optional) file to save PPU user-defined options to

          [ Top ]

          setDontAskAgain   [line 1034]

          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: version 0.4.0a1 (2006-03-28)
          • Access: public

          Parameters:

          boolean   $dontAsk     User's preference for asking about all updates

          [ Top ]

          setDontAskUntilNextRelease   [line 1054]

          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: version 0.4.0a1 (2006-03-28)
          • Access: public

          Parameters:

          boolean   $nextrelease     User's preference for asking about updates again

          [ Top ]

          setMinimumReleaseType   [line 1082]

          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: version 0.4.0a1 (2006-03-28)
          • Access: public

          Parameters:

          string   $minType     The minimum release type to allow.

          [ Top ]

          setMinimumState   [line 1108]

          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: version 0.4.0a1 (2006-03-28)
          • Access: public

          Parameters:

          string   $minState     The minimum release state to allow.

          [ Top ]

          setPreference   [line 1140]

          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: version 0.4.0a1 (2006-03-28)
          • Access: protected

          Parameters:

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

          [ Top ]

          setPreferences   [line 1180]

          boolean setPreferences( array $preferences)

          Sets all preferences at once.
          • Return: true if the preferences were set and saved.
          • Since: version 0.4.0a1 (2006-03-28)
          • Access: public

          Parameters:

          array   $preferences     All user's preferences

          [ Top ]

          update   [line 1224]

          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: version 0.4.0a1 (2006-03-28)
          • Access: public

          [ Top ]


          Documentation generated on Thu, 07 May 2009 22:00:03 +0000 by phpDocumentor 1.4.2. PEAR Logo Copyright © PHP Group 2004.