PSR-2: Coding Style Guide

Die PSR-2 Spezifikation beinhaltet Vorgaben zur Formatierung einer PHP-Datei. Sich an diese Richtlinien zu halten, ist vor allem dann sinnvoll, wenn man mit anderen Leute zusammen an einem Projekt arbeitet. Halten sich alle an die gleichen Stilvorgaben, verschwendet niemand Zeit, sich erst in fremden Code einzulesen.

1. Allgemeines

Die erste Voraussetzung ist, dass sich der Code ebenfalls an die Vorgaben der PSR-1 Spezifikationen hält, welche sich mit dem allgemeinen Programmierstil befasst.

Weitere Vorgaben sind:

  • Alle PHP-Dateien müssen den UNIX LF als Zeilenumbruch benutzen
  • Die Datei muss mit einer Leerzeile abschließen
  • Bei einer reinen PHP-Datei entfällt das schließende ?> Tag
  • Einrückungen bestehen aus 4 Leerzeichen
  • Keywords wie true, false und null werden klein geschrieben
  • Nach der öffnenden Klammer und vor der schließenden keine Leerzeichen
  • Befinden sich eine schließende Klammer und eine geschweifte öffnende Klammer in einer Zeile, so werden sie durch ein Leerzeichen getrennt
  • Bei Aufzählungen kommt vor dem Komma kein Leerzeichen, danach schon

Zeilen

  • Zeilen sollten nicht länger als 80 Zeichen sein
  • Sie dürfen nicht länger als 120 Zeichen sein
  • Keine Leerzeichen am Ende einer Zeile
  • Nicht mehr als ein Statement pro Zeile
  • Leerzeilen dürfen zum Zwecke der Übersichtlichkeit hinzugefügt werden

Namespaces und use-Deklarationen

  • Nach namespace-Deklarationen muss eine Leerzeile folgen
  • Alle use-Deklarationen stehen unterhalb der namespace-Deklaration
  • Pro use-Deklaration muss ein use-Keyword benutzt werden
  • Nach dem use-Block muss eine Leerzeile folgen
<?php
namespace Bereich\Package;
use EinInterface;
use IrgendeineKlasse as EineKlasse;
use AndererBereich\ZweitesPackage\MeineKlasse;
...

2. Klassen, Methoden und Attribute

  • abstract und final-Deklarationen stehen der Sichtbarkeit-Deklaration voran
  • Die static-Deklaration kommt nach der Sichtbarkeit
  • Beim Aufruf einer Funktion kommt kein Leerzeichen zwischen den Methoden- oder Funktionsnamen und der öffnenden Klammer

Extends und implements

  • Die Schlüsselwörter extends und implements müssen in der gleichen Zeile deklariert werden wie Klassenname
  • Die öffnende geschweifte Klammer kommt in eine eigene Zeile
  • Die schließende geschweifte Klammer kommt in die Zeile nach dem body
  • Eine Liste von implements kann in mehrere Zeilen geschrieben werden, dabei muss jedes Element in eine eigene Zeile geschrieben werden

Attribute

  • Bei allen Attributen muss die Sichtbarkeit angegeben werden
  • Das var-Keyword darf nicht zum Deklarieren von Attributen benutzt werden
  • Pro Statement darf nur ein Attribut deklariert werden
  • Keine Präfixe benutzen, die die Sichtbarkeit eines Attributs wiedergeben

Methoden

  • Bei allen Methoden muss die Sichtbarkeit angegeben werden
  • Keine Präfixe verwenden, die die Sichtbarkeit einer Methode anzeigen sollen
  • Nach dem Methodennamen kommt kein Leerzeichen, sondern sofort die öffnende Klammer
  • Nach der öffnenden Klammer und vor der schließenden kommt kein Leerzeichen
  • Die öffnende geschweifte Klammer kommt in eine eigene Zeile nach dem Methodennamen
  • Die schließende geschweifte Klammer kommt in die Zeile nach dem Body der Methode
  • Default-Argumente kommen ans Ende der Liste der Argumente
  • Eine Liste von Argumenten kann wie bei implements über mehrere Zeilen geschrieben werden, dabei gilt: jedes Argument kommt in eine eigene Zeile
class NeueKlasse extends EineKlasse implements EinInterface
{
 public function beispielFunktion($a, $b, $c = 2)
 {
  if ($a == $c) { 
   diesunddas();
  } elseif ($b == $c) { 
   diesundjenes($b);
  } else { 
   MeineKlasse::tudas($a, $b);
  }
 }

  final public static function irgendwas()
 {
  machwas();
 }
}

3. Kontrollstrukturen

  • Nach dem Kontrollstruktur-Schlüsselwort kommt ein Leerzeichen
  • Kein Leerzeichen nach der öffnenden und vor der schließenden Klammer
  • Zwischen der schließenden Klammer und der öffnenden geschweiften Klammer muss ein Leerzeichen sein
  • Der Körper der Kontrollstruktur muss einmal eingerückt sein
  • Die schließende Klammer steht in der Zeile nach dem body

if-else

  • Das else und das elseif befinden sich in der gleichen Zeile wie die geschweifte schließende Klammer des if-Körpers
  • elseif sollte statt else if genutzt werden

switch-case

  • Das case-Statement muss einmal eingerückt werden
  • Der case-body wird noch einmal eingerückt, das break-keyword befindet sich auf der gleichen Ebene wie der body
  • Wenn das break in einem nicht-leeren case weggelassen wird, muss ein Kommentar wie //no break eingefügt werden

4. Closures

  • Closures müssen mit einem Leerzeichen nach dem function-keyword und einem vor und nach dem use-keyword deklariert werden
  • Die öffnende geschweifte Klammer kommt in die gleiche Zeile wie die Deklaration
  • Die schließende geschweifte Klammer kommt in die Zeile nach dem body
  • Kein Leerzeichen nach der öffnenden Klammer oder der schließenden Klammer der Argumenten- Liste




Weitere Informationen sind auf der Seite http://www.php-fig.org/psr/psr-2/ von der PHP Framework Interop Group zu finden.

Erstellen einer Accelerated Mobile Pages (AMP) HTML-Seite

1. Was ist AMP?

AMP steht für „Accelerated Mobile Pages“ und ist ein Open-Source-Projekt, das von einigen Unternehmen ins Leben gerufen wurde. Das Ziel ist, Web-Inhalte, vor allem im Hinblick auf die mobile Entwicklung, möglichst schnell zu laden. AMP ist eine Möglichkeit Webseiten schneller zu laden und für mobile Geräte weiter zu optimieren. Vor allem für Blogbeiträge, Newsartikel, die oft mobil abgerufen werden, bietet sich diese Technik an. AMP besteht aus drei wesentlichen Teilen:

  • AMP HTML
  • AMP JS
  • Google AMP Cache

AMP HTML ist größtenteils reguläres HTML, das um ein paar spezifische Ausdrücke erweitert wurde. AMP JS ist eine JavaScript-Bibliothek, über die alle Lösungen zum schnelleren Laden einer Webseite implementiert sind. Auf eine eigene JavaScript-Datei muss allerdings verzichtet werden. Google wiederum bietet einen Cache, der für alle zugänglich ist und in den alle AMPs geladen werden. Dadurch sind die Seiten für andere Nutzer schneller verfügbar. Ein weiterer Vorteil von AMP besteht darin, dass diese von Google in den SERPs (Search Engine Result Pages) weiter oben stehen, da es ein Rankingfaktor ist.

2. Vorbereitung

Um seine Seite mit Hilfe von AMP zu optimieren, müssen zunächst ein paar Änderungen im Head der Seite vorgenommen werden. Im Folgenden ist der Grundaufbau einer AMP-Datei zu sehen:

<html amp lang="de"> 
<head>
<meta charset="utf-8"> <title>Hello, AMPs</title> <link rel="canonical" href="http://example.ampproject.org/article-metadata.html" />
<meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
<script type="application/ld+json"> { "@context": "http://schema.org", "@type": "NewsArticle", "headline": "Open-source framework for publishing content",
"datePublished": "2015-10-07T12:02:41Z", "image": [ "logo.jpg" ]    } </script>
<style amp-boilerplate> body { -webkit-animation:-amp-start 8s steps(1,end) 0s 1 normal both; -moz-animation:-amp-start 8s steps(1,end) 0s 1 normal both; -ms-animation:-amp-start 8s steps(1,end) 0s 1 normal both; animation:-amp-start 8s steps(1,end) 0s 1 normal both }
@-webkit-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}} @-moz-keyframe -amp-start{from{visibility:hidden}to{visibility:visible}} @-ms-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}
@-o-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}
@keyframes -amp-start{from{visibility:hidden}to{visibility:visible}} </style> <noscript> <style amp-boilerplate> body{ -webkit-animation:none; -moz-animation:none; -ms-animation:none;
animation:none } </style> </noscript>
<script async src="https://cdn.ampproject.org/v0.js"></script> </head>

<body> <h1>Dies ist bereits eine AMP Seite!</h1> </body>
</html>

Im Head-Bereich benötigte Angaben

  • Zunächst muss das Dokument mit der Doctype-Description beginnen: <!doctype html>
  • Das HTML-Tag muss wie folgt ergänzt werden: <html ⚡ > oder alternativ <html amp>, um dem Browser mitzuteilen, dass es sich hierbei um eine AMP-HTML Seite handelt.
  • Die <head> und <body> -Tags dürfen nicht weggelassen werden.
  • Im Head muss mit diesem Tag
    <link rel="canonical" href="$EINE_URL" />
    der Link zu der normalen HTML Version der Seite angegeben sein. Ist diese nicht vorhanden, so muss die HTML AMP Seite auf sich selbst verlinken.
  • Das erste Element des <head>-Tags muss die Zeichenkodierung enthalten:
    <meta charset="utf-8"><meta name="viewport" content="width=device-width,minimum-scale=1">
    muss vorhanden sein.
  • Für die AMP JS-Bibliothek muss das Tag
    <script async src="https://cdn.ampproject.org/v0.js"></script>
    als letztes Element des <head>-Tags enthalten sein. Das „async“ sorgt dafür, dass es asynchron geladen werden darf und so das onload-Event nicht verzögert
  • Ebenfalls darf auf das <style amp-boilerplate> Tag, wie oben angegeben, nicht verzichtet werden.

Alle übrigen Angaben, wie zum Beispiel die Schema.org Definition, sind für eine AMP HTML Seite optional. Um in anderen Diensten (z.B. Googles News) angezeigt zu werden, können diese benötigt werden.

Verbotene/Ersetzte Tags

Aus Performancegründen wurden einige HTML-Tags bei AMP HTML ersetzt und einige werden nicht unterstützt.


Nicht unterstützte Tags:

  • base
  • frame
  • frameset
  • object
  • param
  • applet
  • embed
  • form (Zukünftiger Support wurde bereits angekündigt)
  • input Elemente, textarea, select, option etc. (Davon ausgenommen ist das <button>-Tag)


Eingeschränkte Tags:

  • script (Nur erlaubt, um AMP Komponenten zu laden oder bei type="application/ld+json")
  • style (Ein zusätzliches Style Tag mit dem Attribut amp-custom ist im Head erlaubt)
  • link (rel-Attribute, die auf microformats.org registriert sind, sind erlaubt. Außerdem gibt es Ausnahmen, um benutzerdefinierte Fonts einzuladen)
  • meta (http-equiv-Attribut ist verboten)
  • svg
  • a (Der Wert des href Attributs darf nicht mit javascript: beginnen)


Ersetzte Tags:

  • img ⇒ amp-img
  • video ⇒ amp-video
  • audio ⇒ amp-audio
  • iframe ⇒ amp-iframe

Des Weiteren dürfen das style-Attribut, xml-Attribute sowie Attribute, die mit on beginnen (onclick, onmouseover etc.) nicht benutzt werden. Davon ausgenommen ist das on Attribut ohne Suffix.

3. AMP Elemente

Auf so gut wie jeder Webseite gibt es Bilder. Somit dürfte das wahrscheinlich wichtigste, weil meistbenutzte, AMP Element das <amp-img> Element sein. Anstatt das HTML eigene <img>-Tag zu benutzen, muss stattdessen die AMP Version dieses Tags benutzt werden.
Will man also ein Bild in seine Webseite einbauen, sähe das mit AMP zum Beispiel wie folgt aus:

<amp-img 
    src="pfad_zum_bild.jpg" 
    width=300 
    height=150 
    layout="responsive" >
</amp-img>

Das Attribut layout wird unter dem Punkt „Responsives Design“ erläutert.

Diese häufig benutzten AMP Elemente sind von Haus aus in der Standard-AMP-Bibliothek eingebaut. Erweiterte Komponenten müssen im Head des Dokuments eingeladen werden. Dazu später mehr.

Häufig benutzte Attribute

Um seine Seite AMP konform zu gestalten, sollten einem die Attribute layout, width, height, media, placeholder und fallback geläufig sein. Diese sind wichtig, um das Layout eines Elements zu definieren und diesem seinen Platz zu reservieren bevor andere Ressourcen wie JavaScript geladen wurden. layout Dieses Attribut bestimmt, wie sich das Element im Layout des Dokuments verhält. Die verschiedenen Werte für das Attribut werden unter dem Punkt „Responsives Design“ näher erläutert. Welche Werte das Attribut bei einem Element annehmen darf, steht in der Dokumentation des jeweiligen Elements.
width und height Je nachdem welchen Wert das Attribut layout eines Elements hat, müssen diese Werte gesetzt sein. Die Attribute müssen einen Integer Pixel Wert haben.
media Der Wert dieses Attributs ist ein media query. Immer wenn sich die Fenstergröße des Browser ändert, werden die Queries neu evaluiert und dementsprechend das Element angezeigt oder nicht.
placeholder Dieses Attribut kann nicht nur AMP Elementen, sondern jedem HTML Element zugewiesen werden. Ein Element, das dieses Attribut enthält, ist als Platzhalter seines Elternelements markiert. Es wird angezeigt, so lange die Ressourcen des Elternelements noch nicht geladen oder initialisiert werden konnten.
fallback Wie das placeholder Attribut kann auch dieses Attribut jedem HTML Element zugewiesen werden. Es dient dazu, dem Benutzer der Webseite mitzuteilen, wenn ein bestimmtes Element nicht angezeigt wird, weil es nicht den seinen Browser unterstützt wird.

Weitere Informationen zu den Attributen und Layout sind unter der AMP HTML Layout System Dokumentation zu finden.

Erweiterte Elemente

Erweiterte Elemente sind nicht im Standardumfang der AMP Bibliothek enthalten und müssen extra im Head eingeladen werden. Dabei handelt es sich um Elemente, die nicht so häufig gebraucht werden, wie zum Beispiel Bilder. Sie werden innerhalb eines <script>-Tags geladen:

<script async custom-element="amp-carousel" src="https://cdn.ampproject.org/v0/amp-carousel-0.1.js"></script>

Wichtig ist, dass die async– und custom-element-Attribute nicht weggelassen werden dürfen.
Eine Liste aller momentan zur Verfügung stehenden erweiterten Elemente ist hier zu finden. Zu jedem dieser Elemente gibt es eine Seite, auf der diese ausführlich beschrieben werden. Zu Beginn der Seite findet man eine kleine Übersicht, in der man unter anderem den zum Einladen nötigen <script>-Tag und einen Link zu einem Beispiel findet.

Unter ampbyexample.com sind alle AMP Elemente mit Beispielen aufgelistet. Diese Seite eignet sich gut, um einen Überblick über die Elemente und ihre Implementierung im eigenen Code zu bekommen.

4. AMP und CSS

Bei der Benutzung von CSS gibt es ein paar Einschränkungen, über die man Bescheid wissen sollte. Zunächst muss auf externe Stylesheets verzichtet werden. Ebenso muss man auf Inline Style Attribute verzichten und einige Styles sind aus Performancegründen tabu.

Die Styleangaben müssen im Head des Dokuments angelegt werden. Dabei sollte man darauf achten, dass dieser Bereich nicht zu groß wird: maximal 50000 Bytes sind erlaubt, um AMP konform zu bleiben. Muss es doch etwas mehr sein, so kann allerdings auf CSS-Präprozessoren, wie zum Beispiel Sass oder Less, zurückgegriffen werden.

Verbotene Styles

Inline Style Attribute Alle Styles müssen im <head> der Seite innerhalb eines <style amp-custom> Tags stehen.
! important Da dieses Element durch das AMP CSS selbst benutzt wird und wichtig für die Größenänderungen der Elemente ist, darf es nicht verwendet werden.
<link rel=“stylesheet“> Diese Formulierung ist nur zum Einbinden von benutzerdefinierten Fonts zulässig. Externe Stylesheets sind nicht erlaubt.
* (universeller Selektor) Der universelle Selektor darf nicht benutzt werden, da sich das negativ auf die Performance der Seite auswirken kann. Außerdem könnten dadurch andere Restriktionen umgangen werden.
:not() Dieses Element könnte dazu benutzt werden, den universellen Selektor zu simulieren.
Pseudoselektoren, Pseudoklassen, Pseudoelemente Diese sind nur in Verbindung mit Selektoren, die Tag-Namen enthalten erlaubt. Davon ausgeschlossen sind Tag-Namen, die mit amp- beginnen. Beispiele: a:hover, div:last-of-type sind erlaubt, amp-img:hover ist nicht zulässig.
-amp- Klassen und i-amp Tag-Namen Benutzerdefinierte Klassennamen dürfen nicht mit -amp- beginnen, da diese der AMP-Runtime vorbehalten sind. Im Style Bereich sollte deswegen darauf verzichtet werden, mit Selektoren auf -amp- Klassen und i-amp Tags zuzugreifen.
behavior, -moz-binding Diese Eigenschaften sind aus Sicherheitsgründen nicht erlaubt.
filter Filter dürfen aus Performancegründen nicht verwendet werden.

Transitions und Animations

Transitionen und Animationen sind nicht grundsätzlich verboten. Solche, die bei den üblichen Browsern durch die GPU unterstütz werden, sind generell zulässig. Momentan sind opacity, transform samt -vendor-Prefixes erlaubt. Bei der overflow Eigenschaft muss darauf geachtet werden, dass diese nicht als „auto“ oder „scroll“ gestylt werden darf. Außerdem darf kein benutzerdefiniertes Element eine Scrollbar aufweisen.

Benutzerdefinierte Fonts

Es gibt zwei Möglichkeiten, bei AMP Seiten benutzerdefinierte Fonts einzubinden. Zum einen ist es möglich, in einem link-Tag auf einen von AMP „weißgelisteten“ Anbieter zu verlinken. Zu diesen Anbietern zählt momentan nur: https://fonts.google.com/.
Zum anderen können Fonts auch über @font-face eingebunden werden.

5. Responsives Design

Zur Unterstützung des responsiven Designs einer Seite gibt es bei AMP ein paar neue Attribute, die den AMP Elementen zugewiesen werden können. Das wichtigste unter ihnen ist das layout Attribut, das mit den Attributen width und height zusammenarbeitet.

Folgende Werte werden durch AMP für das Layout Attribut unterstützt:

nodisplay Keine Angabe zu Höhe/Breite nötig.
Dieses Layout kann jedem AMP Element zugewiesen werden. Es hat den selben Effekt wie display: none
fixed Angaben zur Höhe/Breite nötig.
Die Elemente haben eine festgesetzte Breite und Höhe und unterstützen kein responsives Design. Ausnahmen sind amp-pixel und amp-audio Elemente.
responsive Angaben zur Höhe/Breite nötig.
Das Element wird auf die Breite seines Containers vergrößert oder verkleinert und die Höhe entsprechend angeglichen. Mit Hilfe der max-width Eigenschaft kann die Größe des Elements angepasst werden. Dieses Layout funktioniert mit allen AMP Elementen.
fixed-height Angabe zur Höhe nötig.
Das Element nimmt den zur Verfügung stehenden Platz ein, ohne dabei seine Höhe zu verändern. Das width Attribut sollte nicht angegeben werden oder auf auto gesetzt sein.
fill Keine Angabe zu Höhe/Breite nötig.
Das Element übernimmt die Höhe und Breite des Eltern-Elements.
container Keine Angabe zu Höhe/Breite nötig.
Das Element übernimmt seine Größe von seinen Kind-Elementen, ähnlich einem div. Es verhält sich wie ein Container.

Wenn möglich, sollte das responsive Layout verwendet werden, da dieses der Idee des responsiven Designs entspricht.
Ist das Layout Attribut nicht vorhanden, so wird dem Element abhängig von den gesetzten Werten automatisch ein Layout zugewiesen.

Um seine Seite möglichst responsiv zu gestalten, ist es möglich, allen AMP Elementen das Attribut media zuzuweisen. Dieses funktioniert genau wie CSS Media Queries (die ebenfalls verwendet werden können).


<b><amp-img</b><br>
    media="(min-width: 650px)"<br>
    src="breit.jpg"<br>
    width=466<br>
    height=355<br>
    layout="responsive" <b>></b><br>
<b></amp-img></b>



Je nachdem wir breit der Bildschirm ist, wird eines der beiden Bilder ausgegeben.


<b><amp-img</b><br>
    media="(max-width: 649px)"<br>
    src="schmal.jpg"<br>
    width=527<br>
    height=193<br>
    layout="responsive" <b>></b><br>
<b></amp-img></b>

Des Weiteren werden durch AMP die Attribute srcset und sizes zur Verfügung gestellt. Ersteres wurde bereits bei regulären HTML Seiten benutzt und hat den gleichen Zweck wie das Attribut media. Es stellt dem Browser je nach Bildschirmgröße andere Bilder zur Verfügung.


<b><amp-img</b><br>
    src="breit.jpg"<br>
    srcset="breit.jpg" 640w,<br>
           "schmal.jpg" 320w<br>
    sizes="(min-width: 650px) 50vw, 100vw" <b>></b><br>
<b></amp-img></b>

Die Zahl vor dem w teilt dem Browser mit, wie breit das jeweilige Bild ist. Mit Hilfe des sizes Attributs kann festgelegt werden, in welcher Größe das Bild angezeigt werden soll. Im obigen Beispiel nähme das Bild bei einer Breite des Viewports von 650px und mehr, 50% der Breite des Viewports ein. Hätte der Viewport beispielsweise eine Breite von 600px, so würde die Breite des Bildes auf 300px gesetzt. Dementsprechend würde das 320px breite Bild geladen.

Weitere Informationen, wie man das responsive Design seiner Seite mit AMP verbessern kann, gibt es auf:
www.ampproject.org.

6. Validierung

Ob die nun erstellte Seite AMP-konform ist, lässt sich schnell feststellen. Zusammen mit der AMP JS-Bibliothek wird ein AMP Validator mitgeliefert.
Um diesen zu benutzen, muss #development=1 an die URL der Seite angehängt werden. Nach der Aktualisierung
der Seite werden in der Entwickler-Konsole mögliche Validierungsfehler angezeigt.

Alternativ kann das Web-Interface unter validator.ampproject.org benutzt werden. Dort kann man einfach die URL der Seite angeben und auf VALIDATE klicken. Der Code der Seite wird daraufhin in einem interaktiven Editor angezeigt. Falls Fehler vorhanden sind, werden sie darunter angezeigt und im Code markiert.

Als dritte Möglichkeit wird eine Browsererweiterung (bis jetzt nur für Chrome und Opera verfügbar) angeboten, die jede besuchte AMP Seite automatisch prüft und mit Hilfe eines Icons anzeigt, ob die Seite AMP-konform ist. Praktisch ist außerdem, dass es ein spezielles Icon gibt, um zu signalisieren, dass die besuchte Seite zwar keine AMP Seite ist, aber eine AMP Version dieser Seite vorhanden ist.

Damit die erstellte AMP in den Google Cache geladen wird, muss diese validiert werden. Zur Unterstützung bei der Fehlerbehebung haben die AMP Entwickler einen Guide zu den verschiedenen AMP Validierungsfehlern zur Verfügung gestellt. Dieser kann hier gefunden werden.

Nach der erfolgreichen Validierung des Codes steht der Veröffentlichung der Seite nun nichts mehr im Wege. Ist noch eine Version der Seite in regulärem HTML vorhanden, so muss im Head dieser Seite auf die AMP Version verlinkt werden und umgekehrt. Ist eine solche nicht vorhanden, so muss der Link im Head der AMP Seite auf diese selbst verweisen:

<!-- Reguläre Seite: --> <link rel="amphtml" href="https://www.beispiel.com/url/zu/amp/dokument.html"> 
<-- AMP Seite: --> <link rel="canonical" href="https://www.beispiel.com/url/zu/regulaerem/dokument.html">

Weiterführende Informationen

Unter folgenden Links sind weitere Informationen zu AMP zu finden: