Alte PepperShop-Versionen mit UTF-8 betreiben (Datenbank und Dateien) - Stand: August 2009

Inhaltsverzeichnis

wichtig

Diese Anleitung betrifft nur alte PepperShop Versionen. Ab PepperShop v.5.0 wird UTF-8 bereits standardmässig verwendet. Wir empfehlen das Update auf eine neue Version und nicht das Durcharbeiten dieser Anleitung.

Diese Anleitung erhebt nicht den Anspruch auf Vollständigkeit und ist eine Auflistung an Arbeiten, welche in einem Testcase angefallen sind. Es gibt keine Funktionsgarantie! Ausserdem muss mit Einschränkungen in der Funktionalität gerechnet werden, sobald mit angebundenen Systemen kommuniziert wird, welche selbst UTF-8 encodierte Datenströme verwenden.

Wir können keinerlei Support für diese Anleitung geben!

Einführung

Der Impuls für die in diesem Dokument beschriebenen Schritte wurde dadurch gegeben, dass in einem Webshop Artikelnamen und Beschreibungen sowohl in Deutsch, als auch in Japanischer Sprache verwendet werden sollen. Dies ist zur Zeit (bis und mit Shopversion 2.6.0) nicht möglich, da die Dateien und die MySQL-Datenbank Latin1 verwenden, welche die japanischen Zeichen nicht unterstützen Wie schon beschrieben, betrifft das nur alte PepperShop Versionen - ab Shopversion 5.0 ist UTF-8 voll einsatzbereit und per default aktiviert - wir empfehlen ein Update.

Es ist möglich, in der Shopadministration oder im phpMyAdmin japanische Zeichen einzugeben, diese werden dann aber encodiert in der Datenbank abgelegt. Die shopseitige Ausgabe ist dann korrekt, die Artikel sind aber nicht durchsuchbar und das E-Mail für die Bestellbestätigung ist nicht lesbar - folglich führt nichts an einer kompletten Konvertierung vorbei.

Im Kundenforum wurde in folgendem Thread auch über die UTF-8 Umwandlung geschrieben: http://www.phpeppershop.com/sponsoren/forum/read.php?f=1&i=14169&t=14169.

Für ein zukünftiges PhPepperShop Releaese ist die komplette Umstellung der Shop-Distribution auf UTF-8 eingeplant, allerdings gibt es dazu noch keine Terminvorgaben.

Diese Anleitung richtet sich an versierte UNIX/Linux Server Administratoren / Webentwickler mit genügend Erfahrung im PHP-Umfeld und Zugriffsrechten auf den Server.

Voraussetzungungen Server

  • UNIX / Linux Server
  • Testumgebung: Der Server verwendete im Filesystem ISO-8859-1. Das verhalten in einer homogenen UTF-8-Umgebung ist nicht getestet.
  • Es muss mindestens MySQL 4.1 vorhanden sein!

Vorgehen für die Verwendung von UTF-8

2.1 Vorbereitungen im entpackten Release-Verzeichnis

Die Datei template/template_create.sql muss bearbeitet werden, damit die Datenbank mit UTF-8 angelegt wird. Wegen des Primary-Keys in der Tabelle shop_settings_new müssen die Feldlängen für die Spalten name und gruppe stark #D9002Buziert werden, da MySQL sonst folgendes reklamiert 'ERROR 1071 (42000) at line 642: Specified key was too long; max key length is 1000 bytes'. Dies scheint eine MySQL Eigenart zu sein und hat sehr wahrscheinlich damit zu tun, dass UTF-8 mehr als ein Byte pro Zeichen benötigt.

--alt--
 /*!40101 SET NAMES latin1 */;
--neu--
 /*!40101 SET NAMES utf8 */;

--alt--
CREATE DATABASE IF NOT EXISTS {shop_db}; # /* CHARACTER SET latin1 COLLATE latin1_general_ci */
--neu--
CREATE DATABASE IF NOT EXISTS {shop_db} CHARACTER SET utf8 COLLATE utf8_general_ci;

--alt--
CREATE TABLE IF NOT EXISTS shop_settings_new
(
    name VARCHAR(248) NOT NULL DEFAULT '',   #/* Auf 250 beschraenkt, weil MySQL Keys maximal  */
    gruppe VARCHAR(248) NOT NULL DEFAULT '', #/* 500 Zeichen lang sein duerfen (name + gruppe) */
    wert TEXT NOT NULL DEFAULT '',
    security ENUM('user','admin') NOT NULL DEFAULT 'admin',
    PRIMARY KEY (name, gruppe)
);
--neu--
CREATE TABLE IF NOT EXISTS shop_settings_new
(
    name VARCHAR(100) NOT NULL DEFAULT '',   #/* Auf 250 beschraenkt, weil MySQL Keys maximal  */
    gruppe VARCHAR(50) NOT NULL DEFAULT '', #/* 500 Zeichen lang sein duerfen (name + gruppe) */
    wert TEXT NOT NULL DEFAULT '',
    security ENUM('user','admin') NOT NULL DEFAULT 'admin',
    PRIMARY KEY (name, gruppe)
);

--alt--
CREATE TABLE `bonitaet` (
  `provider` VARCHAR(150) NOT NULL DEFAULT '', # /* Laengenbeschraenkung da   */
  `gruppe` VARCHAR(100) NOT NULL DEFAULT '',   # /* MySQL-Keys maximal 500    */
  `name` VARCHAR(248) NOT NULL DEFAULT '',     # /* Zeichen lang sein duerfen */
  `wert` TEXT NOT NULL DEFAULT '',
  PRIMARY KEY  (`provider`,`gruppe`,`name`),
  INDEX `IDX_bonitaet_1` (`provider`),
  INDEX `IDX_bonitaet_2` (`gruppe`),
  INDEX `IDX_bonitaet_3` (`name`)
);

--neu--
CREATE TABLE `bonitaet` (
  `provider` VARCHAR(50) NOT NULL DEFAULT '', # /* Laengenbeschraenkung da   */
  `gruppe` VARCHAR(50) NOT NULL DEFAULT '',   # /* MySQL-Keys maximal 500    */
  `name` VARCHAR(50) NOT NULL DEFAULT '',     # /* Zeichen lang sein duerfen */
  `wert` TEXT NOT NULL DEFAULT '',
  PRIMARY KEY  (`provider`,`gruppe`,`name`),
  INDEX `IDX_bonitaet_1` (`provider`),
  INDEX `IDX_bonitaet_2` (`gruppe`),
  INDEX `IDX_bonitaet_3` (`name`)
);

Weiter muss auch die Datei templates/template_insert.sql angepasst werden:

--alt--
 /*!40101 SET NAMES latin1 */;
--neu--
 /*!40101 SET NAMES utf8 */;

2.2 Shop installieren

Der Shop kann jetzt installiert werden. Wenn alles geklappt hat, sieht man jetzt im phpMyAdmin, dass alle Tabellen als Kollation 'utf8_general_ci' verwenden.

Nach der Installation ausführen:

UPDATE locale SET CHARSET = 'UTF-8'

2.3 Charset (Zeichensatz) für Ausgaben anpassen

Die Zeichensätze müssen noch in der Datei {shop_verzeichnis}/shop/language/xy/localtext.inc.php angepasst werden. Falls der Shop mehrsprachig betrieben wird, alle localetext.inc.php Dateien anpassen!


--alt--
$locale_infos['charset']      = 'ISO-8859-1';   // Zeichensatz der Sprache HTML (Grossbuchstaben)
$locale_infos['charset_text'] = 'WINDOWS-1252'; // Zeichensatz der Sprache Text (Grossbuchstaben)
--neu--
$locale_infos['charset']      = 'utf-8';   // Zeichensatz der Sprache HTML (Grossbuchstaben)
$locale_infos['charset_text'] = 'utf-8'; // Zeichensatz der Sprache Text (Grossbuchstaben)

2.4 DB-Konnektierung auf UTF-8 einstellen

Die Datenbank läuft jetzt auf UTF-8 und die Ausgabe erfolgt auch damit, der MySQL-Client konnektiert die Datenbank aber noch nicht mit dem richtigen Zeichensatz. Im Datenbankwrapper muss noch eine kleine Anpassung gemacht werden ({shop_verzeichnis}/shop/database.php).

--alt--
     if (DIE_IF_DB_CONNECT_FAILS) {
        die($this->errMsg.$this->get_hints('connect_failed'));
    }
}
--neu-- auf Zeile 308 (nicht bei Sybase-Abschnitt einfügen!)
     if (DIE_IF_DB_CONNECT_FAILS) {
        die($this->errMsg.$this->get_hints('connect_failed'));
    }
}
// XXX> UTF-8 Patch
mysql_query("SET CHARACTER SET 'utf8'",$this->myConnectionHandle);
mysql_query("SET NAMES 'utf8'");
// <XXX

2.5 Ausgaben von htmlentities und htmlspecialchars

Die beiden Funktionen htmlentities und htmlspecialchars gehen default-mässig von IS0-8859-1 Daten aus. Jeder einzelne Aufruf dieser Funktionen im Shop muss folgendermassen ergänzt werden. Den Effekt sieht man am besten in Variationen mit Sonderzeichen sowie bei der Ausgabe von 'Stück'.

Am einfachsten ist es, je eine Wrapperfunktion für die beiden Funktion in util.php zu plazieren und alle Aufrufe von htmlentities und htmlspecialchars durch diese Wrapperfunktion zu ersetzen.

Mit folgenden UNIX-Shell-Aufrufen (im Webshop-Rootverzeichnis ausführen) können alle htmlentities- und htmlspecialchars-Aufrufe durch die Wrapperfunktion ersetzt werden.

fgrep -ril 'htmlentities(' * | xargs perl -pi -e 's/htmlentities\(/htmlent\(/g';
fgrep -ril 'htmlspecialchars(' * | xargs perl -pi -e 's/htmlspecialchars\(/htmlspez\(/g';

In der Datei {shop_verzeichnis}/shop/util.php werden dann folgende Wrapperfunktionen eingefügt (erst nach dem Ersetzen!)

// XXX> UTF-8 Patch
// Wrapperfunktion fuer htmlentities, um UTF-8 Ausgabe vereinheitlicht zu steuern
function htmlent($arg){
    return htmlentities($arg,ENT_COMPAT,'utf-8');
}

// Wrapperfunktion fuer htmlspecialchars, um UTF-8 Ausgabe vereinheitlicht zu steuern
function htmlspez($arg){
    return htmlspecialchars($arg,ENT_COMPAT,'utf-8');
}
// <XXX

Achtung: Auch der im PhPepperShop verwendete HTML-WYSIWYG-Editor FCKeditor verwendet die PHP-Funktionen htmlentities und htmlspecialchars. Da dort das PhPepperShop util.php nicht included wird, müssen die zwei Funktionsdefinitionen auch in folgenden Dateien eingefügt werden.

shop/Admin/fckeditor/fckeditor_php4.php
shop/Admin/fckeditor/fckeditor_php5.php
shop/Admin/fckeditor/editor/filemanager/connectors/php/util.php
shop/Admin/fckeditor/editor/filemanager/connectors/php/basexml.php

Hier allerdings mit folgendem Code:

**** FOLGENDE ZWEI DEFINITIONEN AN DEN ANFANG DER DATEI KOPIEREN ****

// XXX> UTF-8 Patch
// Wrapperfunktion fuer htmlentities, um UTF-8 Ausgabe vereinheitlicht zu steuern
if (!function_exists('htmlent')) {
    function htmlent($arg){
        return htmlentities($arg,ENT_COMPAT,'utf-8');
    }
}

// Wrapperfunktion fuer htmlspecialchars, um UTF-8 Ausgabe vereinheitlicht zu steuern
if (!function_exists('htmlspez')) {
    function htmlspez($arg){
        return htmlspecialchars($arg,ENT_COMPAT,'utf-8');
    }
}
// <XXX

2.6 Collation Fix Script anpassen

Shop-Datenbank Collation Fixer auf UTF-8 fixen. Folgende Datei editieren: {shop_verzeichnis}/shop/Admin/shop_db_clean.php. Hier werden zwei Variablen definiert, welche angepasst werden müssen:

    $character_set         = 'utf8';
    $collation             = 'utf8_general_ci';

2.7 PHP-Dateien in UTF8 umwandeln

Die Umwandlung erfolgt am einfachsten mit iconv. iconv kann leider nicht ein file direkt umwandeln, sondern erstellt jedes mal ein neues File. Die Umwandlung erfolgt deshalb in den zwei Schritten umwandeln -> umbenennen. Zuerst werden alle php-Files umgewandelt und mit der Extension .utf8 versehen, danach werden die .utf8-Files wieder renamed.

  1. find . -type f -name "*.php" -exec iconv -f ISO-8859-1 -t UTF-8 {} -o {}.utf8 \;
  2. find . -type f -name "*.utf8" | sed 's/\(.*\).utf8/mv & \1/' | sh

Info: Erst jetzt, nach der Umwandlung sind auch die Datenbank SQL-Dateien konviertiert... nochmals neu einlesen!

2.8 Header im Administrationsbereich ändern

2.8.1 Allgemein

Im Administrationsbereich wird an vielen Stellen IS=-8859-1 als Charakterset ausgegeben. Diese Ausgaben müssen alle ersetzt werden. Dazu im Admin-Verzeichnis folgenden Einzeiler ausführen.

  • fgrep -ril 'charset=iso-8859-1' * | xargs perl -pi -e 's/charset\=iso\-8859\-1/charset\=utf\-8/gi';

2.8.2 Shopversion bis 2.5.2

Bis und mit der Shopversion 2.5.2 muss man noch den Template-Editor patchen, so dass dieser auch UTF-8 ausgibt, Datei: shop/Admin/shop_template_editor.php:

// XXX> UTF-8 Patch
function show_template_editor_header($title='Startseite / Footer bearbeiten', $charset='utf-8') {
    header('Content-type: text/html; charset=utf-8');
    // <XXX

Noch offene Probleme

  • Artikel, welche im Administrationsbereich bearbeitet werden und hebräische Zeichen enthalten, kommen nicht richtig in die Datenbank. Dies gilt für Artikelname und Artikelbeschreibung.
  • Kommunikation mit angebundenen Fremdsystemen (insbesondere Payment Service Provider und der Transaktions-Proxy) müssen auf UTF-8 Encodierung überprüft werden (utf8decode...).

---
fjo, 11.08.2009 (Upd. 13.10.2017)