Debugging and Problem Solving

The WPSSO Core plugin follows all recommended WordPress coding practices, but on occasion, it may break other themes and/or plugins that do not.

If you haven’t used the Query Monitor plugin yet, I would strongly suggest you install and activate this very useful plugin. The Query Monitor plugin will highlight any PHP or database query issues, both on the front and back-end. It may not catch all errors (like Ajax queries, for example), so you may also want to define the WP_DEBUG constant as suggested below.

Since the advent of “page builders” and the new block editor in WordPress v5, JavaScript / jQuery errors have become more common and not easily diagnosed using standard methods, like using the WP_DEBUG constant (see bellow) and the Query Monitor plugin. To view JavaScript / jQuery related errors, you must enable your web browser’s console, and how you do that depends on the web browser you use (see this Google search result for more information on that). It’s definitely worth enabling your web browser’s console to make sure there are no JavaScript / jQuery errors. If there are, you can select the error, then copy-paste the error text into a new support ticket (please do not submit screenshots as we cannot work with text in an image).

WordPress Content Filters

Related FAQ: Why are some HTML elements missing / misaligned / different?

WordPress allows plugins and themes to hook hundreds of different filters to manage content, some of which are used by WordPress to expand shortcodes, for example. WordPress generally calls a filter (like ‘the_content’) once to expand text for a given post within the loop or a single webpage. As a consequence, some authors mistakenly assume that a filter they have created will only be executed once for a given post, and only within the webpage body or specific area. WordPress filters are available to any theme or plugin that needs to expand text (title, excerpt, content, etc.), and in any context (header, loop, widget, admin, etc.). WPSSO Core uses ‘the_content’ filter to locate media elements within the content and to provide complete and accurate description meta tags.

See the “Is your filter going to break the layout?” post on the Make WordPress Plugins blog for additional information on the use (and common misuse) of ‘the_content’ filter by developers.

Under the SSO > Advanced > Content and Filters tab, you can uncheck the “Use WordPress Content Filters” and “Use WordPress Excerpt Filters” to see if your problem is related to a WordPress filter hook. If unchecking these options fixes your problem, you should determine which plugin/theme is at fault and report the issue with the plugin/theme author. Using the WordPress apply_filters() function should not break a theme and/or plugin.

If you disable the content filter, and your Post / Page content relies upon shortcodes for its text, then you may find that WPSSO Core cannot create accurate description meta tags (or any description text at all). WPSSO Core looks for a custom description and excerpt before falling back to using the content text. In the case where content filters are disabled, and the content uses shortcodes for its text, then you may have to enter an excerpt and/or custom description for those Posts / Pages.

Since WPSSO Core uses the custom description and/or post excerpt before falling back the content, using a custom description and/or excerpt for a few Posts/Pages could be another alternative to disabling the content filter for the whole website.

WordPress and PHP Error Messages

Turning on the WordPress debug log can be highly illuminating — your theme and plugins may be generating hundreds of errors, that you would never see unless you turn on the WordPress debug log. To enable the WordPress debug log, without displaying the errors to your visitors, add the following to your wp-config.php file. Make sure you do not already have a define() for WP_DEBUG in your wp-config.php file (constants can only be defined once). If you do, you can safely remove it and replace it with the following lines.

You can turn on/off the WordPress debug log by changing WP_DEBUG‘s value from true to false.

The debug messages will be saved in a wordpress/wp-content/debug.log file by default. If you have several badly coded and/or old plugins and themes that generate a lot of errors, then also make sure you clear the contents / rotate this file regularly, as it could grow large enough to fill a filesystem. In all cases, you should endeavor to resolve all warnings and errors in the debug.log file — the debug.log file should remain empty — always.