Tag: wordpress

The WordPress Gutenberg block editor – a FAQ for cynics

Is it any good?

Meh. But I’ve reached the stage where I’ll no longer disable it by default.

Will it save you any time?

That depends on who “you” are and what you’re doing / writing. There are keyboard shortcuts (if you post often enough to memorise them), but you’ll probably find yourself using the mouse a lot more.

You’ll need to relearn where some things are in the sidebar (e.g. permalink settings) – and it doesn’t quite have feature parity there yet (unless I’m mistaken).

It’s certainly more useful friendly and (imho) also better having a toolbar and menus that adapt to the context.

The editor writing area is also incredibly uncluttered, though much of the stuff has been shoved in the (fixed width) sidebar that’s now full of sections you’ll need to learn to navigate or expand or collapse as needed, and also of course every other page in the WordPress admin area is exactly how it’s always been.

I’d describe it as stable – I’ve not had any real javascript errors yet.

What happens with old and new posts?

New posts

Once you disable the Classic Editor plugin, when you begin every new post you’ll start in the block editor.

Old posts

  • Crucially, turning on Gutenberg (by disabling the Classic Editor plugin) doesn’t make any difference to existing posts (created pre-Gutenberg, in TinyMCE) until you edit them.
  • When you do edit an old post, you get the new “minimalist” view, but your post is converted to a single “classic block” in “classic edit” mode. Once you place the cursor somewhere, you’ll see the familiar TinyMCE toolbar with font styles, buttons to add remove links and so on.

You can leave that intact and make simple edits, or add other blocks around it, or use the “convert to blocks” button, which splits a classic block up by paragraphs (and with some “intelligent” stuff based on the content.)

Classic Blocks also give you an ‘Edit as HTML’ option.

Here’s a slightly longer guide to avoid repeating what others have written.

What happens if you decide to turn Classic Editor back on for some reason?

Any posts you’ve written in the block editor would still display correctly: the code that renders Gutenberg blocks is in WordPress core. You can still edit them too, but you won’t see the new interface and you should switch to text mode – then you can see the HTML comment tags (because that’s how it works) used by the block editor to mark the start and end of blocks, and any extra metadata such as block titles.

All these HTML comment tags are only stored in the “posts” database table, they’re never sent to a user’s web browser. (The overall output seems just as clean as before.)

Converting blocks from one type to another

You’ll want to do this quite often. To change a block type, you click it’s icon (on the far left of the toolbar) – each block type has a different icon – e.g. the paragraph marker for a paragraph block, or a bookmark-style thing for headings.

There are limits on which block types you can convert between, some of which seem unnecessarily restrictive.

Shortcodes

Shortcodes are still supported, but you need to paste them into a Shortcode block.

The “custom HTML” block type

Two key differences from Classic blocks:

  • HTML blocks don’t mess around with your code, adding
    or tags with every line break the way the old WordPress editor used to.
  • in HTML blocks, you can toggle between source and preview instantly without having to open a separate tab.

This would be the one to use for newsletters.

Reusable blocks

Key thing to remember: these aren’t empty templates you fill in each time – i.e. you can obviously reuse them across multiple posts, but editing a reusable block changes every instance of it across the site.

Also once you create them, unhelpfully they’re always labelled ‘Untitled’. You need to go to the Block Manager page (you can get to this via the … dropdown menu on the far-right when editing, under Tools > Manage all reusable blocks)

Detailed guide to reusable blocks

Shifting blocks around

Note you can shade several blocks in using the keyboard and the icon changes to a ‘stack’, you can then move them together using the up/down icons.

Block patterns

Frankly of very limited use right now.

A block pattern is a collection of predefined blocks and they are inserted all at once. (Add a block, choose ‘Patterns’ and use the dropdown menu to select the type you want.)

There isn’t really a way to configure your own patterns via the UI (though someone has written a ‘Custom block patterns’ plugin).

It’s possible to generate them by writing/updating a theme or plugin.

Compatibility with ‘Post templates’ plugin

(because I have a client who uses this). It’s a plugin that’s no longer updated so is not Gutenberg compatible.

You can still create new posts using post templates (i.e. go to Templates and choose ‘New post fromtemplate’).

When you do, it will appear as a single “classic block” and you will need to edit it manually.

Display – meta panels underneath the editor

(You may want to reduce clutter)

There’s a setting to show hide/all these individually, but it’s buried several menus deep.

  • Create or edit a post
  • Click on the three dot icon on the far right
  • then Preferences at the very bottom
  • then the Panels lh-menu item on the modal window that appears
  • then under ‘Additional’ you can show/hide all the sections (hiding things doesn’t get rid of any of the old settings)

Troubleshooting custom WordPress WP-CLI commands running on WP Engine’s SSH Gateway

This is a one line fix if you have missing string/array output from a custom WP-CLI command when using the WP Engine “SSH Gateway”.

Terminology:

    • WP Engine is a WordPress hosting company*.
    • They have an SSH Gateway – where you login to a separate machine and it will pass a limited range of useful commands to your actual server (basic file management, a MySQL console client, WP-CLI)
    • WP-CLI is a timesaving WordPress command line utility.

The problem is the unorthodox way the gateway works suppresses ordinary output from certain commands – e.g. print_r or echo.  Symptom: you run a  WP-CLI command of your own through the SSH gateway and lines of text you’re expecting are missing.

First, you should switch from WP_CLI::line() (deprecated now anyway) to WP_CLI::log() – the line() method doesn’t work because, if you dig into the source code, you’ll see it just echos the output, however log() uses the proper wp-cli Logger class.

That’s fine if you want to output strings. Unfortunately, it doesn’t work if you need to print an array.

This does though:

fwrite( STDOUT, print_r($foo, TRUE) );

To unpack that, we’re using print_r to neatly print the array. The second argument for print_r returns its value as a string.   You need not fopen STDOUT first, as you would for another file handle.

And that’s it.

* Would I recommend WP Engine? No, given I have hosting knowledge myself, and when I asked for their assistance with this particular problem, their support agent told me it was out of scope and I should look at StackOverflow, for which they have earned this mildly passive aggressive paragraph in a blog post that will sink without trace.   However, many people do like them, and if you’re a WordPress developer, you may well inherit a client with a site hosted there one day.

WordPress PSA: disable “Glue for Yoast SEO & AMP” plugin

If you have a site using the AMP plugin in “Reader” (formerly “Classic”) mode – which is to say it uses some simple templates for rendering AMP pages – you should remove Glue for Yoast SEO & AMP:

– it is no longer necessary
– the code in glue-for-yoast-seo-amp/classes/frontend.php adds a duplicate inline CSS selector for

header.amp-wp-header

and

.amp-site-title a

. This means the default colour scheme will override colours you set in Appearance > AMP.

Disabling the plugin fixes this.

(Tested with AMP 1.5.5, WordPress 5.4.2)

WordPress – WPML – fix an incorrect language

I had a site using WPML (WordPress Multilingual) where the site’s language picker was set to English but a Chinese translation was consistently showing up for one particular item.

This turned out to be a simple case of the wrong language being set for the post in the database, but to the best of my knowledge you’d never be able to find that out from the UI.

Fortunately it’s easy to detect and fix with some simple PHP and SQL – the examples below use WP-CLI commands.

Firstly, you can use wp shell to verify the language the post is set to.

wpml_get_language_information('',123456);

The language is stored in the wp_icl_translations table, where element_id = the post ID.  So, using wp db query:

update wp_icl_translations set language_code = 'zh-hans' where element_id = 123456;

The above sets the post language to Chinese, which means it won’t be visible when the English version is requested.

Remember to clear any caches you are using.

 

WordPress REST API security risks

I’d recommend any WordPress users install the disable-JSON-API plugin.  This will prevent anonymous access to WP REST API endpoints, such as /wp-json/wp/v2/users – which provides a list of usernames (API docs).

The REST API was introduced in WordPress 4.7 and is (unfortunately) on by default with no option in settings to turn it off – the idea is it will in time be used for AJAX in some of the admin system, not just external requests.   There is a good change if you were running 4.7.0 or 4.7.1 and did not immediately upgrade to the 4.7.2 security release posts may have been defaced.

Also be aware that the WordPress readme.html file no longer displays complete version numbers – e.g. it will show 4.7 rather than 4.7.2.  (a step backward, IMHO).  Though you might not be aware however you can get the version number by clicking on the WordPress icon at the left of the admin bar (and of course, WP-CLI users can do: wp core version)

Troubleshooting remote debugging with Xdebug in PhpStorm

Updated Fri 7 Dec 2018.

Running Xdebug remotely is very useful – you can add breakpoints, inspect and modify the state of all variables/objects and type PHP code into a live console.  No need to manual add var_dump() statements etc.
It should save you a lot of time.

Unfortunately, while the setup should be straightforward, it’s easy to lose the programming time you save spending ages tweaking your Xdebug and PhpStorm configuration to get it to work in the first place. (In fact, I don’t think it’s worked correctly first time for me once.)

Also, you’ve probably got multiple projects, maybe running on different VMs, or using Docker (scroll down for special instructions for Docker on the Mac).

Drupal users:

There’s an element of “it just works” for Xdebug in the server/PhpStorm configuration when using Acquia Dev Desktop or Drupal VM.

Acquia Dev Desktop:

To enable/disable Xdebug:

edit /Applications/DevDesktop/php7_1/bin/php.ini
Uncomment the zend xdebug extension and turn on remote_enable

zend_extension=xdebug.so
xdebug.remote_enable = 1

Restart Apache – via one of:

  • the DevDesktop UI
  • the UI but with keyboard shortcuts, cmd-2 (stop) then cmd-1 (start)
  • CLI: /Applications/DevDesktop/apache/bin/apachectl -k restart

Drupal VM:

To turn on xdebug, make sure you’ve got:

php_xdebug_default_enable: 1

and:

installed_extras:
[...]
- xdebug

Then run vagrant provision to build/rebuild (this won’t affect your site). Leave PhpStorm set to port 9000.

Everyone else (non Drupal):

On other installations, here’s my growing checklist when I try to use Xdebug and nothing happens:

(The following is based on Xdebug 2.4.0RC4 and PhpStorm 2016.2.1)

Step 1: you should identify whether it’s a complete lack of communication between Xdebug and the IDE, or if PhpStorm is receiving the data the data but is setup wrong.

Close and restart PhpStorm.  Make sure PhpStorm is listening for PHP Debug Connections (bottom of Run menu, or green telephone icon top right), then reload your app in the browser.

What you’re looking for is either:

a) an ‘Incoming connection’ dialog the very first time you open a webpage of your app.
or
b) ‘Debug session was finished without being paused” in the Event Log.

Either of these confirms Xdebug is talking to PhpStorm and you can need not worry about your php.ini entries, the possibility you’re using the wrong port or that you forgot to trigger the bookmarklet – goto section B.

If nothing happened at all, go to section A.

A. Communication failure

  • Ensure the bookmarklet (recommended) or browser addon you’re using to start/stop debugging is activated.  You can use developer tools to verify the cookie is being sent.
  • Is Xdebug installed? (check phpinfo() output)
  • Does the Xdebug section of phpinfo() have this warning: “XDEBUG NOT LOADED AS ZEND EXTENSION”?  You’re meant to use zend_extension=xdebug.so, not extension=xdebug.so – go to the wizard, paste in your phpinfo() contents and it’ll generate a fully customised set of commands to run (< 2-3 mins) to download the xdebug extension and compile it for your system. (I’ve had this problem break one site – further info).
  • Make sure the bookmarklet’s cookie is correct, it should use PHPSTORM for the IDE key.    does the browser IDE key match xdebug.idekey in your php.ini file? (Verify correct config file is being loaded – have you confused configs for multiple versions or CLI/fpm – and correct value read from it by creating a test page with phpinfo() output.)  Correction: specifying xdebug.idekey in php.ini is unnecessary.  Note if you view the phpinfo() output, at the top of the Xdebug section there’s are two rows, listing the version and the IDE key. If xdebug.idekey is unset, XDebug will fall back to the value of $_SERVER[‘USER’], e.g. www-data, but regardless, as soon you activate your bookmarklet to start a debug session, the $_COOKIE[‘XDEBUG_SESSION’] is set to ‘PHPSTORM’ and that’s what’s passed through. (To test, start and stop a session whilst refreshing your phpinfo() page and watch the IDE key change.)
  • php.ini – ensure xdebug.remote_enable is set to 1 (then restart php-fpm, refresh page and keep an eye out for ‘Debug session was finished without being paused’ in the Event Log)
  • php.ini – you may well need xdebug.remote_connect_back = 1 too (again, restart php-fpm) – I’ve had multiple dev sites that require it – XDebug may be ignoring the connection from the debug client because it doesn’t match xdebug.remote_host, turning on remote_connect_back makes it ignore this and accept a connection from anywhere – make sure your dev machine is behind a firewall.
  • Check the ports match – this can get reset by mistake.  You may also need to use 9001 rather than the default 9000 if the latter is also being used by php-fpm on your server.  Also, open the Event Log and look for a message like “Can’t start listening for connections from ‘xdebug’: Port 9000 is busy”. Ports must be set correctly in two places – xdebug.remote_port and PhpStorm’s preferences (Languages & Frameworks > PHP > Debug > Xdebug)
  • You can verify both ends of this, the phpinfo() output will confirm what port Xdebug will send on.  You can verify PhpStorm is actually listening on the correct port with the lsof command (this example from macOS): 
    wt$  sudo lsof -i :9001
Password:
COMMAND    PID USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
phpstorm 80592   wt  330u  IPv4 0xaad56de5076720c3      0t0  TCP *:etlservicemgr (LISTEN)

    If PhpStorm is not listening this will be blank.

B. PhpStorm settings

  • By default Xdebug won’t do anything if no breakpoints were found. Check the Event Log pane – there will be a warning message, e.g. “Debug session was finished without being paused”. Is there one?
  • You may have configured Remote debugging to skip certain paths. In Preferences, check Languages & Frameworks > PHP > Debug > Skipped Paths (there’s no warning in Event Log if a script is skipped.)  Are you trying to verify an AJAX request, when, for example in WordPress, you have previously blocked admin-ajax.php to avoid spawning a new debug session every time autosave is triggered?
  • If PhpStorm is always stopping on the first line of the script but you don’t want it to, note that this option is specified in two separate places – one at the bottom of the run menu (“Break at first line in PHP scripts”) and also in Preferences (Languages & Frameworks > PHP > Debug > External connections)
  • Path mappings can get confusing. The left section is the project files that PhpStorm is looking at.  The column on the right needs to the path on the server – so you have a Vagrant box running on a Mac host, don’t use /Users/<name>/…, use /var/www/…, /usr/share/ etc.  Double check PhpStorm has saved what you’ve entered correctly.
  • If nothing’s happening, make sure all your previous debug sessions have finished. Press the stop button in the debug panel (cmd-F2 on Mac) and try reloading the page again. Also note also the Max. simultaneous connections setting.
  • Have you lost the Debug window, e.g. you minimised it and can’t find it again? Press cmd-5 or hover over the square in the far bottom-left of the screen.
  • Struggling to find the Path mappings dialog? Go to Preferences > Languages & Frameworks > PHP > Servers
  • Common mapping errors: Typically failing to map the document root (e.g. say in WordPress, you’ve mapped wp-admin and nothing else.)

Skipping the Incoming Connection dialog

Note: you might want to set the PHP_IDE_CONFIG environment variable on your server. This tells PhpStorm which path mapping configuration it should use so it doesn’t prompt you.  It needs to be written like this:

serverName=my-server.dev

where my-server.dev must match the name configured in Languages & Frameworks > PHP > Servers – as shown below:

PhpStorm - configuring the server name

PhpStorm’s Debug diagnostic tool

Go to: Run > Web Server Debug Validation (instructions here)

PhpStorm, Xdebug, Docker & Mac

Your Docker containers will have an IP address beginning 172.xxx.xxx.xxx (each container gets it’s own – check what it is)  You might assume that’d be enough to avoid conflicts with your real IP address or 127.0.0.1 when specifying xdebug.remote_host.

Note: on macOS, you need to create a symlink to your IP otherwise PhpStorm won’t be able to hear Xdebug.

  1. Create the alias: 
    sudo ifconfig lo0 alias 10.254.254.254
  2. Put this new address (10.254.254.254) in:
    – your /etc/hosts file (an entry for your project’s hostname)
    – xdebug.remote_host (whether that’s in php.ini or an environment variable in docker-composer.yml)
    – PhpStorm in Preferences > Languages & Frameworks > PHP > Debug > DBGp Proxy > host

Restart everything and things should start working.

Related info:

Small Gravity Forms plugin to resend notifications

Updated Tue 10 May 2016

Gravity Forms doesn’t return or record success or failure of emails, so you may find yourself having to resend them if there was a problem.

It is already possible to trigger notifications for form entries again via the WordPress admin interface, but it requires a lot of clicking should there be very many of them.  Also, although the Directory Columns option allows you to customise the fields displayed, the entry submission date/timestamp is not available here.

Here’s a very quick plugin which uses WP-CLI and the GFAPI to show you a whole batch of entries for a form and filter by start/end date (or date and time).

You can also view a summary of the main notification settings (from/to/reply-to addresses, subject line) for all (or selected) forms.

Full syntax/help is available with:

wp help gftuil renotify
wp help gfutil notifications

Install via GitHub

Fix: WordPress blank admin screen on VVV

If you do sudo apt-get upgrade on a Ubuntu box (e.g. a local VVV development environment) and suddenly find your WordPress Dashboard and admin screens are blank (entirely empty grey background except for the admin bar and left hand navigation – because nothing is being printed below the header), you might well need to do:

sudo apt-get install php7.0-xml

This can be triggered by certain plugins, such as JetPack, needing the xml_parser_create() function, which doesn’t exist without that package.

But the error:

PHP Fatal error:  Uncaught Error: Call to undefined function xml_parser_create() in /srv/www/example-project/htdocs/wp-includes/class-IXR.php:264

…won’t be visible, and you might start removing plugins unnecessarily (because wiping the plugins will seem to cure the problem…)  So I hope that helps.

P.S. when you have something like this, running wp plugin status at the command line (install WP-CLI) is a good idea, as you’ll see all the errors.