|
@@ -1,49 +1,65 @@
|
|
|
<?php
|
|
|
-
|
|
|
-// File: multibyte_string_functions.lib.php
|
|
|
-// Main API extension for Dokeos 1.8.6 LMS
|
|
|
-// A common purpose library for supporting multibyte string aware functions.
|
|
|
-// License: GNU/GPL version 2 or later (Free Software Foundation)
|
|
|
-// Author: Ivan Tcholakov, ivantcholakov@gmail.com
|
|
|
-// October 2008.
|
|
|
-// May 2009 - refactoring and minor fixes have been implemented.
|
|
|
-
|
|
|
-
|
|
|
-// Notes:
|
|
|
-//
|
|
|
-// 1. For all the functions from this library witn optional encoding
|
|
|
-// parameters the system's encoding is assumed, i.e. the value that is
|
|
|
-// returned by api_get_setting('platform_charset') or the value of the
|
|
|
-// global variable $charset.
|
|
|
-//
|
|
|
-// 2. In other aspets, most of the functions in this library try to copy
|
|
|
-// behaviour of some core PHP functions and some functions from the
|
|
|
-// mbstring extension. Mostly they have similar names prefixed with "api_".
|
|
|
-// For your convenience, links have been given to the documentation of the
|
|
|
-// original PHP functions. Thus, you may exploit on your previous habits.
|
|
|
-//
|
|
|
-// 3. Why these function have been introduced? Because they are able to
|
|
|
-// support more encodings than the original ones. And which is more
|
|
|
-// important - they are UTF-8 aware. So, they should be used for strings
|
|
|
-// in natural language. For internal system identificators of file names
|
|
|
-// which are supposed to contain only English letters you may use the
|
|
|
-// original PHP string functions.
|
|
|
-//
|
|
|
-// 4. This library requires PHP mbstring extension to be activated.
|
|
|
-// When encodings to be used are not supported by mbstring, this library
|
|
|
-// is able to exploit the PHP iconv extesion, which in this case should
|
|
|
-// be activated too.
|
|
|
-
|
|
|
-
|
|
|
-//----------------------------------------------------------------------------
|
|
|
-// Multibyte string conversion functions
|
|
|
-//----------------------------------------------------------------------------
|
|
|
-
|
|
|
-
|
|
|
-// Converts character encoding of a given string.
|
|
|
-// See http://php.net/manual/en/function.mb-convert-encoding
|
|
|
-function api_convert_encoding($string, $to_encoding, $from_encoding) {
|
|
|
+/**
|
|
|
+ * ==============================================================================
|
|
|
+ * File: multibyte_string_functions.lib.php
|
|
|
+ * Main API extension library for Dokeos 1.8.6+ LMS
|
|
|
+ * A common purpose library for supporting multibyte string aware functions.
|
|
|
+ * License: GNU/GPL version 2 or later (Free Software Foundation)
|
|
|
+ * @author: Ivan Tcholakov, ivantcholakov@gmail.com
|
|
|
+ * October 2008 - initial implementation.
|
|
|
+ * May 2009 - refactoring and minor corrections have been implemented.
|
|
|
+ * @package dokeos.library
|
|
|
+ * ==============================================================================
|
|
|
+ */
|
|
|
+
|
|
|
+/**
|
|
|
+ * Notes:
|
|
|
+ *
|
|
|
+ * 1. For all the functions from this library witn optional encoding
|
|
|
+ * parameters the system's encoding is assumed, i.e. the value that is
|
|
|
+ * returned by api_get_setting('platform_charset') or the value of the
|
|
|
+ * global variable $charset.
|
|
|
+ *
|
|
|
+ * 2. In other aspects, most of the functions in this library try to copy
|
|
|
+ * behaviour of some core PHP functions and some functions from the
|
|
|
+ * mbstring extension. Mostly they have similar names prefixed with "api_".
|
|
|
+ * For your convenience, links have been given to the documentation of the
|
|
|
+ * original PHP functions. Thus, you may exploit on your previous habits.
|
|
|
+ *
|
|
|
+ * 3. Why these function have been introduced? Because they are able to
|
|
|
+ * support more encodings than the original ones. And which is more
|
|
|
+ * important - they are UTF-8 aware. So, they should be used for strings
|
|
|
+ * in natural language. For internal system identificators of file names
|
|
|
+ * which are supposed to contain only English letters you may use the
|
|
|
+ * original PHP string functions.
|
|
|
+ *
|
|
|
+ * 4. This library requires PHP mbstring extension to be activated.
|
|
|
+ * When encodings to be used are not supported by mbstring, this library
|
|
|
+ * is able to exploit the PHP iconv extesion, which in this case should
|
|
|
+ * be activated too.
|
|
|
+ */
|
|
|
+
|
|
|
+/**
|
|
|
+ * ----------------------------------------------------------------------------
|
|
|
+ * Multibyte string conversion functions
|
|
|
+ * ----------------------------------------------------------------------------
|
|
|
+ */
|
|
|
+
|
|
|
+/**
|
|
|
+ * Converts character encoding of a given string.
|
|
|
+ * @param string $string The string being converted.
|
|
|
+ * @param string $to_encoding The encoding that $string is being converted to.
|
|
|
+ * @param string $from_encoding The encoding that $string is being converted from. If it is omited, the platform character set is assumed.
|
|
|
+ * @return string Returns the converted string.
|
|
|
+ * This function is aimed to replace mb_convert_encoding() for human-language strings.
|
|
|
+ * @link http://php.net/manual/en/function.mb-convert-encoding
|
|
|
+ */
|
|
|
+function api_convert_encoding($string, $to_encoding, $from_encoding = null) {
|
|
|
+ if (empty($from_encoding)) {
|
|
|
+ $from_encoding = api_mb_internal_encoding();
|
|
|
+ }
|
|
|
if (api_equal_encodings($to_encoding, $from_encoding)) {
|
|
|
+ // When conversion is not needed, the string is returned directly, without validation.
|
|
|
return $string;
|
|
|
}
|
|
|
if (api_mb_supports($to_encoding) && api_mb_supports($from_encoding)) {
|
|
@@ -52,22 +68,74 @@ function api_convert_encoding($string, $to_encoding, $from_encoding) {
|
|
|
elseif (api_iconv_supports($to_encoding) && api_iconv_supports($from_encoding)) {
|
|
|
return @iconv($from_encoding, $to_encoding, $string);
|
|
|
}
|
|
|
+ // Here the function gives up.
|
|
|
return $string;
|
|
|
}
|
|
|
|
|
|
-// Converts a given string into UTF-8 encoded string.
|
|
|
-// See http://php.net/manual/en/function.utf8-encode
|
|
|
+/**
|
|
|
+ * Converts a given string into UTF-8 encoded string.
|
|
|
+ * @param string $string The string being converted.
|
|
|
+ * @param string $from_encoding The encoding that $string is being converted from. If it is omited, the platform character set is assumed.
|
|
|
+ * @return string Returns the converted string.
|
|
|
+ * This function is aimed to replace utf8_encode() for human-language strings.
|
|
|
+ * @link http://php.net/manual/en/function.utf8-encode
|
|
|
+ */
|
|
|
function api_utf8_encode($string, $from_encoding = null) {
|
|
|
- return api_convert_encoding($string, 'UTF-8', $from_encoding);
|
|
|
+ if (empty($from_encoding)) {
|
|
|
+ $from_encoding = api_mb_internal_encoding();
|
|
|
+ }
|
|
|
+ if (api_is_utf8($from_encoding)) {
|
|
|
+ // When conversion is not needed, the string is returned directly, without validation.
|
|
|
+ return $string;
|
|
|
+ }
|
|
|
+ if (api_mb_supports($from_encoding)) {
|
|
|
+ return @mb_convert_encoding($string, 'UTF-8', $from_encoding);
|
|
|
+ }
|
|
|
+ elseif (api_iconv_supports($from_encoding)) {
|
|
|
+ return @iconv($from_encoding, 'UTF-8', $string);
|
|
|
+ }
|
|
|
+ // Here the function gives up.
|
|
|
+ return $string;
|
|
|
}
|
|
|
|
|
|
-// Converts a given string, from UTF-8 encoding to a specified encoding.
|
|
|
-// See http://php.net/manual/en/function.utf8-decode
|
|
|
+/**
|
|
|
+ * Converts a given string from UTF-8 encoding to a specified encoding.
|
|
|
+ * @param string $string The string being converted.
|
|
|
+ * @param string $to_encoding The encoding that $string is being converted to. If it is omited, the platform character set is assumed.
|
|
|
+ * @return string Returns the converted string.
|
|
|
+ * This function is aimed to replace utf8_decode() for human-language strings.
|
|
|
+ * @link http://php.net/manual/en/function.utf8-decode
|
|
|
+ */
|
|
|
function api_utf8_decode($string, $to_encoding = null) {
|
|
|
- return api_convert_encoding($string, $to_encoding, 'UTF-8');
|
|
|
+ if (empty($to_encoding)) {
|
|
|
+ $to_encoding = api_mb_internal_encoding();
|
|
|
+ }
|
|
|
+ if (api_is_utf8($to_encoding)) {
|
|
|
+ // When conversion is not needed, the string is returned directly, without validation.
|
|
|
+ return $string;
|
|
|
+ }
|
|
|
+ if (api_mb_supports($to_encoding)) {
|
|
|
+ return @mb_convert_encoding($string, $to_encoding, 'UTF-8');
|
|
|
+ }
|
|
|
+ elseif (api_iconv_supports($to_encoding)) {
|
|
|
+ return @iconv('UTF-8', $to_encoding, $string);
|
|
|
+ }
|
|
|
+ // Here the function gives up.
|
|
|
+ return $string;
|
|
|
}
|
|
|
|
|
|
-// Encodes a given string into the system ecoding if this conversion has been detected as necessary.
|
|
|
+/**
|
|
|
+ * Converts a given string into the system ecoding (or platform character set).
|
|
|
+ * When $from encoding is omited on UTF-8 platforms then language dependent encoding
|
|
|
+ * is guessed/assumed. On non-UTF-8 platforms omited $from encoding is assumed as UTF-8.
|
|
|
+ * When the parameter $check_utf8_validity is true the function checks string's
|
|
|
+ * UTF-8 validity and decides whether to try to convert it or not.
|
|
|
+ * This function is useful for problem detection or making workarounds.
|
|
|
+ * @param string $string The string being converted.
|
|
|
+ * @param string $from_encoding The encoding that $string is being converted from. It is guessed when it is omited.
|
|
|
+ * @param bool $check_utf8_validity A flag for UTF-8 validity check as condition for making conversion.
|
|
|
+ * @return string Returns the converted string.
|
|
|
+ */
|
|
|
function api_to_system_encoding($string, $from_encoding = null, $check_utf8_validity = false) {
|
|
|
$charset = api_get_system_encoding();
|
|
|
if (empty($from_encoding)) {
|
|
@@ -95,8 +163,15 @@ function api_to_system_encoding($string, $from_encoding = null, $check_utf8_vali
|
|
|
return api_convert_encoding($string, $charset, $from_encoding);
|
|
|
}
|
|
|
|
|
|
-// Converts all applicable characters to HTML entities.
|
|
|
-// See http://php.net/manual/en/function.htmlentities
|
|
|
+/**
|
|
|
+ * Converts all applicable characters to HTML entities.
|
|
|
+ * @param string $string The input string.
|
|
|
+ * @param int $quote_style The quote style - ENT_COMPAT (default), ENT_QUOTES, ENT_NOQUOTES.
|
|
|
+ * @param string $encoding The encoding (of the input string) used in conversion. If it is omited, the platform character set is assumed.
|
|
|
+ * @return string Returns the converted string.
|
|
|
+ * This function is aimed to replace htmlentities() for human-language strings.
|
|
|
+ * @link http://php.net/manual/en/function.htmlentities
|
|
|
+ */
|
|
|
function api_htmlentities($string, $quote_style = ENT_COMPAT, $encoding = null) {
|
|
|
if (empty($encoding)) {
|
|
|
$encoding = api_mb_internal_encoding();
|
|
@@ -119,8 +194,15 @@ function api_htmlentities($string, $quote_style = ENT_COMPAT, $encoding = null)
|
|
|
return $string;
|
|
|
}
|
|
|
|
|
|
-// Decodes HTML entities into normal characters.
|
|
|
-// See http://php.net/html_entity_decode
|
|
|
+/**
|
|
|
+ * Convers HTML entities into normal characters.
|
|
|
+ * @param string $string The input string.
|
|
|
+ * @param int $quote_style The quote style - ENT_COMPAT (default), ENT_QUOTES, ENT_NOQUOTES.
|
|
|
+ * @param string $encoding The encoding (of the result) used in conversion. If it is omited, the platform character set is assumed.
|
|
|
+ * @return string Returns the converted string.
|
|
|
+ * This function is aimed to replace html_entity_decode() for human-language strings.
|
|
|
+ * @link http://php.net/html_entity_decode
|
|
|
+ */
|
|
|
function api_html_entity_decode($string, $quote_style = ENT_COMPAT, $encoding = null) {
|
|
|
if (empty($encoding)) {
|
|
|
$encoding = api_mb_internal_encoding();
|
|
@@ -134,12 +216,14 @@ function api_html_entity_decode($string, $quote_style = ENT_COMPAT, $encoding =
|
|
|
return api_utf8_decode(html_entity_decode(api_convert_encoding($string, 'UTF-8', $encoding), $quote_style, 'UTF-8'), $encoding);
|
|
|
}
|
|
|
|
|
|
-// This function encodes (conditionally) to UTF-8 a given string if XmlHttp-request has been detected.
|
|
|
+/**
|
|
|
+ * This function encodes (conditionally) a given string to UTF-8 if XmlHttp-request has been detected.
|
|
|
+ * @param string $string The string being converted.
|
|
|
+ * @param string $from_encoding The encoding that $string is being converted from. If it is omited, the platform character set is assumed.
|
|
|
+ * @return string Returns the converted string.
|
|
|
+ */
|
|
|
function api_xml_http_response_encode($string, $from_encoding = null) {
|
|
|
if (isset($_SERVER['HTTP_X_REQUESTED_WITH']) && strtolower($_SERVER['HTTP_X_REQUESTED_WITH']) == 'xmlhttprequest') {
|
|
|
- if (empty($from_encoding)) {
|
|
|
- $from_encoding = api_mb_internal_encoding();
|
|
|
- }
|
|
|
return api_convert_encoding($string, 'UTF-8', $from_encoding);
|
|
|
}
|
|
|
return $string;
|