Posted on

Debug a wordpress plugin or theme – for non-developers

It works for others, but not for you – what’s happening?

picture of a dead bug and blood
Don't sweat blood over a bug

Rules for dealing with a  new plugin, or theme or an upgrade:

  • READ the instructions, okay some plugins can be intuitive, but some may need a crucial step.  Go back and check that you have not missed something
    • Check the readme.txt (or the WordPress.org site – shoudl be the same)
    • Check the plugins own site
    • Check the settings.
      • I like to code my plugin in such a way that you do not have to even look at the settings, it should still work with a default setup, but not everyone does – some people do not even check the settings.  Some developers put their settings in strange places – I found one whose settings were reached off the plugin listing line, but only when you hovered over the plugin line!
      • I also tend to put some explanatory text, or links to explanations in the settings area near the relevant area
  • READ the changelog.  If the author is diligent, there should be detailed description of the changes.  If there is no detailed description, assume anything could have changed.  If it says ANYTHING about a database change,you definitely need to
    • switch maintenance mode on – a number of plugins can do this for you
    • do a backup that includes the database, and know how to restore it!
  • If the plugin is crucial, check the forums BEFORE you upgrade. If you are really unlucky you may be the first to flush out a bug or clash, but the odds are someone will have got there before you.
  • Test the new plugin, theme or upgrade on a test server first, with other crucial plugins active. NEVER ever apply it to your live site straight off, even if you trust the developer.  There are infinite combinations of circumstances and your site may just find one that breaks the plugin.
  • Have a backup that YOU know how to restore.   Yes it seems it is  not obvious to all, but it is  no good having a backup if you have no idea how to use it.  Hopefully your host has a simple option for you – be aware of lead times if you need their input.
  • Do not start late at night.  If you hit a problem at past 10pm at night, stop, reverse, go to bed. (Yes I’m a mother, but I also know when I am not  being effective.  I do not like to waste my time.)

Only break these rules if…

you are able to cope with the consequences of  a problem

  1. simple actions you may need to do could be  to get the prior version of the code and ftp that over the ‘new’ version
  2. worst may be having to reverse an updated database (and no backup),
  3. or have the plugin deactivated for a while.

Debugging the plugin or theme on your site

If it is a simple, obvious problem or visible error, a “fatal error”, “warning” or “notice”, then an internet search, or forum search both at wp and at a plugin own site,  using the words but removing anything that relates to your site can be very useful and give you a quick sense of what may be wrong. It may educate about the WordPress functionality is use.

Common things are :

  • permalinks needing flushing with custom post types and taxonomies,
  • missing a wp function  due to an old wp install,
  • function or class naming clash with a theme or another plugin
  • etc

Not a simple, obvious problem, or plugin developer cannot recreate the problem?

If it is not a simple, obvious problem or a visible error, then you may need to do one of the following. Both  are looking for a clash or trying to isolate the circumstances that cause the problem

  1. Go backwards – Either start with your test server and switch off  plugins, one by one,  testing the plugin in question after each step, or
  2. Start at the beginning and go forwards – start with a clean install and add in the plugins and themes one by one

This may seem cumbersome, but sometimes it is the only way.  It can also be highly informative about the plugins you are using and/or the theme.  before you all of this, though check first:

  • Is it an old WordPress? If yes, try on a new clean install with latest
  • Did you just upgrade to latest WordPress and was it just released ?  the plugin may not yet be compatible with something that changed in WordPress.
  • It is the php version?  the plugin should work on the ‘most’ common php version, which at time of writing is 5.2  See http://wordpress.org/about/stats/.  If your php is old or very new, this may be it. You need to be able to tell the developer what php you are using.

Be methodical

Be careful that you are doing the necessary steps to adequately test at each step, so you do not waste your time. Do you need

  • refresh the browser and /or clear the cache’
  • logout / login (depends on the functionality of the plugin)

The objective

You want to be able to honestly tell the developer that you have tested the plugin on a

  • clean (non customised) WordPress install, preferably with the latest WordPress version
  • with the current default theme (eg: twentyten) and
  • no other plugins active (or maybe only standard plugins active)

It is highly unlikely that you will get  to this point without  finding some thing out. Examples:

  • a clash with a theme or other plugin
  • if it worked on a clean new wp install, it may be that your database or your WordPress is corrupted. Scary, does happen.  Sometimes even a clean WordPress install gets corrupted and one has to “install” it twice.  I’ve seen people describe this.

Reporting a problem – the rules of engagement

  • Do NOT struggle for multiple hours, getting more frustrated.  Take a tea break, go for a walk, get a nights sleep.  Check for environment changes… i’ve seen people curse WordPress and a developer only to shamefacedly report back after a day or so to report why it was actually something that had happened on their side.
  • Report early to the plugin forum – you may be highlighting something new, the sooner the developer knows, the quicker they can address it.  Use some good judgement about how early to flag an error, but do continue with the debug steps.
  • BUT DO not report without doing some of your own debugging.  Your situation may be unique.
  • Be specific – report  with as much information as possible .   “It does not work” is not helpful to anyone.  Clearly it will have worked for some people or most likely many. The more info you can provide, the more likely you will get quick resolution.
  • Unless you have a support contract with a guaranteed response time, do not realistically expect better than a 48 hour to 1 week turnaround, or even one at all in the case of free plugins or ones that explicitly exclude guaranteed support. It doesn’t mean that they do not support it, it just means they are unable to guarantee it – this is quite reasonable – particularly if the the developers are a small organisation or an individual. For example most of you know that  I usually get to a question within hours, but cannot guarantee that, so I explicitly exclude guaranteed support in my terms.
  • When reporting, have good manners and remember timezones.  You never know what is happening in someone else world (births, deaths, tsunamis, earthquakes, snake bites, sick children, broken fibre optic undersea cables, loss of power, loss of internet…) .

Debugging for plugin developers

Most of the above applies to you too! however there is more. Mostly I recommend

  • always working with php and mysql  ALL errors, warnings, notices etc switched on.
  • test on multiple platforms and browsers
  • before releasing an upgrade, test on existing (upgrade) and one new clean install

For more details, see

Update all plugins
It's tempting.. but should you?

Judge the risk/benefit tradeoff before you click that one step upgrade all – you are the one responsible!

Posted on

Price vs value vs expectations vs feedback

photo by ecastro

A Seth Godin post on the irrelevance of price to content, struck me as relevant to plugin development.

People walking out of the afternoon bargain matinee at the movies don’t cut the film any slack because it was half price. Critics piling on to a music video on YouTube never mention the fact that HEY IT WAS FREE. There is no thrift store for content. Sure, we can get an old movie for ninety-nine cents, but if we hate it, it doesn’t matter how cheap it was. If we’re going to spend time, apparently, it better be perfect, the best there ever was, regardless of price.

It also made me think about the responsibility one has in putting something out ‘there’ – making it free does not absolve one of responsibility for it.  Certainly one should not put something half baked out there.  There are many plugins loaded up that never amount to anything – why do people bother?

Is it responsible ?

The culture of free

Certainly the culture of ‘free’ is (I think) changing.  Services like itunes have proven that there is a market for paid apps.  Some want to ‘pay more’  – they hope they’ll get a better product, and sometimes they do.

There have been many controversial posts on the web about the whole free/paid plugin question.

I’ve noticed that most of the time, when someone has paid for a plugin, they have a vested interest in telling the developer if they experience a problem on their system. This helps the developer understand if there aspects of server setup, or interactions with themes that you did not expect, or perhaps where there is a gap in the documentation or ease of installation.

When the plugin is free, while many are grateful and supportive, others can be quite harsh. A brusque “does not work” ! with no details. They do not stop to wonder why a highly rated plugin used by many does not work on their system – were they on an old core system, did it work on the default theme – who knows?

They slate it, uninstall and move on to the next free one.

The developer knows it works because he tested it (hopefully) on several wp versions, several browsers etc…. but clearly there was a situation somewhere that caused a problem.

Moral of the story?

Releasing a well developed free version is great for exposure, but do not do it unless it is reasonably robust and you are prepared to a some support ….

A free plugin I was using was not doing it’s job like it used to …. a quick look at both forums (wp and the well regarded authors main site) revealed a number of unhappy users. The developers who were perhaps too busy to dedicate time to the ‘free’ plugin, but could perhaps have handled the situation better…. what is left is a slight feeling of negativity.

Some developers have the attitude that they have offered up some code for free and users should debug it and modify it… well….. in some communities where everyone has some ‘expertise’ that philosophy is totally valid.

Too easy

However WordPress has become so accessible to so many. Many WordPress users do not even have html or css skills, let alone php…… As for basic debugging skills ….I sigh at some posts at wordpress – what do these people expect ?  that they can run their web design business leveraging off the good will of others ?

One of the reasons that WP Help desk shut down apparently was that they found it hard to find good staff who were prepared to put up with abusive users of free plugins. How sad

The dangers of too easy and free…..

Posted on

Permalinks, custom post types and taxonomies, conflicts

Around the various forums, I see a number of concerned folk struggling with permalinks.  There is a variety of advice, most of which is about flushing your permalinks (goto settings > permalinks).  This does not always work and sometimes there are weird clashes or conflicts.  There is an important point that is not visibly made and perhaps not obvious to many:

Unique permalink URLS

However you setup your permalinks, custom post types and taxonomies, you need to ensure that the resulting permalink urls will be unique so that the system can identify the post or custom post content correctly and the url’s generated do not conflict.  Else the first rule to fire will determine what is returned.

I first encountered this problem way before post types and taxonomies when a client had an image named the same as a post, with some weird results in certain situations – took me a while to figure that out!

To demonstrate the problem, I

  1. defined my permalink structure using /%category%/%postname%/
  2. created a category called event and
  3. activated my event plugin that has a ‘event’ custom post type.
  4. I then created two posts called the same “CPT 99999”
A standard post in a category called event

When I click down from the standard post category archive instead of getting the standard post, I get the custom post type event with the same name.  There are two rules leading to/from the same url.  The first will win.

Clicking down on the standard post takes me to the custom post type event

Solutions

1. for new systems, or where you can still change the permalink structure:

Make sure that you have something that will guarantee uniqueness in your permalink structure.  Since I usually do not feel the need to have the category name in my permalinks, I use /%post_id%/%postname%/ which will always give me a unique url ! – and since my audience is mostly technical, I am not concerned about the post id in the url.

2. for existing systems with many posts

Essentially you must ensure that each url somehow generates a unique url – this may mean changing some slugs somewhere (posts, custom, taxonomies or categories)

Consider also reversed words

I had the sense in my taxonomy code for the amr-events plugin to check for wordpress “reserved” words and prevent prevent creation of a taxonomy that uses them.  This sort of  checking may need to go further, although as pointed out  here in response to this question, it is not much different from the risk of plugin function names or input form names overlapping with reserved words.  Plugin, theme authors and web developers need  to bear these risks in mind.

More information:

Key points extracted from above:

  • Custom Post Types have a URL of /slug/postname.   The “with_front” option lets you make that into /something/slug/postname, if you happen to have a post permalink structure with a prefix on it (like /text/%postname% or something)
  • Don’t setup a permalink structure that will clash with the archive structure. e.g. say you only had one post a day and wanted to use: %year%%monthnum%%day%, links so generated will be interpreted as the archive of all posts for that day.
  • Add taxonomies slowly, one by one – verify that permalinks continue to work each step of the way.
  • For performance reasons, it is not a good idea to start your permalink structure with the category, tag, author, or postname fields
  • Google looks at the words in the URLs of your posts and uses them as factor in determining relevance, and therefore he (Matt) advises using %postname% in your WordPress permalinks. He doesn’t advise using ONLY %postname%.   There’s nothing wrong with using postname. Just use something else at the beginning of the string.
  • There is a LOT of benefit of having postname in url if you are using adsense. Try this: Take any new domain timbuktu.com and if you have a post for which the url is timbuktu.com?p=7 you will get junk ads.   Now try timbuktu.com/car-insurance-save-on-car-insurance – You will get beautiful insurance ads.