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.

Ten Things Every WordPress Plugin Developer Should Know

Actually you’ll probably want to read this before even starting your project; but better late than never! It’s packed with essential info that you should know. If you’ve missed any of the info in this article, go back to your code and fix it. There’s stuff about common practices, coding standards, etc.

PHP Coding Standards

This is a list of PHP coding standards that WordPress developers follow, both in core and in themes and plugins. It’s a requirement for submission to wordpress.org but it would be really nice to follow as many of these as possible even if you’re not planning to submit your code there.

Ideally you’ll want to use some tools for this. A quick search on GitHub reveals a number of syntax checkers. Here’s one that I use with Eclipse: https://github.com/edpittol/wordpress-eclipse-formatter, and another one for CodeSniffer (which can integrate nicely with a number of IDEs): https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards.

Whatever you use, it doesn’t hurt to double check your code one last time. In Eclipse Formatter for instance, there is no way to check for “Yoda” conditions as far as I know, so you’ll want to manually check for those if you’re using it.

JavaScript Coding Standards

Have you checked your PHP code for compliance to the coding standards? Good! Get ready to do it again, this time for your JavaScript files; at least the unminified copies of them. Here’s a project that uses ESLint to help you enforce the standards: https://www.npmjs.com/package/eslint-plugin-wordpress. If you have a lot of JavaScript in your code, it might pay to integrate this into your pre-build checks, but as with PHP, always have one last look using your eyeballs.

WordPress plugins

If you’re writing a plugin, this is a short list of conditions that your project must meet before you publish to WordPress.org. It has more to do with functionality than standards, and essentially it’s about not being evil with your code.

Detailed Plugin Guidelines

This is essentially a longer version of the above. A definite must read if you’re publishing to WordPress.org. It’s about licensing, versioning, what you can and can’t do, etc.

Theme Review Process

If you’re writing a theme that you plan to publish to WordPress.org, check that it at least conforms to all the required items and try to conform to as many recommended items as possible. The write-up for the recommended guidelines is not complete as of the writing of this article, but there’s some very useful guidelines in there.

Theme Unit Test

Again, if you’re writing a theme for WordPress.org, you will also want to check a number of things against the provided Theme Unit Test. It’s probably a good idea to do this even if you’re publishing elsewhere.

ThemeForest General File Preparation Guidelines

If you’re publishing to ThemeForest, you will have to follow these guidelines on how to bundle your files.

WordPress Phase 1 Submission Requirements – Q&A

This is a list of guidelines to follow before submitting to ThemeForest. There’s a number of things listed that are not allowed, so make sure to check.

A step-by-step guide to the upload process

When uploading to ThemeForest, you will also want to follow these guidelines. They are mostly about the upload process but also include some information about how to bundle your files.

Professional WordPress: Design and Development

Finally, this is a book, not an actual checklist, but still I recommend that you at least glance through the table of contents. I’ve found this book very helpful. It covers all topics related to WordPress development and it’s very likely that whatever it is you’re trying to do, there might be a better way of doing it. WordPress is a complex system and it’s only getting more complex by the day.

My recommendation is that you go through the table of contents and read any chapter that talks about things you do in your theme or plugin. There are things you might have missed.

Too meta? Perhaps! But no matter what and where you’re publishing, if you want to be professional about it, don’t assume you know everything. At least glance through all of these guidelines.

The post ☑ WordPress checklists to go through before publishing a theme or plugin appeared first on Alexandros Georgiou.