PEAR Manual
Prev |  | Next

# XML-RPC functions

XML-RPC functions -- XML-RPC function API documentation

## What XML-RPC functions are available in a standard channel?

A standard PEAR channel should support this list of XML-RPC functions:

- logintest - a stub function

- package.getDownloadURL - retrieve a URL to download a package

- package.getDepDownloadURL - retrieve a URL to download a package dependency

- package.info - retrieve information on a package

- package.listAll - list all packages and verbose information on each package

- package.listLatestReleases - list all packages and their latest release versions

- package.search - search all packages for a match

Channels can also implement channel.listAll, but we recommend that this only be implemented by pear.php.net and pecl.php.net channels, as the command is utilized by the update-channels command to retrieve an official list of channels.

## logintest

The logintest xml-rpc function is called by the login command, and should return a boolean `TRUE`

## package.getDownloadURL

``false|struct package.getDownloadURL` (struct packageinfo [, string preferred_state = stable [, (v1.1) string installed_version = false]])`

false|struct `packageinfo`

  an array of format:

      array(
              'channel' => channel name,
              'package' => package name,
              ['version' => specific version to retrieve,]
              ['state' => specific state to retrieve,]
           )

  if both version and state are set, the version index should be ignored.

string `preferred_state = stable`

  The client-side preferred_state. This should be used to exclude releases that are too unstable.

string `installed_version = false`

  The current installed version of the package on the client-side. This will either be a version string, or false if the package is not installed. Use this to ensure that older versions are never returned (as defined by version_compare(possible_version, installed_version, "<")).

The package.getDownloadURL function should return an array with either two or three indices.

- "version" => version of the release returned

- "info" => the complete package.xml contents from the release

- "url" => a URL from which to download this release. If no releases exist that fit the constraints defined by preferred_state, installed_version, and the version/state indices of packageinfo, then do not return this index, and instead return the version and package.xml of the latest release.

  The url entry should NOT append .tgz or .tar, but should be something like "http://pear.php.net/get/PEAR-1.4.0" instead of "http://pear.php.net/get/PEAR-1.4.0.tgz"

Note that version 1.0 of package.getDownloadURL did not have the installed_version parameter. Version 1.1 of package.getDownloadURL does - that is the only difference between the two versions.

## package.getDepDownloadURL

``false|struct package.getDepDownloadURL` (string xsdversion, struct dependency, struct parentpackage [, string preferred_state = stable [, (v1.1) string installed_version = false]])`

string `xsdversion`

  This should be either '1.0' or '2.0', and should match the version attribute from the top-level <package version="X.0"> tag. This should be used to determine how to process the second parameter.

struct `dependency`

  if the first parameter xsdversion is '1.0', this should be an array of format:

      array(
              'name' => package name
              'type' => 'pkg' - anything else is an error
              'rel' => 'has', 'ge', 'le', 'lt', 'le', 'not', 'ne'
              ['version' => specific version to retrieve,]
           )

  if xsdversion is '2.0', this should be an array of format:

      array(
              'name' => package name
              'channel' => package channel - see notes below
              ['min' => minimum version (inclusive),]
              ['max' => maximum version (inclusive),]
              ['exclude' => single version to exclude (string),
                            or array of versions to exclude,]
           )

  Note that you must always verify that the channel matches your channel. If your channel server is not at pear.php.net or pecl.php.net, you must reject all xsdversion='1.0' requests, and all xsdversion='2.0' requests where the channel is not your channel.

struct `parentpackage`

  This is information on the parent package, and is an array of format:

      array(
              'channel' => channel name,
              'package' => package name,
              'version' => specific version to retrieve,
           )

string `preferred_state = stable`

  The client-side preferred_state. This should be used to exclude releases that are too unstable.

string `installed_version = false`

  The current installed version of the dependency on the client-side. This will either be a version string, or false if the package is not installed. Use this to ensure that older versions are never returned (as defined by version_compare(possible_version, installed_version, "<")).

Like package.getDownloadURL, package.getDepDownloadURL should return an array with either two or three indices.

- "version" => version of the release returned

- "info" => the complete package.xml contents from the release

- "url" => a URL from which to download this release. If no releases exist that fit the constraints defined by preferred_state, installed_version, and the version/state indices of packageinfo, then do not return this index, and instead return the version and package.xml of the latest release.

  The url entry should NOT append .tgz or .tar, but should be something like "http://pear.php.net/get/PEAR-1.4.0" instead of "http://pear.php.net/get/PEAR-1.4.0.tgz"

Note that version 1.0 of package.getDepDownloadURL did not have the installed_version parameter. Version 1.1 of package.getDepDownloadURL does - that is the only difference between the two versions.

## package.info

``false|struct package.info` (string package [, string field = null])`

string `package`

  Package name to retrieve information about

string `field = null`

  specific field to retrieve information about. If null, this should return an array with this indices, although others could be set as well:

      <?php
      array(
          'name' => 'package name',
          'category' => 'category name',
          'license' => 'package license',
          'summary' => 'package summary',
          'description' => 'package description',
          'releases' =>
          array( // all releases indexed by version
              '0.1' =>
              array(
                'license' => 'release license',
                'summary' => 'release summary',
                'description' => 'release description',
                'releasedate' => 'date of release',
                'releasenotes' => 'release notes',
                'state' => 'release stability',
                // the next index is optional
                'deps' =>
                array(
                  array( // release dependencies of latest release
                    'type' => 'dep type from package.xml <dep>',
                    'relation' => 'rel from package.xml <dep>',
                    'version' => 'version from package.xml <dep>, or empty string',
                    'name' => 'name from package.xml <dep>',
                    'optional' => 'yes or no',
                  ),
                  // and so on with all deps
                ),
              ),
              // and so on with all releases
              // releases should be ordered by releasedate DESC
          ),
      );
      ?>

  The second parameter, if set, must be one of these choices:

  - authors - a current list of package maintainers in format:

        <?php
        array(
            'handle1' =>
            array(
              'name' => 'Maintainer Name',
              'email' => 'maintainer@example.com',
              'role' => 'role from package.xml (lead, developer, contributor, helper)',
            ),
            'handle2' =>
            array(
              'name' => 'Maintainer Name 2',
              'email' => 'maintainer2@example.com',
              'role' => 'role from package.xml (lead, developer, contributor, helper)',
            ),
            // etc.
        );
        ?>

  - category - the category this package is in

  - description - the description of the latest release

  - license - package license of latest release

  - notes - release notes of the latest release

  - releases - an array of the format documented above, containing information on all releases

  - summary - summary from latest release

## package.listAll

``struct package.listAll` ([bool released_only = true [, bool stable_only = true]])`

bool `released_only = `TRUE``

  If `TRUE`, then packages that have no releases should not be returned in the listing of available packages

bool `stable_only = `TRUE``

  If `TRUE`, then packages that have no stable releases should not be returned in the listing of available packages

This function should return an array of this format for all packages that match the constraints defined above:

    array(
      array(
        'name' => 'packagename',
        'category' => 'category name',
        'license' => 'release license',
        'summary' => 'package summary',
        'description' => 'package description',
        'stable' => 'latest release version that matches constraints',
        'unstable' => 'latest unstable release version or false if stable_only',
        'state' => 'release state of latest release that matches constraints',
        'deps' =>
        array( // same format as for package.info
        )
      ),
      // etc.
    );

## package.listLatestReleases

``struct package.listLatestReleases` ([string state = ''])`

string `state = ''`

  If '', then the newest release will be returned for all packages. Otherwise, it must be one of 'snapshot', 'devel', 'alpha', 'beta', or 'stable', and the function should return the newest release that is more stable than state.

  If state is 'beta', then the function should return the latest release that is beta or stable. If state is 'devel', the function should return the latest release that is devel, alpha, beta, or stable, and so on.

This function should return an array of this format for all packages that have a release within the constraint defined by the "state" parameter:

    array(
      array(
        'package' => 'packagename',
        'version' => 'release version',
        'state' => 'release stability',
        'filesize' => 'size of the .tgz file to download',
      ),
      // etc.
    );

## package.search

``struct package.listAll` (string fragment [, string|bool summary = false [, bool released_only = true [, bool stable_only = true]]])`

string `fragment`

  A text fragment to use when searching for packages by name

string|bool `summary = `FALSE``

  If set to false, this should be ignored. Otherwise, this should be used to search through the summaries of packages that match the first parameter to limit the list of returned packages.

bool `released_only = `TRUE``

  If `TRUE`, then packages that have no releases should not be returned in the listing of available packages

bool `stable_only = `TRUE``

  If `TRUE`, then packages that have no stable releases should not be returned in the listing of available packages

This function should return an array of this format for all packages that match the constraints defined above:

    array(
      array(
        'name' => 'packagename',
        'category' => 'category name',
        'license' => 'release license',
        'summary' => 'package summary',
        'description' => 'package description',
        'stable' => 'latest release version that matches constraints',
        'unstable' => 'latest unstable release version or false if stable_only',
        'state' => 'release state of latest release that matches constraints',
        'deps' =>
        array( // same format as for package.info
        )
      ),
      // etc.
    );

Prev | Home | Next
channel.xml | Up | Custom File Roles