Don’t print out too early

We’ve all been there: You’ve happily opened your PHP tag, <?php, at the beginning of the file, at character #1. Your file is going to contain only code, no markup. Perhaps the file is included before any HTML output has even begun.

Being the savvy PHP developer that you are, you know all too well, that if your code were to output even one extra white-space, that would screw up the page’s markup. You’re careful not to use any closing ?> tag at the end of the file, to avoid any mishaps. Even a stray linefeed character could trigger output buffering early, and then out goes any chance for other code to modify the HTTP response headers, among other things.

So now you’re happily defining your functions, classes and other code-y stuff, then all of a sudden, you need to build some markup! Perhaps you’re printing out a UI element, maybe it’s a widget, maybe it’s a shortcode, maybe it’s even an RSS feed or other XML, but in any case, it’s too small for you to define an entire template-part. Your string is going to be some concatenation of hard-coded markup and dynamic data that’s currently sitting in variables.

How To Meet Ladies

Everyone says they know HTML. But HTML is easy to get started with, and hard to master.

When writing HTML markup for a theme or plugin in WordPress, your professional-grade code must fulfill a number of simultaneous requirements. Your main concerns should be to:

• Write correct HTML5 markup that is SEO friendly, using semantic tags where possible (e.g. <nav>, <article>, <aside>, etc).
• Escape any values properly
• Internationalize strings so they can be translated
• Give unique IDs to your elements, and name your classes properly, to assist any CSS and JS assets that go with your markup. Remember, naming things is one of the two hard things in computer science!
• Conform to the WordPress HTML Coding Standards. This is a good standard to follow, because it forces you to be consistent about how to open and close your PHP tags, among other things.
• Depending on use case, optionally add semantic metadata, such as microformats.org, schema.org, Open Graph, ARIA, etc

A concrete example

So let’s say you want to output some HTML form when a shortcode is used. We’ll give the form a unique ID and we’ll also embed some default values, coming from the shortcode’s attributes.

Don’t do this:

You might be tempted to do the following:

$id = uniqid( 'form' );
$html  = '<form id="' . esc_attr( $id ) . '">';
$html .= '<input type="text" name="name" placeholder="' . esc_attr( 'Enter your name', 'langdomain' ) . '" value="' . esc_attr( $atts['name'] ) . '" />';
$html .= '<input type="number" name="age" placeholder="' . esc_attr( 'Enter your age', 'langdomain' ) . '" value="' . absint( $atts['age'] ) . '" />';
$html .= '<button type="submit">' . esc_html( 'Submit', 'langdomain' ) . '</button>';
$html .= '</form>';

Sadly, a lot of people would say this is fine! I can’t blame them too much. We’re all way too used to opening the PHP tag and then never closing it again: we tend to use PHP as if it was Java. And with so many PHP templating libraries out there, it’s hard to remember that PHP is primarily a templating tool.

Do this instead:

We can combine the awesome templating power of the language with some cleverly nested output buffering, and now the above can be re-written as follows:

$id = uniqid( 'form' );

ob_start();
?>
<form id="<?php esc_attr_e( $id ); ?>">

    <input type="text" name="name" placeholder="<?php esc_attr_e( 'Enter your name', 'langdomain' ); ?>" value="<?php esc_attr_e( $atts['name'] ); ?>" />
    <input type="number" name="age" placeholder="<?php esc_attr_e( 'Enter your age', 'langdomain' ); ?>" value="<?php esc_attr_e( $atts['age'] ); ?>" />

    <button type="submit"><?php esc_html_e( 'Submit', 'langdomain' ); ?></button>
</form>
<?php
return ob_get_clean();

To see a somewhat more complete example, here’s the above as a gist:

Notice how we start a new output buffer with ob_start() and how we then get the resulting string with ob_get_clean(). Notice also how we’ve swapped esc_html() with esc_html_e() and esc_attr() with esc_attr_e(). Similarly, we would swap sprintf() with printf(), checked( $value, true, false ) with checked( $value, true ), and so on.

PRO TIP: If your code throws an exception, you can use ob_end_clean() in your catch clause to cancel your buffer.

“Why does it even matter”, you ask?

Well, there’s a few advantages with the second form of our, err…, form!

• Readability. I find the second piece of code to be much more readable.
• Syntax coloring. Yes, some editors do perform HTML parsing and show visual queues related to the syntax of HTML inside strings. But not every editor does this, and the ones that do, cannot do this perfectly.
• No quote hell. No need to count opening and closing ' characters, interpolated with " characters while printing HTML attributes. This business can quickly get confusing, and is a common source of errors.
• Show off your mad PHP output buffering skillz! Your average front-end developer will be astonished at your professional-looking code!

Now, if only we were allowed to use shorthand PHP tags, our code could be even nicer. Sadly, we can’t.

?>

The post 💩 Please, WordPress theme and plugin developers, learn to write proper HTML already… smh appeared first on Alexandros Georgiou.

First, some theory

In a fantasy world where unicorns poop chocolate fudge and everything is awesome, it all goes down somewhat like this: You talk with the client or end user, and you gather up a list of things they want. You collect and number these in a requirements document, braking them up into Functional requirements, Non-functional requirements, and other Design constraints. Then, you design a solution, write your tests, and implement your code. Once all of the requirements in the document are met, you are done, and you get paid. Easy! Deviate from this simple methodology at your own peril. (Oh, and you also then need to maintain, fix and improve the code you’ve written.)

As a software engineer, you should know that in addition to what the client asks for, there are always implicit requirements. For example, your code must be readable and maintainable, and it must be reliable (read: not too buggy). All of these are aspects of code quality. A client or end user will never ask you for these, but you should have them in your list of non-functional requirements.

Professional developers write simple, clear code where a novice would write complex, intricate code to solve that same problem. Sure, a lot of this is just a matter of practice and experience.

Dev tools can help you with code quality whether you’re novice or pro. They help you discover issues that you don’t know about, and they help you discover issues that you do know about, faster!

If you are developing themes or plugins, here’s two tools that you definitely want to use as a professional WordPress developer:

Improve WordPress PHP code smell with CodeSniffer

There are some styling guidelines that all WordPress developers should follow. Especially if you are aspiring to upload your code to wordpress.org, or to the Envato Market (ThemeForest or CodeCanyon), then you definitely want to follow these guidelines. Generally, these get encoded into your muscle memory pretty quickly, but it’s always a great idea to have a tool like PHP CodeSniffer that double-checks your code style.

On my Ubuntu machine, I was able to install PHP CodeSniffer easily with:

sudo apt install php-codesniffer

Then, it’s just a matter of loading the WordPress-specific set of rules. Go to your home directory and clone the project:

git clone https://github.com/WordPress/WordPress-Coding-Standards ~/wpcs

And tell CodeSniffer the location of these rules:

sudo phpcs --config-set installed_paths ~/wpcs

Check that the new rules are added into CodeSniffer with:

phpcs -i

Congratulations! You can now check your plugin for code style with a command such as:

phpcs --standard=Wordpress-Core /path/to/source/code/root/dir

If, like me, you’re using grunt for your build process, then there’s a nifty Grung plugin, grunt-phpcs. Just make sure to specify WordPress-core as the rule set. Here’s a grunt target that you might use:

phpcs: {
    plugin: {
        src: ['src/**/*.php']
    },
    options: {
        bin: '/usr/bin/phpcs',
        standard: 'WordPress-core'
    }
}

Run it against your code and you will get a number of improvement suggestions. Some of these can be applied automatically with PHPCBF (the PHP Code Beautifier and Fixer), or you can go through the list manually and apply each suggestion as you see fit. Many of the suggestions will be related to code indentation, but you will also see a large number of other suggestions that are more critical.

Improve WordPress PHP code correctness with phan

PHP is a very lenient language. It will let you get away with murder. This is something that novice programmers often enjoy. For professionals it’s a nightmare, as it makes spotting errors harder. PHP has thus gained somewhat of a notoriety for being a bad language, and is the butt of some clever jokes.

This isn’t something to worry about. It has happened to many respectable languages, including JavaScript. So nowadays we have use strict, which lets us only use The Good Parts of the language. You can do something similar with PHP.

My point is that static code analysis is not the hero you want, but it’s definitely the hero you deserve. Enter phan:

First, install it. It’s straightforward to install phan with composer:

composer require phan/phan

Now phan lives in your project’s vendor/ dir.

Next, create a configuration under your project dir, in .phan/config.php. This will tell phan what settings you want to run it with. Start with the example given here, and set your source code directories.

You will also want to point to some third-party code, including the directory of your WordPress installation, since your code will invariably use WordPress functions and types.

You can also use this config file to exclude some rules, so that phan does not check for them. Here’s the complete list of phan plugins.

When all is set, you can call phan on your code with:

vendor/bin/phan

I don’t care how pro you are, you will definitely get a list of suggestions on how to improve your code.

Conclusion

Using phpcs and phan together, you will avoid a large number of errors that would otherwise likely go undetected. These include errors with translator comments over strings, phpDoc formatting errors, variable type errors, errors related to sentinel values such as null, and array indexing errors.

Always use these two tools together with phpunit when you write code. You will write more readable, maintainable, correct and robust code that you can feel confident about.

The post 💩 Your WordPress PHP code stinks! Here’s why. appeared first on Alexandros Georgiou.