Posted on

Netbeans, phpDoc, and WordPress

A posting from our private “Tech List”, a list I share with select tech geeks mostly from the days at Cyber Sprocket Labs.   We tend to share high end tech tips that only geeks would find interesting.    I am posting here for easy reference for “The Tech List” groupies.

My Intro To Netbeans

9 months ago Chase was showing me NetBeans on his desktop.   It had some cool features for PHP like auto-complete and some very handy code lookup tools that reminded me of Visual Studio without all the weight.

 I wish I had learned about the NetBeans environment a long time ago.    NetBeans+ GitHub + SmartGit have made my coding at least twice a productive when it comes to PHP work, especially with complex WordPress plugin code.
In the past few months, while working in NetBeans, I’ve been refining my phpDoc skills.  This is EXTREMELY handy in making coding far more productive.    Here are some of the things I’ve learned that I wish we had all known about at Cyber Sprocket.    With the right tools it makes coding for people with senility (me) easier.

Effectively Using Netbeans for WP Dev

1) Wrap your ENTIRE plugin into a single instantiated object.
My plugin invocation now is basically something along these lines:
DEFINE(blah,blah) // a few of these help with WordPress stuff, like plugin version
class MP {
class MP_Error extends WP_Error {}
add_action('init', array('MP','init');
That is pretty much it other than the singleton.
2) Learn how to create and use singletons PROPERLY in WordPress
It must be a static method.
It should return itself as an instantiated object.
Set minimal properties as needed, not the entire WPCSL object here.
public static function init() {
    static $instance = false;
    if (!$instance) {
        $instance = new MP;
    return $instance;
3) phpDoc the class
In netbeans you go back to just above class MP {} and type /** after starting the frame of the class with properties and methods in place.
It will AUTO-CREATE the template PHP docs.
First line of comment = 1 line description
Lines 3..m = a longer description if you’d like
Lines m+1..n = the properties defined with @property, @property-read, @property-write    (the setters/getters with r/w, r, w status)
These property lines, like variable lines are simple:
@property-read <type> name  description
for example
@property-read string plugin_name the plugin name
This indicates a read-only property for the object.
4) phpDoc the methods
Like classes, but NetBeans is even better with the docs, you write the function first.   Then go before the function foo() line and type /**.   NetBeans will create the entire phpDoc template.   You update it to give it the “hints”.
This is something I use a LOT now and you’ll see why in a moment.   Here is an example from WPCSL_Settings add_section:
Old school:
* method: add_section
* does stuff
* params:
*     [0] - named array, blah blah
 * Create a settings page panel.
 * Does not render the panel.  Simply creates a container...
 * <pre><code>
 *   $mySettings->add_section(array('name'='general'));
 * </code></pre>
 * @param array $params named array of the section properties, name is required.
5) If your phpDoc property/variable type is a specific OBJECT then NAME THE OBJECT. 
For example:
class MP {

    * The WPCSL settings object, shortcut to the parent instantiated object.
    *  @var wpCSL_settings__mp
    private $wpcSettings = null;


Why I Am More Productive

Now here is why all these tips with phpDoc are useful and how I’ve slowly made my coding at least twice as efficient.
NetBeans defaults to having code hints and auto-fill turned on.   The cool part about this is it will do a few things like tell you when a required param is missing and flag the line as an error, the same way it does with blatant PHP syntax errors.    If you are creating some new code and you pause for a second with a partially written invocation then it will show you the possible options from a list of PHP functions, custom functions, or methods from objects you’ve phpDoc’ed properly.
Thus, I do something like this:
$this->wpcSettings->a   <pause>
It now shows me all the methods and properties in the WPCSL Settings Class that start with a in an in-place drop down list.
I cursor down to add_section and pause.
It shows me the full documentation on the method including my code example, the required parameters and more.
I press enter, it drops the completed method along with the first prototype in place, I cursor down to select from the various templates, for example if secondary parameters are optional, press enter and if fills out the entire code block.
I then modify the prototype to fill in my settings and I’m done.
If you do this right you can be ANYWHERE in your code as deep as you need to be.   You never have to go looking for the source, especially if you’ve written decent phpDoc comments.
I used to find myself split-screen looking at the source method or property code to see what it did or how it worked.    Now I spend time documenting the methods or properties in a verbose phpDoc comment and I never have to look at the code again.

Key Points

If you do NOT wrap everything inside a parent class it takes a lot longer to pop up the help.
If you just use the lazy @property object $myvar (or ‘mixed’) syntax you do not get to see all of the methods whenever you newly instantiated object is referenced by the variable name.
If you use things like public, private, setters, getters and use the matching phpDoc elements like @property-read  then NetBeans warns you if you do something illegal like try to directly SET that property.

A Day Older, A Day Smarter

I know some of you probably had productivity helpers like this while at Cyber Sprocket, but if I had known then what I know now I’d have been insisting that we all learn and properly implement phpDocs as our commenting standard.
An as you all know the other “freebie” with this is I could easily generate a full HTML (or markdown) site with all the classes, methods, and properties of any plugin with a few short commands.   I’ve not done that yet but will play with that sometime in the near future.    I need to figure out how to bake it into WordPress content at but I think it would be cool to have an entire plugin + wpCSL documented in an easy-to-browse format on the web.
Posted on

Tab Completion for Custom Commands

A lot of commands in Emacs take input from the minibuffer, the little one-line area at the bottom of the editor. When you are writing your own commands you will often make use of the same facility. In this article I want to show you one way of doing that which will provide tab completion for your custom functions.

I’m going to use a simple example out of my own dot Emacs file. This is the function that was in my last email, my function for opening org-mode log files. I keep one org-mode file for each project, in a log directory, split up by year. So I wanted a simple command I could bind to a key that would let me type in a project name and open the file. So I have this:

(defun open-project-log-file (project)
      "Opens a log file for a project."
      (interactive "sProject: ")
      (find-file (concat "~/Documents/Logs/2010/" project ".org")))

Then when I press C-H-x l I get the ‘Project:’ prompt in the minibuffer. I type in something like ‘Foo’, press Enter, and there’s my org-mode file.

This short example demonstrates the easiest way of getting a string of input in your commands: interactive. Emacs makes a distinction between functions which are called interactively, and those which are not. When you call a function non-interactively that means you are calling it from inside of Lisp code. If I wrote

(open-project-log-file "Foo")

then that is a non-interactive call. But when I run the command from my key-binding, or if I did M-x open-project-log-file, then that is an interactive call. When I do that Emacs looks at the ‘interactive’ form at the top of the function to figure out how to get the argument for the function.

We can use interactive in a couple of different ways. The simpliest is by giving it a string that describes how we want to prompt for and read in arguments. The parts of the string are separated by ‘
’ characters. The first character of each part tells Emacs what kind of input to read in. Then everything from that character until the next ‘
’ or end of string is the prompt.

So in the case of “sProject: “ that means to read in a string (‘s’) from the prompt ‘Project: ‘. Whatever I type in is assigned to the ‘project’ parameter of the function. Another example:

(defun interactive-example (foo bar baz)
      (interactive "bFoo: 
fBaz: ")

This example has three prompts, setting ‘foo’ to a buffer name (‘b’), ‘bar’ to the name of a function (‘a’), and ‘baz’ to the name of a file (‘f’). In all cases Emacs knows what we are wanting to read in and provides us with completion help. For example, it knows what buffers and files are open, and what functions exist, so we can tab-complete on all of these.

If you look at the documentation on interactive you will see that it accepts a large number of codes for defining your input. But they can’t cover everything. There comes a time when you’ll want to have tab-completion available for some known set of values. This is where completing-read comes into the picture.

Let’s say I want to redefine my log function so that Emacs will know which files I might be looking for. That is, what log files exist in my log directory? Easy way to find out:

(directory-files "~/Documents/Logs/2010/")

Returns all of the files in that directory as a list of strings. I can use that as my set of possible inputs. Whenever I open a log file, the file I want will always be in the list. So what I want is for Emacs to tab-complete based on the values in that list. The function completing-read does this exactly.

(completing-read "Project: "
                     (directory-files "~/Documents/Logs/2010/"))

This line of code will print out the ‘Project: ‘ prompt as usual and read in input from the minibuffer. The second argument is the ‘collection’, a list of strings which represent valid input values, and which Emacs can tab-complete on. This is the minimum needed to use completing-read. However, it takes six additional, optional arguments. If you want to restrict completion to a sub-set of those values, or allow input outside of that set, then you’ll need to pass values to those optional arguments. As always, C-h f is the fastest way to find this information.

So let’s look at a smarter version of open-project-log-file:

(defun open-project-log-file (project)
      "Opens a log file for a project."
        (completing-read "Project: " (directory-files "~/Documents/Logs/2010/"))))
      (find-file (concat "~/Documents/Logs/2010/" project)))

Here is an example of the other form of interactive: using Lisp code instead of strings. In this form, the code given to interactive needs to return a list of values that will be assigned to the function parameters. The easiest way to create a list in Lisp is with the ‘list’ function.

(list 10 20 (+ 100 1)) => ‘(10 20 101)

In my case, I’m just creating a list of one value, the result of completing-read.

The rest of the function is the same. But now when I run it and type ‘F’, I get the benefit of hitting Tab and having ‘’ show up in the minibuffer. If you are writing a custom command and can think of a way to define the set of inputs that function will take, even if it is incomplete, then you can use completing-read to get the benefits of tab-completion in your functions.

Posted on

Real-Time PHP Error Messages in Emacs

I was frustrated yesterday while working on a project because of a bug caused by a syntax error. In the year 2010 we really should not be having bugs because of syntax. I say this not to blame anyone—in fact the syntax mistake was mine—but to make the point that this is not the type of bug that should ever waste our time.

Flymake is a package for Emacs (I think it’s standard these days) which performs automatic syntax checking. Like most things in Emacs, it is extensively configurable. Flymake has to be this way by design, since it is intended to perform real-time syntax checking for all languages.

One way Flymake does this is by deferring to external tools. PHP happens to have a syntax checker built-in. If you run

php -l foo.php

you will be told whether or not foo.php has any syntax errors, and on what lines they appear.

There was an existing Emacs package that claimed to provide PHP support for Flymake, but it didn’t work for me. So I wrote my own.

(defun flymake-php-init ()
  (let* ((temp-file (flymake-init-create-temp-buffer-copy
         (local-file (file-relative-name
                      (file-name-directory buffer-file-name))))
    (list "php" (list "-f" local-file "-l"))))

(add-to-list 'flymake-allowed-file-name-masks

(add-to-list 'flymake-err-line-patterns
             '("\\(Parse\\|Fatal\\) error: \\(.*?\\) in \\(.*?\\) on line \\([0-9]+\\)" 3 4 nil 2)) 

Stick this in your .emacs file—or some external file—and you will be able to get real-time syntax error checking. I don’t know why I went so long without doing this.

Posted on

Indent on Save, Maybe

While working on a .NET project, I have noticed that when I do many things, Visual Studio takes that time to re-indent large amounts of my code. But most of the time I’m writing it out in Emacs, so this makes my diffs a pain in the ass. But it got me to thinking about indenting on save. And then—lo—the very subject came up today on the Emacs mailing list. A teacher was asking for a way to make C++ mode automatically re-indent the whole file on save, to make his students use. I don’t know if he was sick of seeing horrible indentation or what.

There is a hook in Emacs called the before-save-hook, to which you can add functions to be called just before saving the contents of a buffer. A great example:

(add-hook 'before-save-hook 'delete-trailing-whitespace)

Will call delete-trailing-whitespace whenever you save any file.

So with that hook in mind, here was my first idea, which I sent back to the guy.

(add-hook 'before-save-hook
          (lambda ()
            (when (eq 'c++-mode
                      (buffer-local-value 'major-mode (current-buffer)))
              (indent-region (point-min) (point-max)))))

Each buffer has a local variable called major-mode that names the current major mode—appropriately enough. This anonymous function checks to see if that mode is c++-mode, and if it does then it calls indent-region with two arguments: the start and end points of the region we want to indent. The functions point-min and point-max return the minimum and maximum points of the buffer. So this indents the whole thing.

But a more experienced Emacs Lisp developer on the mailing list pointed out to me a better way. His code:

(defun c++-indent-buffer-maybe ()
  (when (and (string-match
             (y-or-n-p "Indent buffer before saving ?"))
    (indent-region (point-min)

(defun my-c++-hook ()
  (add-hook 'before-save-hook 'c++-indent-buffer-maybe nil t))

(add-hook 'c++-mode-hook 'my-c++-hook)

His code looks at the filename of the buffer to decide whether or not the file should be indented. I prefer checking the major mode still, but the teacher who asked the original question also wanted to see a filename-based solution.

This version also prompts—via the function y-or-n-p—to make sure the user wants to indent the whole buffer. If the user types ‘n’, the buffer is still saved, but not indented. This is useful, but adds an extra key-press on every save. Personally, I think I would go without it.

But the best way in which this code is better is how it sets the hook as a mode hook for C++ mode. One problem with using before-save-hook is it is called for every buffer. So my original code would be checking every time I save anything. Which is overkill. The function my-c++-hook above adds the indenting function to before-save-hook, but sets it as a buffer-local hook. This is done by the last argument. If we look at the definition of add-hook:

(add-hook HOOK FUNCTION &optional APPEND LOCAL)

The first optional argument APPEND decides where in the hook list our function goes. The LOCAL argument, if true, makes the hook local to the current buffer.

So via a little indirection, the code above makes sure that the indented code is only run when saving C++ buffers, instead of checking it when saved everywhere.

A useful combination of these would be:

(defun c++-indent-buffer-maybe ()
  (if (y-or-n-p "Indent buffer before saving?")
      (indent-region (point-min)

(add-hook 'c++-mode-hook
          (lambda ()
            (add-hook 'before-save-hook 'c++-indent-buffer-maybe nil t)))

Not hard to imagine how to extend this to other modes.

Posted on

SQL Movement Commands

Most programming modes in Emacs support two commands, beginning-of-defun and end-of-defun.  These move you to the beginning and end of the nearest function, and by default are bound to C-M-a and C-M-e, respectively.

However, sql-mode does not have anything similar.  I have the above two commands bound to C-up and C-down for quickly moving around functions, but I find myself often hitting them when viewing an SQL file to move through tables—which doesn’t work.  Fortunately that functionality is pretty easy to add.

For my fellow Emacs users, here is some code I whipped up that you can use to easily move between tables and views.

(defconst sql-beginning-of-table-or-view-regexp
"Regular expression for matching the start of an SQL table or view definition.")

(defun sql-prev-table-or-view ()
"Move backwards to the beginning of the nearest table or view
from point."
(re-search-backward sql-beginning-of-table-or-view-regexp
nil 'noerror))

(defun sql-next-table-or-view ()
"Move forwards to the beginning of the nearest table or view from point."
(re-search-forward sql-beginning-of-table-or-view-regexp
nil 'noerror))

Then you can add a hook for sql-mode to bind those commands to keys whenever sql-mode is first loaded. I know you guys already know about using global-set-key, but you can also create key bindings specific for modes. Each mode in Emacs has an associated “mode map”, for example, sql-mode has the sql-mode-map, php-mode has the php-mode-map, et cetera. You can use the function define-key to create a binding for a specific mode map. Like I said, I have C-up and C-down globally bound to move functions, but I use define-key like this to make the keys move by tables/views is sql-mode:

(global-set-key (kbd "<C-up>") 'beginning-of-defun)
(global-set-key (kbd "<C-down>") 'end-of-defun)

(add-hook 'sql-mode-hook
(lambda ()
(define-key sql-mode-map (kbd "<C-up>")
(define-key sql-mode-map (kbd "<C-down>")

I put my global key settings in there just for comparison. The call to define-key is almost identical, except the first argument is the mode map.

While I’m on the subject, there are two similar commands for text-mode that have no default binding, which I find come in handy:

(add-hook 'text-mode-hook
(lambda ()
(define-key text-mode-map (kbd "<C-down>")
(define-key text-mode-map (kbd "<C-up>")

So there’s some hopefully useful commands for SQL work, and for configuring key bindings in general.