0byt3m1n1

Path: /data/applications/aps/gallery/2.2-08/htdocs/modules/core/classes/ [ Home ]
File: GalleryRepositoryUtilities.class
<?php
/*
 * Gallery - a web based photo album viewer and editor
 * Copyright (C) 2000-2007 Bharat Mediratta
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at
 * your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA  02110-1301, USA.
 */

/**
 * Provides repository-related utility functions. Some of them are also used by repository tools.
 *
 * @package GalleryCore
 * @subpackage Classes
 * @author Jozef Selesi <selesi at gmail dot com>
 * @version $Revision: 16127 $
 */
class GalleryRepositoryUtilities {

    /**
     * Extracts the revision number from a string generated by CVS' Id tag.
     *
     * The pattern is one of:
     *  <DOLLAR>Id: it.po 13690 2006-05-19 18:01:46Z mindless <DOLLAR>
     *  <DOLLAR>Revision: 13690 <DOLLAR>
     *
     * @param string $string to exract revision from
     * @return array object GalleryStatus a status code
     *               string revision
     */
    function extractRevision($string) {
	if (preg_match('/Id: \S+ (\d+) \d.*/U', $string, $revision)) {
	    $revision = $revision[1];
	} else if (preg_match('/Revision: (\d+) /U', $string, $revision)) {
	    $revision = $revision[1];
	} else if (preg_match('/Id: \S+,v (.*?) .*/U', $string, $revision)) {
	    /* support 2.1.2 pre-svn strings.raw */
	    $revision = 10212;
	} else if (preg_match('/crc32 crc32/', $string)) {
	    /* support 2.1.2 pre-svn MANIFEST files*/
	    $revision = 10212;
	} else {
	    return array(GalleryCoreApi::error(ERROR_BAD_PARAMETER, __FILE__, __LINE__,
					      "No revision found in [$string]"),
			 null);
	}
	return array(null, $revision);
    }

    /**
     * Compares two specified versions and, optionally, build numbers (timestamps). Returns the
     * relation between the first and second specified versions.
     *
     * @param string $version1 first version (x[.y][.z][...])
     * @param string $version2 second version
     * @param int $build1 first build (yyyymmddhhmmss)
     * @param int $build2 second build
     * @return array object GalleryStatus a status code
     *		      string 'older', 'equal', 'newer'
     */
    function compareVersions($version1, $version2, $build1=null, $build2=null) {
	$relation = '';

	/* Compare versions if they're different. */
	if ($version1 != $version2) {
	    $relation = $this->compareRevisions($version1, $version2);
	}

	/* Compare builds if they're specified and if versions are identical. */
	if (!empty($build1) && !empty($build2) && empty($relation)) {
	    if ($build1 != $build2) {
		$relation = $build1 > $build2 ? 'newer' : 'older';
	    }
	}

	/* If no differences have been found, versions/builds are equal. */
	if (empty($relation)) {
	    $relation = 'equal';
	}

	return array(null, $relation);
    }

    /**
     * Compares two specified revisions.
     *
     * @param string $revision1 first revision (x[.y][.z][...])
     * @param string $revision2 second revision
     * @return string 'equal', 'older' or 'newer'
     */
    function compareRevisions($revision1, $revision2) {
	if ($revision1 == $revision2) {
	    return 'equal';
	}

	$revision1 = explode('.', $revision1);
	$revision2 = explode('.', $revision2);

	$subRevisions = count($revision1) > count($revision2) ? count($revision1)
							      : count($revision2);
	for ($i = 0; $i < $subRevisions; $i ++) {
	    if (!isset($revision2[$i])) {
		$relation = 'newer';
		break;
	    }
	    if (!isset($revision1[$i])) {
		$relation = 'older';
		break;
	    }
	    if ($revision1[$i] != $revision2[$i]) {
		$relation = $revision1[$i] > $revision2[$i] ? 'newer' : 'older';
		break;
	    }
	}
	return $relation;
    }

    /**
     * Reads specified number of bytes from the file's beginning.
     *
     * @param string $path file path
     * @param int $bytes bytes to read
     * @return array object GalleryStatus a status code
     *               string first line from file
     */
    function getFirstBytesFromFile($path, $bytes) {
	global $gallery;
	$platform =& $gallery->getPlatform();

	if ($file = $platform->fopen($path, 'r')) {
	    $data = $platform->fread($file, $bytes);
	    $platform->fclose($file);
	} else {
	    return array(GalleryCoreApi::error(ERROR_BAD_PARAMETER, __FILE__, __LINE__,
					      "Error reading file [$path]"),
			 '');
	}
	return array(null, $data);
    }

    /**
     * Reads the strings.raw revision of the specified plugin.
     *
     * @param string $pluginType
     * @param string $pluginId
     * @return array object GalleryStatus a status code
     *		     string strings.raw timestamp
     */
    function getLanguageBaseRevision($pluginType, $pluginId) {
	global $gallery;

	/* Make sure that strings.raw exists where we expect it. */
	$platform =& $gallery->getPlatform();
	$pluginBaseDir = GalleryCoreApi::getPluginBaseDir($pluginType, $pluginId, true);
	$pluginLanguageBasePath =
	    sprintf('%s%ss/%s/po/strings.raw', $pluginBaseDir, $pluginType, $pluginId);
	if (!$platform->file_exists($pluginLanguageBasePath)) {
	    return array(GalleryCoreApi::error(ERROR_BAD_PARAMETER, __FILE__, __LINE__,
					      "strings.raw not found [$pluginLanguageBasePath]"),
			 null);
	}

	/* Get the strings.raw file's first line which contains the timestamp. */
	list ($ret, $line) = $this->getFirstBytesFromFile($pluginLanguageBasePath, 128);
	if ($ret) {
	    return array($ret, null);
	}

	list ($ret, $revision) = $this->extractRevision($line);
	if ($ret) {
	    return array($ret, null);
	}

	return array(null, $revision);
    }

    /**
     * Determines whether the specified plugin is available in the local Gallery.
     *
     * @param string $pluginType
     * @param string $pluginId
     * @return array object GalleryStatus a status code
     *		     boolean availability
     */
    function isPluginAvailable($pluginType, $pluginId) {
	list ($ret, $plugins) = GalleryCoreApi::getAllPluginIds($pluginType);
	if ($ret) {
	    return array($ret, null);
	}

	$isAvailable = in_array($pluginId, $plugins);
	return array(null, $isAvailable);
    }

    /**
     * Checks plugin compatibility with a certain version of Gallery.
     *
     * Determines whether the specified plugin type's required APIs are compatible with specified
     * provided APIs. If provided APIs are omitted, currently installed API versions will be
     * used.
     *
     * @param string $pluginType
     * @param array $requiredCoreApi required core API version
     * @param array $requiredPluginApi required theme/module API version
     * @param array $providedApis provided core API versions
     *              ('core', 'module', 'theme' => array(Major, Minor))
     * @return boolean compatibility
     */
    function isPluginCompatible($pluginType, $requiredCoreApi, $requiredPluginApi,
	    $providedApis=null) {

	/*
	 * We must explicitly convert version numbers to integers because
	 * GalleryUtilities::isCompatibleWithApi only works with integers.
	 */
	$requiredCoreApi[0] = (int)$requiredCoreApi[0];
	$requiredCoreApi[1] = (int)$requiredCoreApi[1];
	$requiredPluginApi[0] = (int)$requiredPluginApi[0];
	$requiredPluginApi[1] = (int)$requiredPluginApi[1];

	/* If no provided core API versions were specified, get versions from installed core. */
	list ($providedCoreApi, $providedPluginApi) =
	    $this->getProvidedApis($pluginType, $providedApis);

	return (GalleryUtilities::isCompatibleWithApi($requiredCoreApi, $providedCoreApi)
	    && GalleryUtilities::isCompatibleWithApi($requiredPluginApi, $providedPluginApi));
    }

    /**
     * Returns the provided APIs relevant to the specified plugin type.
     *
     * If no provided APIs are specified, currently installed API versions will be used.
     *
     * @param string $pluginType
     * @param array $providedApis provided core API versions
     *              ('core', 'module', 'theme' => array(Major, Minor))
     * @return array array provided core API version
     *		     array provided plugin (based on its type) API version
     */
    function getProvidedApis($pluginType, $providedApis=null) {
	if (empty($providedApis)) {
	    $providedCoreApi = GalleryCoreApi::getApiVersion();
	    /*
	     * GalleryModule will be loaded, but GalleryTheme may not be, yet because this
	     * is typically called from controller code.
	     */
	    GalleryCoreApi::requireOnce('modules/core/classes/GalleryTheme.class');
	    $providedPluginApi = $pluginType == 'module' ? GalleryModule::getApiVersion()
							 : GalleryTheme::getApiVersion();
	} else {
	    $providedCoreApi[0] = (int)$providedApis['core'][0];
	    $providedCoreApi[1] = (int)$providedApis['core'][1];
	    $providedPluginApi[0] = $pluginType == 'module' ? (int)$providedApis['module'][0]
							    : (int)$providedApis['theme'][0];
	    $providedPluginApi[1] = $pluginType == 'module' ? (int)$providedApis['module'][1]
							    : (int)$providedApis['theme'][1];
	}

	return array($providedCoreApi, $providedPluginApi);
    }

    /**
     * Gets version and build information about the installed packages of the specified plugin.
     *
     * @param string $pluginType
     * @param string $pluginId
     * @return array object GalleryStatus a status code
     *		     array[$packageName] => array('version' => $version, 'build' => $build)
     */
    function getPluginPackages($pluginType, $pluginId) {
	if (empty($pluginType) || empty($pluginId)) {
	    return array(GalleryCoreApi::error(ERROR_BAD_PARAMETER, __FILE__, __LINE__,
					 "Missing plugin type [$pluginType] and/or ID [$pluginId]"),
			 null);
	}
	list ($ret, $searchResults) = GalleryCoreApi::getMapEntry('GalleryPluginPackageMap',
            array('locked', 'packageVersion', 'packageBuild', 'packageName'),
	    array('pluginType' => $pluginType, 'pluginId' => $pluginId));
	if ($ret) {
	    return array($ret, null);
	}

	$data = array();
	while ($result = $searchResults->nextResult()) {
	    $data[$result[3]] =
		array('locked' => $result[0], 'version' => $result[1], 'build' => $result[2]);
	}

	return array(null, $data);
    }

    /**
     * Returns the language description of the specified language-country code.
     * eg. en_US => English (US)
     *
     * @param string $languageCode
     * @return array object GalleryStatus a status code
     *		     string language description
     */
    function getLanguageDescription($languageCode) {
	global $gallery;
	$translator =& $gallery->getTranslator();

	list ($newLanguageCode, $languageData) =
	    $translator->getSupportedLanguageCode($languageCode, false);
	if (!$newLanguageCode) {
	    return array(GalleryCoreApi::error(ERROR_BAD_PARAMETER, __FILE__, __LINE__,
					       "Invalid language code specified [$languageCode]"),
			 null);
	}

	if (!isset($languageData['description'])) {
	    return array(GalleryCoreApi::error(ERROR_BAD_PARAMETER, __FILE__, __LINE__,
					       "Language not supported [{$language}_{$country}]"),
			 null);
	}

	return array(null, $languageData['description']);
    }

    /**
     * Returns the version of the specified plugin.
     *
     * @param string $pluginType
     * @param string $pluginId
     * @return array object GalleryStatus a status code
     *		     string version
     */
    function getPluginVersion($pluginType, $pluginId) {
	list ($ret, $plugin) = GalleryCoreApi::loadPlugin($pluginType, $pluginId, true);
	if ($ret) {
	    return array($ret, null);
	}

	return array(null, $plugin->getVersion());
    }

    /**
     * Downloads a file from the specified URL.
     *
     * It currently calls GalleryCoreApi::fetchWebPage to do all the work.  If the gzinflate()
     * function is available, then download the gzipped version of the file and unpack it locally
     * to save bandwidth.
     *
     * @param string $url url to download from
     * @param string $ignoreCompression don't try to get the compressed version of the file
     * @return array boolean file was successfully downloaded
     *		     string file contents
     */
    function downloadFile($url, $ignoreCompression=false) {
	global $gallery;

	$phpVm = $gallery->getPhpVm();
	$needsInflation = false;
	if (!$ignoreCompression && $phpVm->function_exists('gzinflate')) {
	    $url .= '.gz';
	    $needsInflation = true;
	}

	list ($successful, $contents, $response, $headers, $actualUrl) =
	    GalleryCoreApi::fetchWebPage($url);
	if (empty($contents) || !$successful) {
	    return array(false, null);
	}

	if ($needsInflation) {
	    $contents = $phpVm->gzinflate($contents);
	}
	return array(true, $contents);
    }
}
?>