User Tools

Site Tools


en:dev:all:wb-adaption

This is an old revision of the document!


FIXME This page is not fully translated, yet. Please help completing the translation.
(remove this paragraph once the translation is finished)

General adjustment for Website Baker

Since WebsiteBaker existed before the appearance of the PHP FIG standards a few adjustments to the standards are required, which are described below. Further adjustments to adhere are included in the chapters on the individual WB versions / WB version groups!

Warning Caution: For all new Code the principle of electronic data processing, valid since the invention of the computer and which has often been disregarded in WB in the past, from now on has to be followed in WB as well:

  • Input » Processing » Output

These 3 areas must be strictly separated and always occur in the exact order. New modules that do not adhere to this basic rule are no longer included in future in the repository, or they are marked as 'not compatible'.

PHP File Formatting

General

For files with the extension *.php which include only PHP code or end with PHP code, the closing tag ?> is not allowed. It is not required by the web server nor by PHP and omitting it prevents from accidentally including blank lines which would may prematurely trigger that headers are sent.
If a file starts with PHP code, the opening <?php-tag must be placed on the first column of the first line of the file. Text files (not binary files such as images, etc.) must be saved in UTF-8 format without BOM (ByteOrderMark).
Particularly users of Windows environments have to be cautious about this, because usually for Unix / Linux UTF-8 is the system-wide standard anyway.

Indentation

The standard pitch of the tab should be set to 4 spaces. An indentation generally consists of 4 spaces. Tabs themselves are not allowed at any point and for convenience should be automatically converted by the editor each in 4 spaces.

Maximum Line Length

The target line length is 80 characters. Developers should keep each line of their code below 80 characters, as far as is possible and practicable. Nevertheless, longer lines are allowed in exceptional cases. However, the maximum length of a PHP code line should not exceed 130 characters.

Line termination

Line termination follows the Unix text file convention. Lines must end with a single linefeed (LF). Newline characters are represented by an ordinal 10, or 0x0A (hexadecimal).
:!: Note: Do not use the carriage return (CR / 0x0D) as in the conventions of Apple or the combination of carriage return and line feed (CR/LF / 0x0D, 0x0A) as specified in the standard for Windows.

Naming conventions

General

Website Baker largely adopts the PSR here as well, in a version slightly adapted to the specific requirements WB. The main difference is found in the structure of the search paths for the files. In later versions also here a further approximation to PSR will take place.

Note Note: Strict compliance with these conventions is imperative so that there can be no homonyms of classes and functions / methods in different modules. The core is thus able to clearly determine the location of the class file based on the class name to reload them using the autoloader optimized on WB. An explicit inclusion of the class files via include () or require () is superfluous.

Website Baker from v2.8.4 on requires PHP 5.4.x as a minimum requirement. For a transitional period 2 different naming conventions for classes are permitted. However, the stated objective is to convert entirely to namespaces to utilize their advantages and also to reduce the cost significantly when naming classes.

Classes

Class names must be declared in StudlyCaps (also called UpperCamelCase) and correspond to the following RegEx rule: '/[A-Z][a-zA-Z0-9]+/'. Numbers are permitted in class names, but should be limited to what is necessary and do not pose any risk of confusion with letters. If the class name consists of more than one word, the respective first letter of a word has to be in uppercase. Several consecutive uppercase letters are not allowed. Example based on a name:

Identifier Status
smtp_mailer wrong
Smtp_Mailer wrong
SMTPmailer wrong
SmtpMailer correct

Abstract classes and interfaces

In general, abstract classes and interfaces follow the same conventions as classes, with an additional rule: The names of abstract classes and interfaces should end with the term “Abstract” or “Interface”, and the term must not be preceded by an underscore. As an example Plugin_Abstract is considered invalid, but PluginAbstract or m_MyModul_PluginAbstract would be valid names.

Emulierte Namespaces

In diesem Modus ist in Klassennamen zusätzlich der Unterstrich '_' als Sonder-/Funktionszeichen gestattet. Er dient jedoch ausschließlich als Pfadseperator. Klassennamen bestehen hier nicht allein aus dem bis jetzt definierten Namen, sondern müssen zusätzlich noch genau definierte Präfixes enthalten. Nur dann ist es möglich, aus dem Klassennamen den exakten Dateinamen zu ermitteln, so dass die passende Datei bei einem Zugriff auf eine Klasse automatisch geladen(included) werden kann.

Die Klassenbibliotheken von WebsiteBaker sind in mehrere Gruppen aufgeteilt:
Klassen des Kerns: sind im Verzeichnis wb/framework/ oder einem seiner Unterverzeichnisse zu finden. Hierfür ist kein Prefix erforderlich.
Klassen der Module: Klassen der Module im jeweiligen Modulverzeichnis wb/modules/%modul_name%/ oder einem seiner Unterverzeichnisse. Der Bezeichner muss zwingend den Prefix 'm_' erhalten. Beispiel: m_MyModule_PluginInterface
Klassen des ACP: (AdminControlPanel ⇒ ehem. Backend) sind im Verzeichnis wb/admin/ oder einem seiner Unterverzeichnisse zu finden. Der KlassenBezeichner muss zwingend den Prefix 'a_' erhalten. Beispiel: a_Pages_PageTree
Klassen der third-party libraries: die im Verzeichniss wb/include/ sowie seinen Unterverzeichnissen liegen, werden vom Autoloader nicht automatisch erfasst. Jede Library hat jedoch die Möglichkeit, eine eigene Registrierung im SPL-Autoloaderstack vorzunehmen. Mehr dazu in der Beschreibung des Autoloaders der jeweiligen WB-Version.

Dateinamen

Soweit die vorgenannten Regeln für Klassennamen eingehalten wurden, ergeben sich die Dateinamen eindeutig aus den Klassennamen. Die Klasse m_MyModul_PluginAbstract findet sich demnach in der Datei wb/modules/MyModul/PluginAbstract.php.
Für alle anderen Dateien sind nur alphanummerische Zeichen und der Bindestrich (-) gestattet. Leerzeichen sind völlig verboten.
Jede Datei, die ausführbaren PHP Code enthält sollte mit der Endung .php enden und in UpperCamelCase-Schreibweise ausgeführt sein.

Verzeichnise

Zur Benennung von Verzeichnissen gelten die selben Grundlagen wie für Dateien. Es sind nur alphanummerische Zeichen sowie nur wenige Sonderzeichen des Standard 7-Bit-ASCII Bereiches <128 ( ! # - . @ ~ ) zulässig. Wie bei Dateinamen, sind Leerzeichen und der Unterstrich grundsätzlich verboten.

Funktionen und Methoden

Funktions- und Methodennamen dürfen nur Alphanummerische Zeichen enthalten. Unterstriche sind nicht gestattet. Nummern sind in Funktionsnamen gestattet aber in den meisten Fällen nicht empfohlen. Wortreichtum wird generell befürwortet. Funktionsnamen sollten so wortreich wie möglich sein um deren Zweck und Verhalten möglichst genau zu erklären.

Funktionen oder Methoden sollen möglichst immer in lowerCamelCase (oder einfach camelCase) geschrieben werden. Das bedeutet, mit einem klein geschriebenen Verb wie get, set, add, delete, load, save, execute etc. beginnen, das dann von einem Substantiv in StudlyCaps gefolgt werden kann, welches das zu bearbeitende Objekt beschreibt. Beispiel: <php> $oMyObject→saveItemList(); </php> oder <php> reloadAllModules(); </php>

:!: Achtung: Es dürfen niemals doppelte Unterstriche als Prefix für Methoden-, Funktions- oder Variablennamen verwendet werden. Es besteht hier die Gefahr, dass es zu Überschneidungen mit aktuellen oder zukünftigen, PHP-eigenen Magic-Functions etc. kommt.

en/dev/all/wb-adaption.1434211061.txt.gz · Last modified: 13.06.2015 15:57 by mrbaseman