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.

Have you tried POT?

Hopefully you’ve already used the i18n functions in your PHP code. For example, a simple translatable string would look like:

$text = __( 'Text to internationalize', 'language-domain-slug' );

The purpose of this article is not to list all the relevant functions, you can look them up here. These are all wrappers to gettext.

The important thing to note is that you need to run something to generate your Portable Object Template files. These .pot files can then be copied to Portable Object .po files, then translated to Machine Object .mo files. These .mo binaries are finally loaded by the end user’s WordPress installation to provide the translated strings to the plugin, or theme. No surprises up to here, all of this is standard.

Grow your own with Grunt!

What I will present today is an easy way to use grunt to generate the following:

1. Two .pot files, one with the front-end strings and one with the admin area strings, and
2. .mo files for any .po files in your project

You will still need to copy the .pot files to .po files manually and provide the translations. Let’s get started:

The first thing to add to our Gruntfile.js is grunt-wp-i18n. This is a grunt plugin that I have found to be a little more flexible than the alternative, grunt-pot. So, as usual, add this grunt plugin to your dev toolbox:

npm install grunt-wp-i18n --save-dev

grunt.loadNpmTasks( 'grunt-wp-i18n' );

makepot: {
    front: {
        options: {
            cwd: 'build',
            potFilename: 'myplugin-front.pot',
            include: [ '/path/to/files', '/more/files', '/etc' ],
            domainPath: 'languages/',
            type: 'wp-plugin'
        }
    },
    admin: {
        options: {
            cwd: 'build',
            potFilename: 'myplugin.pot',
            include: [ '.*' ],
            exclude: [ '/path/to/files', '/more/files', '/etc' ],
            domainPath: 'languages/',
            type: 'wp-plugin'
    }
}

Make pot

grunt makepot

This will make two files in your project, /build/languages/myplugin.pot and /build/languages/myplugin-frontend.pot. Do not commit these files, we’ll let them auto-generate every time. The /build directory is in my .gitignore list.

Using pot

cp build/languages/myplugin-front.pot src/languages/myplugin-front-de_DE.po
cp build/languages/myplugin.pot src/languages/myplugin-de_DE.po

cp build/languages/myplugin-front.pot src/languages/myplugin-front-ar.po
cp build/languages/myplugin.pot src/languages/myplugin-ar.po

We’ll use another grunt plugin, grunt-po2mo. First add it to your project:

npm install grunt-po2mo --save-dev

And add the following into your Gruntfile to load it:

grunt.loadNpmTasks( 'grunt-po2mo' );

This one requires very little configuration. Add the following target into your Gruntfile:

po2mo: {
    plugin: {
        cwd: 'src',
        src: 'languages/*.po',
        dest: 'build',
        expand: true
    }
},

This config expects that the .po files are in the /src/languages directory where we placed them earlier. It places the .mo files in the /build/languages dir. All you need to do for this is:

grunt po2mo

You will also need to tell your plugin to actually go and use these .mo files. Easy. Just hook to the plugins_loaded action and load the text domains:

function action_plugins_loaded() {
    load_plugin_textdomain( 'myplugin', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' );
    load_plugin_textdomain( 'myplugin-front', false, dirname( plugin_basename( __FILE__ ) ) . '/languages/' );
} // end function action_plugins_loaded

add_action( 'plugins_loaded', 'action_plugins_loaded' );

That’s it!

Make sure to include the makepot and po2mo targets in your build task. Finally use grunt-contrib-compress or another plugin to compress your entire build directory to a .zip file that is ready to be installed into WordPress!

Pass it on.

The post 😛 How to make pot with WordPress appeared first on Alexandros Georgiou.

No matter which tool you’re using, building, testing, packaging and deploying a WordPress plugin should be one command. That way when you’re dev testing, you are actually testing the whole process, including installation, activation and deactivation of the plugin’s zip file. grunt-shell and wp-cli are your friends. Use wp option liberally in your dev deployment code.

My Gruntfile.js describes all the steps needed between my code sitting in my working directory and the same code running in my WordPress dev environment.

Grunt alias tasks let you define this process hierarchically. Use them! I aim to model the process so that at some level it has some resemblance to steps from the waterfall model: build, package, test, and deploy are verbs that I always aim to define in my script. Then, at a lower level I can define which grunt plugins actually accomplish each step.

When you have defined the steps in this way, then you can begin to create builds of varying quality or for various purposes. Testing takes too long to run every time in your development cycle? Create a quick build that excludes it. Want to have separate builds with and without documentation included? Define another package verb. Want to create a deliverable package but not deploy it? Create a task that omits the deploy verb.

The following is from an actual project I’m working on. Don’t worry about the details. You have your own workflow. All I’m saying is that you will benefit from structuring your script hierarchically.

Here’s my increasingly verbose meme. Make it viral!

The post 🐗 Building WordPress plugins with an increasingly verbose Gruntfile appeared first on Alexandros Georgiou.

Monetizing WordPress software

WordPress is such a fun platform to work with not so much for its core features, but due to its vibrant ecosystem of themes and plugins.

On WordPress.org there’s a ton of high-quality software that you can use for free (they’re all GPL), and they cater to seemingly every need you can think of. This is perhaps the software channel with the largest exposure since it is integrated into the WordPress admin screen.

Envato is a very successful software market where developers can charge money for their themes and plugins, but there are strict rules for admission and the distribution channel does the pricing; not the developer. The channel also takes a huge cut which currently ranges from 50 to 70 percent depending on whether you give them exclusive rights over your creation.

Or you can buy access to a whole bunch of plugins from developer teams that have put a lot of stuff out there, such as WPMU DEV. Even factoring in the support and documentation you get, the prices you pay are very low.

Very few plugins will cost you a price higher that a two digit amount of US dollars. So who makes these free, or dirt-cheap themes and plugins, and how do they get paid for their work?

Just do a google search on WordPress and business models, and you will come across articles from developers who discuss their experience on how they monetize on their work. I feel that this article sums it up nicely:

So it turns out there are a bunch of way to make money selling your WordPress software. Today I’m going to focus on the simplest and perhaps most popular way:

The Freemium model

It’s all a numbers game. Sure, you might be selling your plugin for only a few bucks, but if a million people buy it, you’re rich. After all, a very very large percentage of all websites on the Internet run WordPress. That looks like a huge market. Surely even the slimest slice from that pie should be big enough by your standards?

Not so fast, though. How feasible is it to reach large numbers of people? Having built a good and robust product, on its own, is a good start, but you need to do more. You have to think of how to reach your customers, and how you will convince them to:

1. look at your product,
2. decide to use your product, and
3. reach into their pockets and pay you for your hard work.

Think web marketing and promotion. Think exposure to the right channels. Think social media. Think landing pages and variable pricing, and promo codes and “growth hacking” and all that good stuff. How you go from having a product to having money in the bank is your business model. Your strategy. The Freemium model is a tried and true model in the WordPress world.

A portmanteau of “Free” and “Premium”, this model is what it says on the title: You build a product that is high-quality and fully functional. If it solves a real need, with the right kind of promotion you will have a chance of reaching large numbers of users. That’s step 1.

Don’t rush into asking for money at this stage. Nobody will be willing to pay for your product at first. Not even a dollar. Website developers and administrators these days are pandered with absolutely too many high-quality freebies out there. It’s a large Internet and competition is fierce.

At least, they won’t pay with money. But if they choose to give your free product a try, they will have to pay with their valuable time. Even the easiest piece of software takes you a few minutes to install, configure and figure out. You need to convince your potential customer that what they get for free is worth 5 or 10 minutes of their time, or they will spend those 10 minutes trying out someone else’s product.

Once you’ve done all that, you will begin to build a user base. Now it is out of that user base that you can begin to hope that a small percentage will maybe pay a small amount. These dedicated users of your community will pay for everybody else’s free ride.

Source code maintenance

So you have a free edition of your product, plus a premium edition that does all the stuff that the free does, plus a few more features. These features are not absolutely necessary for beginers, but that will come in handy to a few of your most dedicated users. You will have to put the free edition on software channels with high exposure, create some noise around them, and put the premium edition behind some kind of paywall or restricted area. In that same area you might offer support and additional freebies, and perhaps even a community for your users.

How do you maintain this? Surely you don’t want to have two copies of your source tree. That’s a maintainer’s nightmare. You don’t want to duplicate any code. But you do want to have variations between the two release types. Perhaps there is some placeholder text or popup in the free version where the premium feature is missing. You will want to add links to a landing page where users can purchase your premium version. In essence you have two products that are similar in some ways, but not exactly the same. And users who have the free edition installed might be baffled if they buy and install the premium edition and it clashes with their free installation, due to some namespace clash.

The solution that I prefer the best is to use a source code preprocessor. Preprocessors are tools that do stuff with your source before it runs or gets packaged. Let’s look at your requirements and how a preprocessor meets them:

• You want to be able to include files conditionally into your deliverables. Perhaps this or that directory only goes into the Premium edition.
• File-level granularity will probably not cut it on its own, though. You will have large files where only a few lines will change between editions. You want to be able to say “if i’m building the free edition, include this code segment in the build, else include that code”. So you need to be able to use inline conditionals into your code.
• You want to be able to insert variables into your code that are different for each of your multiple editions. Your welcome message might be something along the lines of “thanks for downloading xyz free” versus “thanks for purchasing xyz premium”. Keeping the title of xyz in a preprocessor variable will com handy.
• Also remember that you will not only need to do this in PHP code. Think CSS and JavaScript. In my case, I produce documentation with Markdown. So you need something that works well across multiple languages.

Readers of this blog will know how much I love Grunt. Grunt is something that in my opinion you should already be using in your project for all kinds of automation. I guess you could get away with plain old shell scripting or some other build tool, but you will definitely want to automate some tasks such as testing, building, producing documentation, packaging and releasing.

I have split my project into the following directories which represent the workflow from source to deliverables:

• /src — I keep my source code here. This is just an assortment of PHP, JavaScript and CSS magic, as well as a few binary assets. The codes are sprinkled with preprocessor directives that grunt-preprocess will understand. This is a grunt plugin that meets the aforementioned requirements very well.
• /doc — Here I keep my documentation in Markdown format. Read this other article I wrote on how I use grunt and pandoc to convert it into PDFs. Again, there is very little duplication here thanks to preprocessor directives.
• /build/free and /build/premium — This is where the output of the preprocessor dumps the processed code and documentation. Some generated data files that contain lists of fonts are dumped here too. I use grunt-shell to run arbitrary linux commands and write the output here. I keep these to a minimum, since the preprocessor does a lot of the dynamic stuff. I also dump here my translation files.
• /package/free and /package/premium — This is where the source code is zipped. I use grunt-contrib-compress to produce a WordPress plugin in installable .zip form. Also, pandoc dumps the PDF documentation here.
• /deliverables — You might think that the product has been through enough steps by now, but you’d be wrong. The end deliverable is more than just code. So finally I have grunt-contrib-compress zip up the plugin’s .zip file and the PDFs into a final .zip file, once for each edition, free and premium.

Simply typing grunt on my command line will test and do all of the above. It will also use wp-cli to install and activate the plugins into my development environment so I can manually test.

Deployment considerations

I’m going to leave you with some code that makes sure not both editions are activated in your freemium plugin. It showcases the deactivate_plugins() function and at the same time gives you a taste of what it feels like to use preprocessor directives in your code. Enjoy!

<?php
/*
 * Plugin Name: // @echo name
 * Description: // @echo description
 * Version: // @echo version
 * Plugin URI: // @echo homepage
 * Author: // @echo author
 * Author URI: http://alexgeorgiou.gr
 * Text Domain: myplugin
 * Domain Path: /languages/
// @ifdef FREE
 * License: GPLv2 or later
// @endif
 *
 * @package myplugin
 * @since 1.0.0
 */

// don't load directly
defined( 'ABSPATH' ) || die( '-1' );

if ( ! class_exists( '/* @echo class */' ) ) {

    final class /* @echo class */ {

        // @ifdef PREMIUM
        private $_disabled_notice = false;

        private $_must_disable_notice = false;
        // @endif

        private function __clone() {
            // Cloning disabled
        }

        private function __construct() {
            set_error_handler( array( __CLASS__, 'error_handler' ) );
            
            // more stuff here

            // @ifdef PREMIUM
            add_action( 'admin_init', array( &$this, 'action_admin_init' ) );
            add_action( 'admin_notices', array( &$this, 'action_admin_notices' ) );
            // @endif

            // more stuff here

            restore_error_handler();
        }

        // @ifdef PREMIUM
        
        /**
         * Makes sure that free and premium editions are not both installed.
         */
        public function action_init() {
            set_error_handler( array( __CLASS__, 'error_handler' ) );

            // Disable free if free and premium are both installed
            if ( class_exists( '/* @echo pkg_name */_premium' ) && class_exists( '/* @echo pkg_name */_free' ) ) {
                if ( current_user_can( 'activate_plugins' ) && function_exists( 'deactivate_plugins' ) ) {
                    $plugin = plugin_basename( __FILE__ );
                    // @ifdef PREMIUM
                    $plugin = str_replace('myplugin-premium/', 'myplugin/', $plugin);
                    // @endif
                    deactivate_plugins( $plugin );
                    $this->_disabled_notice = true;
                } else {
                    $this->_must_disable_notice = true;
                }
            }

            restore_error_handler();
        }

        public function action_admin_notices() {
            set_error_handler( array( __CLASS__, 'error_handler' ) );

            if ( $this->_disabled_notice ) {
                echo '<div class="notice notice-warn is-dismissible"><p style=\"font-size: larger;">';
                echo '<strong>' . str_replace( '_', ' ', __CLASS__ ) . ':</strong> ';
                echo __( 'Thank you for installing the premium edition of this plugin. ' );
                echo __( 'The free edition has been deactivated.' );
                echo '</p></div>';
            }

            if ( $this->_must_disable_notice ) {
                echo '<div class="notice notice-error is-dismissible"><p style=\"font-size: larger;">';
                echo '<strong>' . str_replace( '_', ' ', __CLASS__ ) . ':</strong> ';
                echo __( 'Thank you for installing the premium edition of this plugin. ' );
                echo __( 'The free edition of the plugin must be deactivated, but your account lacks the necessary priviledges. Please ask the site administrator to disable it, or delete the directory <code>wp-content/plugins/myplugin</code> using FTP or some other means.' );
                echo '</p></div>';
            }
            restore_error_handler();
    }
    // @endif
}

The post Developing and maintaining “freemium” WordPress plugins appeared first on Alexandros Georgiou.

• Text-based documents are much more friendly to revision control systems than, say, Microsoft Word documents or even LibreOffice Writer documents.
• Markdown is convenient. 90% of the time it is all you need.
• LaTeX is powerful. You can use it for that other 10% of the stuff you want to do. But you don’t want it to get in the way every time you start a new section or add a hyperlink.
• JavaScript is even more powerful. Thanks to grunt you can link variables from your project’s metadata into your text. Think names and version numbers. When your project’s metadata change, your documents reflects this. If this is not cool, I don’t know what is.
• All of this can be nicely integrated to your build process. I will show you how I did this using grunt, grunt-contrib-watch, grunt-panda, and a dual monitor PC for a near-WYSIWYG authoring experience. Read on!

RTFM in the third millennium?

Generally speaking, software documentation is a thing of the past. Most end-user software does not come with instructions any more. The reason? Most end-users do not read the instructions. (This is why engineers had to come up with the acronym RTFM. But users have their own acronym: TL;DR!) So the fact remains that users don’t read instructions, even if they are right there on the screen, let alone in a separate PDF file on their computer. If the UI is not intuitive enough for them to figure out how to do something, users will do one of the following:

1. Switch to some user-friendlier piece of software.
2. Ask their children or grandchildren to figure out how to do it. Depending on availability.
3. If all else fails, they might go ask a question in a user community such as a forum, issue tracker, comment section, twitter, etc. This is the ideal user.

Users will crawl on broken glass to avoid intentionally learning something new. Users will never read your documentation, not even at gunpoint.

But there still are, and always will be, cases when you do need to produce documentation for your software. For instance, your intended audience might be technically minded. Or you might be explicitly required to produce a User’s Manual. Envato for instance is a platform that asks from its contributors to include a manual with themes and plugins. This makes sense, because users of themes and plugins are often technically minded themselves. They might even find it welcome to know that if all else fails they can dive into a manual and find the solution to their problem. It’s all a matter of perspective.

How pros create PDFs

Traditionally, whenever they dabble in typography, computer geeks such as ourselves have been using LaTeX, an evolution of Donald Knuth’s TeX. In addition to the immense power of TeX, there is also the advantage of the esoteric syntax which makes you feel like a l33t h@xor when you use it. In fact the language is so complex that there is an entire stackexchange QA site devoted to it: http://tex.stackexchange.com/.

Purists might argue that easier is better. Bah! As a geek who enjoys assembly code and Perl, I tend to disagree, but I see their point: Pressing deadlines leave little time for you to play with TeX when fancy word processors are at your fingertips. But as a programmer you really don’t want to be using binary files in your revision control system. They don’t diff well. Hence people nowadays use Markdown, which is very easy to write and can readily be transformed to HTML, PDF, etc. albeit at a loss of expressive power.

If you enjoy such handy features as unicode support and using your own fonts, you might decide to use XeTeX and its XeLaTeX compiler instead of LaTeX.

pandoc

Enter pandoc. Pandoc is really cool, so you’ll want to install it:

sudo apt-get install pandoc

Here’s how you’d convert your markdown document to a PDF using XeTeX:

pandoc readme.md -o readme.pdf --latex-engine=xelatex

Easy. Pandoc silently converts the markdown to LaTeX and then spares you the usual complexity of converting LaTeX to DVI, DVI to PS, and PS to PDF. In goes markdown, out comes PDF. Magic!

grunt

Since pandoc is a thing that exists in this world, naturally there must be a grunt plugin for it, right? Correct. It is called panda. You’ll need to install it in your grunt project as a dev dependency with

npm install grunt-panda --save-dev

and then also load it in your Gruntfile.js:

grunt.loadNpmTasks( 'grunt-panda' );

You’ll want to read the panda README for details, but this is what one might do to convert a markdown document into PDF:

 panda: {
   doc: {
     options: {
       process: true,
       pandocOptions: "--latex-engine=xelatex"
     },
     files: {
       'build/readme.pdf': [ 'docs/readme.md' ],
     }
   }
 },

If you want to control your LaTeX headers or other document metadata, you can prepend your markdown code with YAML headers.

---
title: '**<%= pkg.name.replace(/_/g,' ') %>** **<%= pkg.version %>** user manual'
author: 
- name: '<%= pkg.author %>'
header-includes: |
 \setmainfont{Arial}
abstract: |
 This paragraph is an abstract that briefly talks about this software manual.
---

= Introduction

_Hello_ PDF world!

Check out how I defined the title of the document and author name using grunt-flavored JavaScript. The values come from my package.json file. All of this is possible thanks to panda’s option process: true. Since JavaScript is turing-complete, you could potentially go full meta in there and generate chunks of your document dynamically. Please don’t do that! :-p Here I just replace underscores with spaces in the pkg.name field.

You can go on and use LaTeX syntax, Markdown syntax and <%= %> tags throughout the document. The only downside is that if you do something really really funky, panda might fail silently. In that case, simply attempt to convert the file manually using pandoc, as we saw before. You will then get error messages from the xelatex engine that will point you in the right direction.

WYSIWYG

Once you’re satisfied that calling grunt panda does indeed generate your documents, why not sprinkle some grunt-contrib-watch on top of it all?

 watch: {
   docs: {
     files: [ 'docs/**/*.md' ],
     tasks: [ 'panda' ],
     options: {
       spawn: false,
     },
   },
 },

Aaah nice. Now whenever you save changes to your markdown, the PDF is regenerated. If you’re on Linux, I recommend that you open the PDF with Evince, which is usually the default PDF viewer in Gnome desktops. It has the nice feature that it auto-reloads a PDF that has changed on disk. Slide the window to your second monitor, and leave grunt watch running. Now you can edit your Markdown/LaTeX/JavaScript source and see the result almost in real time.

The post Create PDF documentation like a pro appeared first on Alexandros Georgiou.