Beispiele #

Dieser Bereich enthält Beispiele, die Sie in eine echte Installation übernehmen können. Es gibt drei Arten:

Warnung .htaccess bremst jede Anfrage. Sind .htaccess-Dateien erlaubt (AllowOverride alles außer None), geschweige denn genutzt, sucht Apache sie bei jeder Anfrage in jedem Verzeichnis des Pfads und liest und wertet sie aus, und die Ladezeiten der Seiten steigen drastisch (gemessen). Die einzige wirkliche Abhilfe ist, die Funktion für den virtuellen Host abzuschalten: AllowOverride None im virtuellen HTTPS-Host, und die Regeln in der Konfiguration des virtuellen Hosts selbst als mod_rewrite-Regeln. Das ist in Geschwindigkeitstests im Produktivbetrieb weit schneller und die Zeit für die Optimierung einer Produktivkonfiguration unbedingt wert. Stellen Sie sofort um: Übernehmen Sie die Regeln des Beispiels für einen virtuellen HTTPS-Host in Ihren virtuellen Host (mit dem statischen Cache auch staticcache_offload.conf), setzen Sie AllowOverride None, führen Sie apachectl configtest aus, laden Sie Apache neu und testen Sie die Website. Dieselben Regeln für andere Server: nginx, LiteSpeed, Caddy, IIS, Velocity (eingebaut); wohin Regeln für virtuelle Hosts in einem Control Panel gehören: Plesk, cPanel, DirectAdmin, ISPConfig. Unter LiteSpeed oder OpenLiteSpeed kann zusätzlich der Seiten-Cache des Servers anonyme Besucher und Crawler ohne PHP bedienen: Seiten-Caching mit LiteSpeed und OpenLiteSpeed.

• Webserver-Beispiele: vollständige Konfigurationen für Exponential Velocity, Apache (.htaccess und virtueller Host), nginx, Caddy, FrankenPHP, LiteSpeed, IIS und PHP-FPM. Jede leitet Anfragen genauso weiter wie die ausgelieferte .htaccess_root. Die Syntax jeder Konfiguration wurde geprüft, die meisten wurden außerdem auf einem Testserver erprobt.
• Kochbuch: vollständige Aufgaben von Anfang bis Ende. Eine Inhaltsklasse, ein Template-Override, ein eigener Template-Operator, Datentyp, ein eigenes Modul, Workflow-Ereignis und ein eigener Cronjob, ein Erweiterungsgerüst, JSON-Aufrufe, mehrere Websites in einer Installation, Übersetzungen, Caching und das Ausrollen mit Velocity.
• Referenzbeispiele, aus dem Code erzeugt: eine Seite pro Element, jede mit einem Beispiel, das aus der Definition abgeleitet ist, die der Code mitbringt. Die Liste steht unten.

Die Regeln für das Schreiben von Code (Benennung, Dateiaufbau, Sicherheit, Templates ohne Inline-Styles oder -Skripte) stehen in Standards und Muster. Dieser Bereich zeigt sie in der Anwendung und wiederholt sie nicht.

Webserver und Hosting #

staticcache_offload.conf ergänzt Regeln, die Seiten direkt aus dem statischen Cache ausliefern. Siehe Apache .htaccess.

Die mitgelieferten Vorlagen .htaccess_root (oder .htaccess_root_static) und config.php-RECOMMENDED bringen ./console exp:setup:htaccess --apply und ./console exp:setup:config --apply an ihren Platz, und config.php wird mit ./console exp:config:set bearbeitet: siehe .htaccess und config.php von der Konsole einrichten und die erzeugten Seiten exp:setupfiles und exp:configphp.

Aus dem Code erzeugte Referenzbeispiele #

Die Hilfe listet diese Seiten in Ordnern. Ein Ordner klappt in der Navigation auf, sobald Sie auf einer seiner Seiten sind; seine Übersichtsseite verlinkt jede Seite darin. In der Suche stehen sie unter den geschriebenen Anleitungen, sodass eine Frage zuerst die Erklärung findet und danach die Referenz.

Die deutschen Seiten werden aus demselben Code erzeugt wie die englischen. Die festen Texte und die Kommentare der Quellen kommen aus der deutschen Übersetzung in doc/ger-de/.examples/; ein Kommentar, der dort noch fehlt oder sich seit der Übersetzung geändert hat, erscheint auf Englisch.

Was „aus dem Code abgeleitet“ bedeutet #

• Aus den Definitionen gelesen. Namen, Parameter, Typen, Standardwerte, Richtlinienfunktionen, Einschränkungen, INI-Werte und ihre Kommentare sowie Optionslisten werden aus den Dateien gelesen, die der Kernel lädt, etwa eztemplateautoload.php, function_definition.php, module.php, operation_definition.php, die ausgelieferten INI-Dateien, die Klassen der Datentypen und Workflow-Ereignisse, cronjob.ini und die Befehlsklassen. Jede Seite nennt ihre Quellen am Ende.
• Platzhalter. Werte in einem Beispielaufruf, etwa 1 für eine Ganzzahl oder 'text' für eine Zeichenkette, zeigen nur die Form. Jede Seite sagt das.
• Heuristiken. Manche Angaben sind Vermutungen und als solche gekennzeichnet: die Speicherspalten, die ein Datentyp verwendet (durch Lesen seiner Klasse ermittelt), und die Erweiterungspunkte (am Namen der Einstellung erkannt).
• Erste Verwendung in einem ausgelieferten Template. Das ist der erste Treffer in den Templates des Repositorys, in der Reihenfolge der Pfade. Es ist echter Code, aber nicht immer das einfachste Beispiel.
• Nur der ausgelieferte Code. Gelesen werden nur Dateien, die im Repository versioniert sind: der Kernel, seine Bibliotheken und die mitgelieferten Erweiterungen. Andere installierte Erweiterungen, lokale Overrides und die Datenbank bleiben außen vor. Das gilt auch für Einstellungen, die eine Quelle beim Lesen abfragt (eine module.php, die die Werte einer INI-Einstellung auflistet, die PHP-Operatoren der template.ini): Sie kommen aus settings/ und den Einstellungen der mitgelieferten Erweiterungen, nie aus einem Override, einem Siteaccess, dem INI-Cache oder einer Erweiterung außerhalb des Repositorys. So erhalten eine Installation, ein Git-Worktree und die CI dieselben Seiten. Die Einschränkungen nach Objektzuständen sind die einzige Stelle, an der der Kernel die Datenbank lesen würde. Ihre Seiten sagen stattdessen, woher diese Einschränkungen kommen.

So entstehen die generierten Seiten #

Sie stammen aus einem Befehl, der im Wurzelverzeichnis der Installation ausgeführt wird:

./console exp:help:examples                 # write every area; only changed files are written
./console exp:help:examples --list          # the areas and how many pages each has
./console exp:help:examples --check         # change nothing; exit 1 if a page is missing, different or stale
./console exp:help:examples --area=datatypes,cronjobs
./console exp:help index --rebuild          # then rebuild the help index

Die deutschen Seiten erzeugt derselbe Befehl mit --language=ger-de; er schreibt sie nach doc/ger-de/beispiele/ und trägt sie in doc/ger-de/.paths.json ein:

./console exp:help:examples --language=ger-de
./console exp:help:examples --language=ger-de --check
./console exp:help:examples --language=ger-de --worklist=var/tmp/todo.json

Die Ausgabe ist deterministisch. Dieselben Quellen ergeben immer dieselben Dateien: Die Eingabe wird sortiert, und die Seiten enthalten keine Daten und keine Hostnamen. Führen Sie den Befehl nach einer Änderung an einem Operator, einer Fetch-Funktion, einer Ansicht, einer Richtlinie, einer INI-Datei, einem Datentyp, einem Workflow-Ereignis, einem Cronjob oder einem Befehl aus und committen Sie die geänderten Seiten zusammen mit dieser Änderung. --check in einem Review oder einem CI-Job findet Seiten, die nicht neu erzeugt wurden.

Die Übersetzung liest ihre Texte aus doc/ger-de/.examples/: strings.json enthält die festen Texte der Seiten (Überschriften, Beschriftungen, Sätze) mit ihren {Platzhaltern}, descriptions/*.json die Kommentare und Beschreibungen aus den Quellen, je Element (etwa ini:settings/site.ini [Block] Setting) mit dem englischen Text, den sie übersetzen. Eine Übersetzung wird nur verwendet, solange ihr englischer Text dem der Quelle entspricht; die Arbeitsliste von --worklist enthält die Texte, die neu zu übersetzen sind. Code, INI-Schlüssel und -Werte, Befehle und Bezeichner werden nie übersetzt.

Jede generierte Seite trägt generated: exp:help:examples in ihrem Front Matter. Der Befehl ersetzt oder entfernt nur Seiten mit dieser Markierung, innerhalb der oben genannten Bereiche. Die von Hand geschriebenen Seiten fasst er nie an: diese hier, die Webserver-Beispiele und das Kochbuch. Um eine generierte Seite zu ändern, ändern Sie ihre Quelle (oder ihre Übersetzung) und führen den Befehl erneut aus. Änderungen an der Seite selbst gehen beim nächsten Lauf verloren.

Der Code ist kernel/classes/help/exphelpexamplesgenerator.php (Klasse expHelpExamplesGenerator), die Übersetzung kernel/classes/help/exphelpexamplestranslation.php (Klasse expHelpExamplesTranslation), und der Befehl ist kernel/private/classes/commands/exphelpexamples.php. Um einen Bereich hinzuzufügen, geben Sie der Klasse eine Methode area<Name>() und einen Eintrag in AREAS.

Hilfe-Einstellungen für diesen Bereich #

settings/exphelp.ini:

• Die Kategorie examples: [CategorySettings] Categories[], CategoryNames[examples], CategoryIcons[examples].
• Der Seitentyp generated für die generierten Seiten: [TypeSettings] TypeNames[generated]. Er steht in der Suche über [SearchSettings] TypeBoost[generated] weiter unten und bleibt über [DashboardSettings] AudienceExcludeTypes[] von den Zielgruppenkarten des Dashboards fern.
• Die eingeklappten Ordner der Navigation: [NavigationSettings] FoldedFolders[].

Verwandte Seiten #

• Standards und Muster: die Regeln, denen die Beispiele folgen.
• Die Website ausliefern und Sicherheitshärtung.
• Templates und Design, Rollen und Richtlinien, Workflows, Cronjobs.
• Das Hilfesystem.
• Freie Dokumentation: Diese Seite dürfen Sie frei kopieren, übersetzen und verbessern.