From 379fffa19b6be036ea7b148abfa981782cbaabf6 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Mon, 3 Dec 2007 14:11:35 +0000 Subject: [PATCH] fixes #16 * all PHP code is documented * admin/scripts/*php is added to apidoc and gettext generation in Makefile --- Makefile | 1 + admin/i18n.inc.php | 45 +++++++++++++++++++++++++++++++++++++++--- admin/scripts/i18n.php | 3 ++- admin/shared.inc.php | 6 ++++++ admin/users.php | 9 +++++---- 5 files changed, 56 insertions(+), 8 deletions(-) diff --git a/Makefile b/Makefile index a363f0f..6ece213 100644 --- a/Makefile +++ b/Makefile @@ -26,6 +26,7 @@ VERSION := 0.2 PROJECT := davadmin SRCFILES := $(wildcard admin/*.php) +SRCFILES += $(wildcard admin/scripts/*.php) JSFILES := admin/scripts/autocomplete.js admin/scripts/directories.js \ admin/scripts/users.js APISRC := $(shell echo $(SRCFILES) | sed 's/ /,/g' ) diff --git a/admin/i18n.inc.php b/admin/i18n.inc.php index 0504ed8..94d44b3 100644 --- a/admin/i18n.inc.php +++ b/admin/i18n.inc.php @@ -1,6 +1,7 @@ * @version $Id$ @@ -28,7 +29,11 @@ */ /** - * Gets the language data. + * Gets the language data for supported languages. + * + * @return array associative array of language descriptions at index 0 + * and associative array of language to default country mappings at + * index 1 */ function get_language_data() { static $supportedLanguages = array(); @@ -48,6 +53,17 @@ function get_language_data() { return array($supportedLanguages, $defaultCountry); } +/** + * Sets the locale for the given LC_* constant in $category to $locale + * or a matching replacement. + * + * @param int $category one of the LC_* constants that PHP's setlocale + * function accepts + * @param string $locale locale name with or without country + * specification and with or without character set name + * @return string|boolean the locale actually set or FALSE if no + * locale could be set at all + */ function _setlocale($category, $locale) { if (($ret = setlocale($category, $locale)) !== false) { return $ret; @@ -77,10 +93,20 @@ function _setlocale($category, $locale) { return $ret; } } - echo "unable to select a valid locale code"; return false; } +/** + * Gets a supported language code. If $fallback is true en_US is + * returned as a last resort. + * + * @param string $code the language code which should be tested + * @param boolean $fallback if set to true (default) always return a + * valid language code + * @return string|boolean language code with country specification or + * false if $fallback is set to false and language code is not + * supported + */ function _get_supported_language_code($code, $fallback = true) { static $supportedLanguages; static $defaultCountry; @@ -107,6 +133,12 @@ function _get_supported_language_code($code, $fallback = true) { } } +/** + * Negotiate the locale based on the value of + * $_SERVER['HTTP_ACCEPT_LANGUAGE']. + * + * @return string language code string or null + */ function _http_negotiate_locale() { $accepted = $_SERVER['HTTP_ACCEPT_LANGUAGE']; if (!empty($accepted)) { @@ -120,15 +152,19 @@ function _http_negotiate_locale() { return null; } +// start the session session_start(); $project = "davadmin"; +// set the language based on a GET-Parameter. if (isset($_GET["language"])) { $languageCode = _get_supported_language_code($_GET["language"], false); if (isset($languageCode)) { $_SESSION["language"] = $languageCode; } } +// if the current session has a language use it, negotiate from +// HTTP-Header otherwise if ($_SESSION["language"]) { $language = $_SESSION["language"]; } else { @@ -138,11 +174,14 @@ if ($_SESSION["language"]) { putenv(sprintf("LANG=%s", $_SESSION["language"])); putenv(sprintf("LANGUAGE=%s", $_SESSION["language"])); $_SESSION["locale"] = _setlocale(LC_ALL, $_SESSION["language"]); +// bind text domain for normal code bindtextdomain($project, realpath(dirname(__FILE__) . DIRECTORY_SEPARATOR . ".." . DIRECTORY_SEPARATOR . "po")); +// bind text domain for JavaScript code bindtextdomain($project . "js", realpath(dirname(__FILE__) . DIRECTORY_SEPARATOR . ".." . DIRECTORY_SEPARATOR . "po")); +// set the default text domain to project name textdomain($project); ?> \ No newline at end of file diff --git a/admin/scripts/i18n.php b/admin/scripts/i18n.php index 83cbb27..c835875 100644 --- a/admin/scripts/i18n.php +++ b/admin/scripts/i18n.php @@ -5,7 +5,7 @@ * @author Jan Dittberner * @version $Id$ * @license GPL - * @package DAVAdmin + * @package DAVAdmin::JavaScript * * Copyright (c) 2007 Jan Dittberner * @@ -29,6 +29,7 @@ /** Include the internationalization code. */ require_once(".." . DIRECTORY_SEPARATOR . "i18n.inc.php"); + textdomain("davadminjs"); $translatable = file(realpath(implode(DIRECTORY_SEPARATOR, diff --git a/admin/shared.inc.php b/admin/shared.inc.php index 39d7c99..ef9f0d4 100644 --- a/admin/shared.inc.php +++ b/admin/shared.inc.php @@ -30,6 +30,12 @@ /** Include common internationalization code. */ require_once("i18n.inc.php"); +/** + * Create a server error with HTTP status code 500 and end script + * execution. + * + * @param string $message error message + */ function _server_error($message) { header('HTTP/1.0 500 Internal Server Error'); header('Status: 500 Internal Server Error'); diff --git a/admin/users.php b/admin/users.php index 2f00081..37aa714 100644 --- a/admin/users.php +++ b/admin/users.php @@ -34,7 +34,7 @@ include_once('common.inc.php'); * Gets the names of the given users's groups from the group file. * * @param string $username user name - * @return array of group names + * @return array array of group names * @access private */ function _getGroupNames($username) { @@ -57,7 +57,7 @@ function _getGroupNames($username) { * Gets XML encoded data for a user. * * @param int $uid user id - * @return XML string + * @return string XML string */ function getUserData($uid) { if (!(is_numeric($uid) && array_key_exists($uid, $GLOBALS['namemap']))) { @@ -77,7 +77,7 @@ function getUserData($uid) { * Gets XML encoded data for a deleted user. * * @param int $uid user id - * @return XML string + * @return string XML string */ function getDeletedUserData($uid) { if (!is_numeric($uid)) { @@ -92,7 +92,8 @@ function getDeletedUserData($uid) { * @param array &$userdata reference to an user data array * @param boolean $forinsert if this is true the check skips field * that will be created during insert - * @return an array with validation error messages or an empty array + * @return array an array with validation error messages or an empty + * array */ function validateUserData(&$userdata, $forinsert) { $errormsgs = array();