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

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.
Posted on

Plugin does not have valid header.. still activates

If you experiencing problems installing a plugin from a zip file, do not panic, do not curse the developer!

Google The+plugin+does+not+have+a+valid+header and you will find a lot, most of them will tell you that

  1. Mostly it is the folder structure which suits ftp’ers but does not suit zip installers
  2. sometimes  there is a minor problem in the plugin header
  3. sometimes  it is a bug in the way that the zip installer works and you will find that even though you have that invalid header message, the plugin will have activated or you will be able to activate it from the inactive plugins list

Use FTP if you can

The wordpress zip install is finicky – it does not cope with certain situations that I expect it to.  If you can at all use ftp instead, please do.  Not only will you have a better view of what is going on and your websites folder structure, you will also avoid some problems.

Handling a zip file – Zipped at folder or file level?

  • If the plugin zip file has a version number (which is good practice so one knows which file is which, the zip installer will install it into a version folder… and NOT upgrade – you will end up with two versions.
  • Unzip or explore the zip file first – if it is all neatly in a folder, you can ftp that folder up sweetly.  Nice!
  • If you insist on using the zip install, you will have to unzip, and then rezip at the lower level, without the top folder in order to use the zip installer

Still getting an invalid header message (even in 3.0.1)?

  • Somehow once you have mucked around trying the zip  install with folders etc, WordPress has stored the fact that it does not like the plugin, and even if you have now ftp’ed a copy up it remembers that it had a problem.  I was getting really frustrated and had double checked my header endlessly.  Then I found a note about ignoring the message, heading back, back, back to the plugin list.
  • Go to inactive plugins, refresh if you have to, activate.
  • In one instance, after being told there was an invalid header and not being to see it in the inactive list, I found that it had activated after all.

I have had an attempt at describing what seems to be the cause possible corrective action.  See

http://core.trac.wordpress.org/ticket/15191

Hope that helps!