Die WordPress-Einstellungs-API, Teil 7: Validierung, Desinfektion und Eingabe

() translation by (you can also view the original English article)

Wenn Sie gerade erst zu uns kommen, haben wir viele Themen in dieser Reihe behandelt. Wir haben versucht, einen vollständigen Überblick über die WordPress-Einstellungs-API und die zugehörigen Funktionen zu geben. Wir haben Einstellungen, Optionen, Navigation und Menüs besprochen. Wir haben auch praktische Beispiele für jedes der von uns diskutierten Themen erarbeitet.

Wir sind fast fertig. In den letzten beiden Artikeln dieser Reihe werden wir uns mit der Bereinigung, Validierung und den grundlegenden Eingabeelementen befassen, die wir in unseren WordPress-Plugins und -Themen verwenden können.

Bevor wir beginnen: In diesem Artikel wird davon ausgegangen, dass Sie zusammen mit dem Rest der Serie eine Arbeitskopie des Beispielcodes installiert haben und nun mit der Einstellungs-API und den Designoptionen relativ vertraut sind. Wenn Sie sich über eines der oben genannten Dinge nicht sicher sind, empfehle ich dringend, den Rest der Artikel zu lesen, bevor Sie in diesen Beitrag eintauchen.

Grundlegendes zur Validierung und Desinfektion

Bevor wir mit dem Schreiben von Code beginnen, müssen wir genau verstehen, was wir erreichen werden - nämlich Validierung und Desinfektion. Einfach ausgedrückt sind dies die beiden Aspekte des sicheren Schreibens und Lesens von Daten von einer WordPress-Optionsseite und der zugrunde liegenden Datenbank.

Wir werden viel tiefer in dieses Thema eintauchen, wenn wir uns die einzelnen Eingabetypen ansehen und die Beispiele durcharbeiten, aber lassen Sie uns einen Kontext zu dem geben, was wir tatsächlich tun werden:

Die Validierung ist der Prozess, bei dem wir die von der Optionsseite eingehenden Daten - oder vielmehr die Benutzereingaben - untersuchen und feststellen, ob das Speichern akzeptabel ist oder nicht.
Bei der Bereinigung stellen wir sicher, dass die aus der Datenbank kommenden Daten sauber und für das Rendern auf der Seite ordnungsgemäß formatiert sind.

Die vielleicht prägnanteste Zusammenfassung ist, dass die Validierung vor dem Schreiben der Daten in die Datenbank erfolgen sollte und die Bereinigung zwischen dem Lesen der Daten aus der Datenbank und dem Senden an den Browser erfolgen sollte.

Häufig bezieht sich die Validierung auf das Speichern von Daten und die Bereinigung auf das Abrufen von Daten. Es ist jedoch auch vollständig möglich, Daten nach bestandener Validierung zu bereinigen, um sicherzustellen, dass nur saubere Daten in der Datenbank gespeichert werden. Wenn wir mit unserem eigenen Code arbeiten, ist dies einfacher. Wir können uns jedoch nicht immer darauf verlassen, dass andere Entwickler ihre Daten bereinigt haben, sodass die Verantwortung für die Bereinigung aller aus der Datenbank kommenden Daten bei uns liegt.

Aktualisierung unseres Projekts

Um das Verständnis der Validierung und Desinfektion zu vereinfachen, führen wir eine neue Registerkarte in unsere Optionsseite ein. Wenn Sie ein neues Menü der obersten Ebene eingeführt haben, müssen Sie außerdem ein neues Untermenüelement hinzufügen und die Registerkarte "Optionen" aktualisieren. Kümmern wir uns jetzt darum.

Suchen Sie zunächst die Funktion sandbox_example_theme_menu und fügen Sie den folgenden Untermenüpunkt hinzu:

add_submenu_page(
	'sandbox_theme_menu',
	'Input Examples',
	'Input Examples',
	'administrator',
	'sandbox_theme_input_examples',
	create_function( null, 'sandbox_theme_display( "input_examples" );' )
);

Als nächstes müssen wir eine Funktion ausführen, mit der die Gruppe von Optionen für unsere neue Registerkarte "Einstellungen" erstellt wird. Angenommen, Sie haben die Serie mitverfolgt, sollte dies leicht zu befolgen sein:

function sandbox_theme_initialize_input_examples() {

	if( false == get_option( 'sandbox_theme_input_examples' ) ) {
		add_option( 'sandbox_theme_input_examples' );
	} // end if

} // end sandbox_theme_initialize_input_examples
add_action( 'admin_init', 'sandbox_theme_initialize_input_examples' );

Schließlich müssen wir die Funktion sandbox_theme_display aktualisieren, um die Registerkarte zu rendern und sie richtig auszuwählen, wenn entweder über die Registerkarten oder das Untermenüelement darauf zugegriffen wird. Aktualisieren wir zunächst die Bedingung, die die Abfragezeichenfolge und die Argumente der Funktion untersucht. Insbesondere muss der Fall für die Eingabebeispiele behandelt werden. Aktualisieren Sie die Bedingung so, dass sie folgendermaßen aussieht:

if( isset( $_GET[ 'tab' ] ) ) {
	$active_tab = $_GET[ 'tab' ];
} else if( $active_tab == 'social_options' ) {
	$active_tab = 'social_options';
} else if( $active_tab == 'input_examples' ) {
	$active_tab = 'input_examples';
} else {
	$active_tab = 'display_options';
} // end if/else

Als nächstes müssen wir der Navigation eine neue Registerkarte hinzufügen. Aktualisieren Sie den nav-tab-wrapper-Container, um diesen neuen Anker einzuschließen:

1	<a href="?page=sandbox_theme_options&tab=input_examples" class="nav-tab <?php echo $active_tab == 'input_examples' ? 'nav-tab-active' : ''; ?>">Input Examples</a>

Schließlich müssen wir dem Formularelement, das für die Anzeige der Optionen verantwortlich ist, eine weitere Bedingung hinzufügen. Aktualisieren Sie die Bedingung so, dass sie folgendermaßen aussieht:

if( $active_tab == 'display_options' ) {

	settings_fields( 'sandbox_theme_display_options' );
	do_settings_sections( 'sandbox_theme_display_options' );
	
} elseif( $active_tab == 'social_options' ) {

	settings_fields( 'sandbox_theme_social_options' );
	do_settings_sections( 'sandbox_theme_social_options' );
	
} else {

	settings_fields( 'sandbox_theme_input_examples' );
	do_settings_sections( 'sandbox_theme_input_examples' );
	
} // end if/else

Angenommen, Sie haben den gesamten Code korrekt eingefügt, sollte Ihr Admin-Bereich nun folgendermaßen aussehen:

Wir sind jetzt bereit, neue Optionselemente sowie die Validierungs- und Desinfektionsfunktionen einzuführen. Wenn der obige Code unklar erscheint, lesen Sie unbedingt die Artikel weiter oben in der Reihe, da alle Einstellungen, Menüseiten und Registerkarten behandelt wurden.

Die Elementtypen

Es gibt fünf grundlegende Elementtypen, die wir für die Eingabe in unsere WordPress-Optionsseiten verwenden können. Dies sind Eingaben, Textbereiche, Kontrollkästchen, Optionsfelder und Auswahlfelder. Im Rest dieses Artikels werden wir uns die Eingabeelemente und Textbereiche ansehen und die letzten drei im letzten Artikel der Reihe überprüfen.

Eingang

Eingabeelemente sind ideal für Situationen, in denen wir eine kleine Textmenge von einem Benutzer erfassen müssen. Dies kann so etwas wie ihr Name oder ihre Telefonnummer sein oder etwas etwas komplexeres wie eine URL, ihre E-Mail-Adresse oder ein API-Schlüssel. Tatsächlich verwenden wir bereits Eingabefelder auf der Seite "Soziale Optionen", wenn wir nach den Profiladressen des Benutzers für soziale Netzwerke fragen.

Das Überprüfen der Texteingabe kann eine komplexe Operation sein, insbesondere wenn Sie bestimmte Einschränkungen erzwingen möchten. Beispielsweise folgen Telefonnummern einem bestimmten Format. Wenn Sie einen Benutzer nach seiner Telefonnummer fragen, können Sie eine Funktion einrichten, die bestimmt, ob die Telefonnummer dem strengen Format entspricht. Offensichtlich können wir in unseren Beispielen hier nicht alle diese Anwendungsfälle erfassen, da es sich einfach um ein zu weites Feld handelt.

Stattdessen stellen wir sicher, dass kein schädlicher Code in die Datenbank geschrieben wird. Dies bedeutet, dass wenn ein Benutzer Text in unser Textfeld eingibt, alle HTML-Tags und potenziell problematischen Zeichen entfernt werden. Aber bevor wir das tun, wollen wir eine neue Option einführen, das Markup verstehen und dann sehen, was passiert, wenn wir keine Art von Validierung erzwingen.

Führen Sie den neuen Abschnitt und das neue Feld mit der Funktion sandbox_theme_initialize_input_examples ein:

add_settings_section(
	'input_examples_section',
	'Input Examples',
	'sandbox_input_examples_callback',
	'sandbox_theme_input_examples'
);

add_settings_field(	
	'Input Element',						
	'Input Element',							
	'sandbox_input_element_callback',	
	'sandbox_theme_input_examples',	
	'input_examples_section'			
);

register_setting(
	'sandbox_theme_input_examples',
	'sandbox_theme_input_examples'
);

Definieren Sie als Nächstes den Rückruf für den Abschnitt:

1	function sandbox_input_examples_callback() {
2	echo '<p>Provides examples of the five basic element types.</p>';
3	}

Zuletzt stellen Sie das eigentliche Eingabeelement vor, das wir zum Erfassen der Eingabe verwenden werden:

function sandbox_input_element_callback() {
	
	$options = get_option( 'sandbox_theme_input_examples' );
	
	// Render the output
	echo '<input type="text" id="input_example" name="sandbox_theme_input_examples[input_example]" value="' . $options[ 'input_example' ] . '" />';
	
}

Ihre Optionsseite sollte nun wie folgt aussehen:

Markup verstehen

Bis zu diesem Punkt haben wir unsere Optionselemente erstellt und ich habe erwähnt, dass wir später in der Serie jedes der Attribute diskutieren werden. Dies ist der Artikel, in dem wir uns mit der Bedeutung der id- und name-Attribute befassen.

Beachten Sie, dass wir zu Beginn der Funktion die Optionen für diese bestimmte Registerkarte mithilfe der get_option-Funktion von WordPress lesen. Diese Funktion gibt die Optionen in einem Array zurück. Das id-Attribut des Eingabeelements identifiziert den Wert dieses Elements im Array. Das name-Attribut ist der Name des Arrays, das mit der ID verschlüsselt ist. Sinn ergeben?

Um vollständig zu sein, stellen Sie sich das folgendermaßen vor:

WordPress erstellt ein Array basierend auf dem Namen des von Ihnen definierten Abschnitts. In diesem Fall ist es sandbox_theme_input_examples
Jedes Element wird durch das id-Attribut identifiziert. In diesem Beispiel ist es "input_example"
Sie können den Wert dieses Arrays mit sandbox_theme_input_examples[input_example] lesen.

Die id des Elements repräsentiert also den Schlüssel des Werts im Optionsarray, das Attribut name repräsentiert den Namen des Arrays mit dem Schlüssel des Werts im Array.

Hinzufügen von Validierung und Desinfektion

Zu diesem Zeitpunkt ist es durchaus möglich, Werte in das Eingabeelement einzugeben und die Option zu speichern. Probieren Sie es aus - legen Sie einen Wert fest, klicken Sie auf "Änderungen speichern", und das Eingabeelement sollte den soeben erstellten Wert anzeigen. Aber hier ist das Problem: Versuchen Sie, so etwas in das Eingabefeld einzufügen:

1	<iframe src='http://wp.tutsplus.com' width='640' height='480'></iframe>

Wechseln Sie als Nächstes zu index.php und fügen Sie den folgenden Codeblock hinzu:

1	<?php $input_examples = get_option('sandbox_theme_input_examples'); ?>
2	<?php echo $input_examples['input_example']; ?>

Aktualisieren Sie die Homepage und Sie sollten feststellen, dass in der Mitte der Homepage Ihres Themas ein Iframe angezeigt wird:

Scheint ein relativ kleines Problem zu sein, aber genau das müssen wir verhindern. Wir möchten nicht, dass Benutzer diese Art der Kontrolle über die Datenbank, die Websiteseiten usw. haben. Das Speichern eines einfachen Iframes ist natürlich ein kleines Beispiel. Wenn Benutzer JavaScript einfügen können, können sie bestimmte Aspekte Ihrer gesamten Site beeinflussen. Noch schwerwiegender ist, dass Ihre Datenbank gefährdet sein kann, wenn Benutzer in der Lage sind, schädliches SQL einzufügen.

Lassen Sie uns also eine Validierung einführen. Wie oben erwähnt, möchten wir alle Markups und problematischen Zeichen entfernen. Dazu müssen wir zunächst einen Validierungsrückruf für unseren Eingabeelementabschnitt definieren. Lassen Sie uns dazu den Aufruf register_setting erneut aufrufen und so aktualisieren, dass er folgendermaßen aussieht:

register_setting(
	'sandbox_theme_input_examples',
	'sandbox_theme_input_examples',
	'sandbox_theme_validate_input_examples'
);

Als nächstes definieren wir diese Funktion:

1	function sandbox_theme_validate_input_examples( $input ) {
2	} // end sandbox_theme_validate_input_examples

Beachten Sie, dass diese Funktion einen einzelnen Parameter akzeptiert, den wir als input bezeichnet haben. Dieses Argument stellt den nicht validierten Satz von Optionen dar, den WordPress von der soeben gespeicherten Optionsseite an diese Funktion sendet. Beachten Sie auch, dass wir beim Hinzufügen zusätzlicher Optionselemente dieselbe Funktion verwenden.

Das Erstellen einer Validierungsfunktion erfolgt normalerweise in drei Schritten:

Erstellen Sie ein Array, in dem die validierten Optionen gespeichert werden
Überprüfen Sie alle eingehenden Optionen (und bereinigen Sie sie bei Bedarf)
Geben Sie das zuvor erstellte Array zurück

Lass uns das jetzt machen. Schauen Sie sich die folgende Implementierung an und achten Sie dabei genau auf die Kommentare:

function sandbox_theme_validate_input_examples( $input ) {

	// Create our array for storing the validated options
	$output = array();
	
	// Loop through each of the incoming options
	foreach( $input as $key => $value ) {
		
		// Check to see if the current option has a value. If so, process it.
		if( isset( $input[$key] ) ) {
		
			// Strip all HTML and PHP tags and properly handle quoted strings
			$output[$key] = strip_tags( stripslashes( $input[ $key ] ) );
			
		} // end if
		
	} // end foreach
	
	// Return the array processing any additional functions filtered by this action
	return apply_filters( 'sandbox_theme_validate_input_examples', $output, $input );

}

Der größte Teil des Codes sollte relativ einfach sein, aber die beiden wichtigsten Aspekte betreffen die Anweisung innerhalb der bedingten und der return-Anweisung.

Wir verwenden die für PHP native Funktion strip_tags, um alle HTML- und PHP-Tags zu entfernen
Wir verwenden die stripslashes-Funktion, eine weitere native PHP-Funktion, die Anführungszeichen um einen String herum korrekt verarbeitet.

Schließlich hätten wir einfach das $output-Array am Ende der Funktion zurückgeben können, aber die Rückgabe des Ergebnisses des Aufrufs an apply_filters ist eine bewährte Methode. Obwohl es den Umfang dieses Artikels überschreitet, ist es erwähnenswert, dass diese Anweisung grundsätzlich alle anderen Funktionen aufruft, die von dieser bestimmten Funktion gefiltert werden, bevor der Wert zurückgegeben wird.

Versuchen Sie nun, eine Beispieleingabe in das Eingabeelement einzugeben. Geben Sie eine einfache Zeichenfolge, eine Telefonnummer, eine E-Mail-Adresse, eine URL, einen HTML-Block, eine Zeile JavaScript usw. ein. Ordentlich, was?

Lassen Sie uns abschließend index.php erneut besuchen und eine letzte Änderung vornehmen, um zu demonstrieren, wie wir die Ausgabebereinigung durchführen können. Denken Sie daran, dass es empfehlenswert ist, Optionen zu bereinigen, auch wenn Sie mit Werten arbeiten, die nicht aus Ihrer eigenen Arbeit stammen.

Suchen Sie die Zeile mit der Aufschrift:

1	<?php echo $input_examples[ 'input_example' ]; ?>

Und aktualisieren Sie es so, dass es lautet:

1	<?php echo sanitize_text_field( $input_examples[ 'input_example' ] ); ?>

Die Funktion sanitize_text_field ist eine weitere native WordPress-Funktion, mit der Benutzereingaben aus Textfeldern oder aus der Datenbank bereinigt werden sollen.

Wir werden uns in diesem und im nächsten Artikel mehr damit befassen, aber es gibt eine vollständige Liste dieser Funktionen im WordPress-Codex.

Textbereich

Bei der Betrachtung der Eingabeelemente haben wir viel Boden unter den Füßen. Glücklicherweise gelten viele der gleichen Prinzipien nicht nur für Textbereiche, sondern auch für den Rest der Elemente. Daher sollten wir nicht so viel Zeit mit jedem Element verbringen müssen. Dies gibt uns die Möglichkeit, einige der Besonderheiten zu betrachten, die mit jedem der Elementtypen verbunden sind.

Lassen Sie uns zunächst ein Textarea-Element einführen. In unserem Beispiel können Benutzer mit diesem speziellen Element einige Sätze über sich selbst eingeben - stellen Sie sich das als kurze Biografie vor. Fügen Sie zunächst der Funktion sandbox_theme_initialize_input_examples den folgenden Aufruf hinzu:

	
add_settings_field(	
	'Textarea Element',						
	'Textarea Element',							
	'sandbox_textarea_element_callback',	
	'sandbox_theme_input_examples',	
	'input_examples_section'			
);

Als nächstes definieren wir den Rückruf, der zum Rendern des Textbereichs erforderlich ist:

function sandbox_textarea_element_callback() {
	
	$options = get_option( 'sandbox_theme_input_examples' );
	
	// Render the output
	echo '<textarea id="textarea_example" name="sandbox_theme_input_examples[textarea_example]" rows="5" cols="50">' . $options[ 'textarea_example' ] . '</textarea>';
	
}

Beachten Sie, dass dieser Aufruf dem oben definierten Eingabeelement sehr ähnlich ist. Insbesondere haben wir ein id-Attribut angegeben, um diesem Wert einen Schlüssel im Optionsarray zuzuweisen, und wir haben den genauen Namen und Schlüssel im name-Attribut des Elements angegeben. Wir haben dem Textbereich auch eine bestimmte Größe gegeben, obwohl dies rein willkürlich ist.

Denken Sie daran, dass dieses Element, da es zum selben Abschnitt wie das Eingabeelement gehört, mit derselben Validierungsfunktion verarbeitet wird. Als solches erhalten wir die gleiche Validierungsstufe kostenlos. Probieren Sie es aus - versuchen Sie, Markups, Skripte und andere Codetypen mithilfe des Textbereichs zu speichern.

Zuletzt aktualisieren wir die öffentlich zugängliche Seite unseres Themas, um diesen Wert abzurufen und ihn für die Anzeige ordnungsgemäß zu bereinigen. Fügen Sie in index.php den folgenden Codeblock hinzu:

1	<?php if( $input_examples[ 'textarea_example' ] ) { ?>
2	<?php echo sanitize_text_field( $input_examples[ 'textarea_example' ] ); ?>
3	<?php } // end if ?>

Obwohl es praktisch dasselbe ist wie das Eingabefeld, müssen wir sicherstellen, dass unsere Validierung und Desinfektion vollständig ist.

Abschluss

Obwohl wir nur zwei Arten von Elementen betrachtet haben, haben wir viel Boden unter den Füßen. Wir haben nicht nur unser Thema auf den neuesten Stand gebracht, sondern auch die grundlegende Validierung implementiert und begonnen, die Desinfektionsfunktionen von WordPress zu erkunden.

Im letzten Artikel werden wir uns die verbleibenden drei Elementtypen ansehen und wie sie mithilfe von Validierung und Desinfektion verwaltet werden. Experimentieren Sie in der Zwischenzeit mit einigen der hier behandelten Themen und denken Sie daran, die zugehörigen Quellartikel zu lesen, die am Ende des Beitrags verlinkt sind.