Categorie: WordPress

De WordPress-thema’s die we tegenwoordig bij Pronamic ontwikkelen, zijn doorgaans volledig opgebouwd met blokken. We zetten daarbij ook steeds meer in op Full Site Editing (FSE)-thema’s. Bij maatwerkontwerpen maken we daarbij vaak intensief gebruik van blockpatronen, blockstijlen en blockvariaties.

Bij het registreren van een block style kun je een style_handle meegeven. Tijdens het ontwikkelen van een maatwerkplugin viel het me eerder dit jaar (in maart) al op dat de bijbehorende stylesheet niet automatisch werd ingeladen. Destijds heb ik dat opgelost door de stijl handmatig te laden in een block render callback, waarbij ik controleerde of de custom style actief was. Onlangs liep ik bij het uitwerken van een campagnesite opnieuw tegen hetzelfde probleem aan. Ik ben de documentatie nog eens gaan nalezen en heb gezocht naar gerelateerde GitHub-issues. Al snel vond ik WordPress/Gutenberg issue #27244, waarin een gebruiker aangaf dat hij het probleem ook had ontdekt via de officiële documentatiepagina: https://developer.wordpress.org/themes/features/block-style-variations/.

Op die pagina staat inmiddels ook een duidelijke waarschuwing:

style_handle currently has a bug where it only enqueues the stylesheet in the editor but not on the front end. Until that linked ticket is addressed, its use is not recommended.

Block Style Variations – Theme Handbook | Developer.WordPress.org

Dat had ik eerder niet gezien. Ik ging er eigenlijk vanuit dat style_handle de aanbevolen en nette manier was om block-CSS aan te bieden, maar dat blijkt dus niet (meer) het geval te zijn. In de laatste reactie binnen het GitHub-issue wordt zelfs aangegeven dat de optie nooit echt goed gewerkt heeft en dat verwijderen misschien overwogen moet worden. Misschien is het gebruik van een inline_style voorlopig dus nog wel de meest betrouwbare aanpak.

<?php

\add_action(
	'init',
	function() {
		$url = \get_block_asset_url( __DIR__ . '/images/beige-cutout-1.svg' );

		\register_block_style(
			'core/group',
			[
				'name'         => 'custom-beige-cutout-1',
				'label'        => __( 'Beige cutout 1', 'custom' ),
				'inline_style' => <<<END
					.wp-block-group.is-style-custom-beige-cutout-1 {
						background-image: url("$url");
						background-repeat: no-repeat;
						position: calc( 100% + ( ( 1920px - 100vw ) * 0.2 ) ) top;
					}
					END,
			]
		);
	}
);

https://core.trac.wordpress.org/ticket/55184

In februari stuitte ik op een bericht van Tanner Record waarin hij het gebruik van slashes in WordPress filter- en action-hooks voorstelde. Hij suggereert bijvoorbeeld de volgende conventie te volgen:

apply_filters( '{prefix}/{plugin}/{hook-name}', $data );

Using slashes in your #WordPress plugin hooks:

• Improves readability
• Increases the specificity
• Avoids collisions with other plugins
• Uses a similar format as namespacing

Easy to read hooks are much easier to work with. pic.twitter.com/Ul1gwgHv1K

— Tanner Record (@tarecord) February 13, 2024

Gebruik in populaire WordPress plugins

Ik was een vergelijkbare notatie al wel tegen gekomen in populaire plugins zoals “Query Monitor” en “Advanced Custom Fields”:

Query Monitor

// Start the 'foo' timer:
do_action( 'qm/start', 'foo' );

// Run some code
my_potentially_slow_function();

// Stop the 'foo' timer:
do_action( 'qm/stop', 'foo' );

https://querymonitor.com/wordpress-debugging/profiling-and-logging

Advanced Custom Fields

add_action('acf/init', 'my_acf_init');

function my_acf_init() {
    // Get ACF version.
    $version = acf_get_setting('version');

    // Do something.  
}

• https://www.advancedcustomfields.com/resources/#actions
• https://www.advancedcustomfields.com/resources/#filters

Andere plugins

Mijn collega Reüel kwam nog met een reguliere expressie Github-zoekopdracht om het gebruik van deze notatie op te speuren in GitHub-repositories:

/do_action(\s['"]\w+\/\w+['"]\s(,.*?))/ language:PHP

Op basis hiervan heb ik al wel eens overwogen om een vergelijkbare notatie te introduceren in Pronamic-plugins. In de reacties op het bericht van Tanner worden echter ook een aantal nadelen genoemd.

Waarschuwing door “WordPress Coding Standards for PHP_CodeSniffer”

Agreed though I wish it didn’t trigger a warning from the coding standards

— Brian Coords 💻 (@briancoords) February 14, 2024

Bij het gebruik van de volgende notatie zal de “WordPress Coding Standards for PHP_CodeSniffer” bibliotheek een waarschuwing geven:

do_action( 'pronamic/plugin/init' );

Words in hook names should be separated using underscores. Expected: 'pronamic_plugin_init', but found: 'pronamic/plugin/init'.

De WordPress.NamingConventions.ValidHookName.UseUnderscores sniff waarschuwt hierover:

https://github.com/WordPress/WordPress-Coding-Standards/blob/29488feb64b723674fe463e691a4f83682c2dd5e/WordPress/Sniffs/NamingConventions/ValidHookNameSniff.php#L31

In de “Coding Standards Handbook” staat namelijk het volgende vermeld:

Use lowercase letters in variable, action/filter, and function names (never camelCase). Separate words via underscores.

https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/#naming-conventions

Nou is het prima mogelijk om af te wijken van de “WordPress Coding Standards”. Bij Pronamic hanteren we ook een eigen standaard, die op een paar punten afwijken van de “WordPress Coding Standards”: https://github.com/pronamic/wp-coding-standards.

Lastiger te selecteren en kopieren

Neat, but the less_fancy_hook_name is easy to select with a double-click.

Without doing precision pointing and mouse down events, it requires me a double click, the shift key, and a third click, to select the more/fancy/version.

— Konstantin Kovshenin (@kovshenin) February 14, 2024

Bij het dubbel klikken op een tekst zoals pronamic_plugin_init zal direct de hele tekst geselecteerd worden. Bij het dubbel klikken op de tekst pronamic/plugin/init zal alleen een deel tussen de slashes geselecteerd worden. Dit maakt het dat ik voor nu nog de pronamic_plugin_init notatie zal aanhouden.

Het is alweer een paar weken geleden dat ik een bericht van Tanner Record op X voorbij zag komen op mijn tijdlijn over het gebruik van ‘output buffering’ in WordPress plugins:

You don’t have to mix HTML with PHP in your plugin functions.

Use output buffering:

1. Start output buffering
2. Include your HTML template
3. Return (or echo) the result

Your template can also include any variables within the same function scope. pic.twitter.com/EzLSS9BoOK

— Tanner Record (@tarecord) February 17, 2024

Vergelijkbare constructies gebruiken we bij Pronamic ook regelmatig, maar ik herinnerde me ook een GitHub-issue binnen het “WordPress Coding Standards” voor PHP_CodeSniffer project: Add sniff to warn against using output buffering #1422. In dit issue stelt Juliette Reinders Folmer voor om een ‘sniff’ toe te voegen die gaat waarschuwen voor het gebruik van ‘output buffering’. Blijkbaar kunnen er ook problemen ontstaan bij het gebruik van ‘output buffering’ binnen WordPress. Zelf hebben we nog nooit met de genoemde problemen te maken gehad. Het is echter wel goed om te realiseren dat er dergelijke problemen kunnen ontstaan. In de reacties op het bericht van Tanner wordt ook voorgesteld om een PHP ’template engine’ zoals Blade of Twig te gebruiken. Een dergelijke ’template engine’ kan de nadelen van ‘output buffering’ wegnemen. Voor eenvoudige projecten zal ‘output buffering’ prima functioneren.