blog.kungf.eu

Warning: This plug-in is now unsupported. I haven’t had time to develop it for a while, and I can’t see that changing any time soon. If anybody wishes to do something with this then by all means be my guest.

Description »

Referer [sic] is a plugin for the popular blogging software WordPress. It allows you to display information about refers you have had from other websites. Currently available stats are Top URLs, Top Hosts Top Search Keywords, and Top Search Phrases. Basically these show how many people have clicked through from a given website and what people are searching for to find your website.

You can see this plugin in action at the bottom of my right-hand sidebar (see http://kitty0.org/blog/).

I know it’s spelt wrong but somehow that is the spelling used in the HTTP/1.1 Specification (RFC 2616) so I guess it is now the official spelling when describing “the address (URI) of the resource from which the Request-URI was obtained.”

Copyright / Disclamer »

Copyright (C) 2006 Hamish Morgan (referer [at] kitty0 [dot] org)

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

FURTHER MORE this plugin may well corrupt your website, empty your database, delete the internet, run away with your girlfriend, instigate World War III, email your porn collection to your Mum, and perform satanic rituals to further the coming of Demonic Minions and general Armageddon. USE IT AT YOUR OWN RISK! You have been warned.

Design Goals »

• Display a list of Urls and Hosts on a Wordpress blog to show where people have clicked though from to find the site.
• Display a list of Search Words and Phrases that where used in a search to find the site.
• Allow this display to be easily customized without the need to edit any files.
• Log the referering url every time a page is loaded.
• To quickly fill out the logged data with data recorded previously by allowing a webserver access log to be imported.
• Provide some means by which results can be filtered out by URL, Host, or Search Word to counter the increase is referer spam.
• Allow the site owner to browse and manage logged data in detail.

Download »

This plugin is in very early Alpha version. It has several bugs that I am aware of and probably many others that I am not. I distribute it in the hope that it will be useful, but WITHOUT ANY WARRANTY, without even the implied warranty of MERCHANTABILITY or FIRNESS FOR A PARTICULAR PURPOSE. It may well corrupt your website, empty your database, delete the internet and run away with your girlfriend. Use it at your own risk!

Click here to download.

The latest version is 0.41 but if you wish you may download an earlier version:

• Version 0.41 — referer_v041.tar.gz.
• Version 0.40 — referer_v040.tar.gz.
• Version 0.30 — referer_v030.tar.gz. — view source
• Version 0.21 — referer_v021.tar.gz. — view source
• Version 0.20 — referer_v020.tar.gz. — view source
• Version 0.10 — referer_v010.tar.gz. — view source

Installation »

1. Extract the contents of the archive to your wp-content/plugins/ directory, creating a new directory: wp-content/plugins/referer/
2. Make sure all these files are readable by the webserver. (See http://codex.wordpress.org/Changing_File_Permissionsread)
3. Go to the “WordPress Admin -> Plugins” panel. Find the Referer plugin in the list and click “Enable” in the right-hand column.
4. Go to “WordPress Admin -> Options -> Referer” and click Install. You should now see the plugins Options page.
5. Add referer_topReferers() function to your template. This will display referer stats on your blog. If you have a custom template I can’t describe exactly what you should do but here is what you should do if you are using the WordPress default template.
   1. If your template files are writable on the server then login to WordPress Site Admin and go to Presentation -> Theme Editor. Otherwise you will have to edit the file on you computer and upload it to the correct location on your server.
   2. In Theme Editor click “Sidebar”. Or localy open /wp-content/themes/default/sidebar.php.
   3. Insert ” <li> <?php referer_topReferers(); ?> </li> ” at the bottom of the page just before the ” </ul> </div> ” tags. It should look something like this:

      <li>
      <?php referer_topReferers(); ?>
      </li>
      </ul>
      </div>
      

   4. Click “Upload File” to save your changes. Or locally save the file and upload it.
6. Done! Browse to your blogs front page and you should see the Top Referers stats box in the bottom right-hand side of your side-bar.

Upgrading »

1. Extract the contents of the archive to your wp-content/plugins/ directory, creating a new directory: wp-content/plugins/referer/
2. Go to “WordPress Admin” -> “Options” -> “Referer” and click “Migrate”.
3. If you are upgrading from version 0.10 you will need to configure your template as described in Installation Item 5.Download and extract the latest version of this plugin (above.)

Problems (Help!) »

So it isn’t working as expected. Well first go and read the last paragraph of the Copyright / Disclaimer (above) …and your back. See I told you so.

If you would like my help with a problem then, to speed up resolution, please:

• Insure you are using the latest version of this plugin.
• Tell me about your server: What version of PHP, MySQL and WordPress you are using? Is it Apache on Linux, or IIS on Windows?
• Explain step-by-step exactly what happened up until the problem occurred.
• List all your installed Wordpress plugins with version.
• Provide a link to your blog and, if possible, to the page with the error.

Related Links »

• http://www.wpplugins.jp/projects/analyze/referer/
  Japanese translation of the plugin.
• http://mhdland.net/blog/index.php/2006/08/31/hamishs-referer-sidebar-widget/
  Sidebar Widget for the referer plugin written by Huda.
• http://www.ozpolitics.info/blog/?p=32
  Bryan’s BDP Referral Tracker plugin. Very similar plugin mine but has slightly different strengths.

Change Log »

Version 0.4 -> 0.41

• Fixed call-time pass-by-reference bug that showed under some PHP5 configurations.

Version 0.3 -> 0.4

• Split the plugin into many smaller files because ~250k of code in one file is just silly.
• Put all the css into a seperate style sheet.
• Added Manage options subpage which allows you to view and manipulate stored referer records.
• Moved Log upload controls and other operations to Tools options subpage.
• Removed %n% tag from the page template description because it isn’t very important.
• Added DHTML Date/Time Selector by dynarch.com to Manage subpage.
• Fixed bug where rows from imported log files would use the current date not the logged date.
• Simplified default display templates, because they where confusing and where cause problems with IE (suprise suprise)
• Complete re-write of log import functionality. Now has the ability to set any valid CustomLog directive to parse the log by.
• HTTP Referer is processed after the page has been outputed to the client so it doesn’t slow the page load time.
• Fixed bug where not all SQL was escaped properly.
• Now Strips cache:llO61WBwk4wJ:example.org/ strings from search queries.
• Default value of Blacklist Search Hosts option is now off.
• Added AOL Search to default Search Engines list.

Version 0.21 -> 0.3

• Added rel=”nofollow” to all generated links, so referer spammers dont get any pagerank for their trouble.
• Added “Clear Logged Data” button to empty the referers data table.
• Added GZip (.gz) compressed log file upload. (Not .tar.gz though.)
• Added error checking for client-side form post failures.
• Added disable on submit to options forms so it doesn’t get borked by users epileptic-clicking.
• Added ability to import logs from a server path.
• Hitting [Enter] key in the Options page now runs “Update Options” not “Restore Defaults”.
• Max-upload in label for “Log File Upload” is now in human readable units.
• Simplified the default display templates.
• Fixed some HTML bugs in Options page.
• Fixed bug where limit argument in topReferers() functions doesn’t update %*-limit% tag.
• Fixed multilingual character support in search words and phrases.
• Fixed bug where uploading files larger than max upload file size sometimes just reloads the page with no error.

Version 0.2 –> 0.21

• Fixed bug where Host Blacklist didn’t blocks URLs.
• Fixed/Enabled Searchengine Host Blacklisting
• Improved default output format templates.
• Added %snip% element to output format.
• Fixed problem where stats titles could say “Top 0 Referers”
• Fixed problem with submitting forms containing HTML entities (eg )
• Fixed typo in function referer_fetchPhrases()
• Function parseReferer now returns an associative array of referer info.
• Add migration supportto make upgrading easier.
• Fixed bug where empty lines in searchengine RegEx caused an error.

Version 0.10 –> 0.20

• Added Search Phrases.
• Added complete URL logging.
• Changed database structure to use one table for all data.
• Added search word blacklist
• Improved default format strings for all data types.
• Improved configuration options sub-panel layout.
• Re-wrote almost everything to better accommodate new and upcoming features.
• Removed all fatal errors.. so if something goes wrong it should at least still be possible to disable the plugin.

Known Bugs

• In KHTML (Konqueror / Safari) does strange things with <abbr> tags.
• Long strings in the Manage page are broken up by font-size:0 spaces so copy/paste doesn’t work properly. Additionaly it is malformed XHTML because empty tags should be stripped. Alternative solutions like <wb />, ­ and Unicode U+200B (zero width space), or normal spaces have their own cavetes.
• In Manage page Search Words and Phrases are wrapped even if it is wraping on a whitespace. Very minor but anoying.
• Not exactly a bug but I don’t have access to IE so no doubt everything gets garbled by that poor excuse for a browser.
• Importing a malformed log file can throw many, many errors.
• In Options that Display Format Templates are sometimes reported to have been saved even if no change has been made. This is due to varying new line encoding on different platforms.
• Manage Admin page style is inconsistent with rest of Admin.

Roadmap (TODO)

• Implement a “Reprocess logged data” tool to update data against new filters and blacklists.
• Rewrite all string/regex functions to be mulltibyte safe.
• Fuzzy match domain names in URLs (e.g www.example.com and example.com should be grouped.)
• Improved and easier searchengine matching. Possibily defined as a host and a query identifier. e.g: For google: host=”/www.google..+/search/”, query=”/[?&]q=([^&])&/”
• Or better yet host=”www.google”, query=”q” but the problem with the latter is it doesn’t cope with dogpile style urls: “search/blah/-/-/-/”
• Log local searches
• Add many more search engines. E.g: excite, hotbot, dmoz, aol, a9, technorati, altavista, images.google, dogpile, beta.search.msn, lycos, metacrawler, alltheweb, vivisimo, wisenut, gigablast, mamma, looksmart, search. netscape, clusty, about.com, iwom.ask, webcrawler.
• Add “Clear” button to filters in Manage page.
• Replace the error handling class with something less um… crap.
• For log parsing use ApacheLogRegex::parse_n() to improve performance.
• Add tooltips to result hheaders and clickable results in Manage page to give some hint as to what will happen if clicked.
• Search words and phrases sometimes contain erroneous punctuation.
• Add ability to delete (not just hide) records from the manage page.
• Clarify deffinition of hiding, deletion, and blacklisting (when logging or when displaying) And alter respective controls.
• Install and Mirgate should happen automatically
• Referers page template (like links template)
• Localization / I10n
• Run as a Wordpress Widget
• Current HTTP_REFERER Referer search word highlighting.

API Function Reference »

The following functions can be used in your template files to include referal statistics.

string referer_topReferers([integer limit [, boolean echo]])

This is a wrappers for a function in the Referer class. Use it in your  template to print a formated listst of top referers by catagory. This will  display all usefull information in a box and should be the only function you  have to include in your template. However if you wish to display only certain  parts of the data or format it yourself use the referer_top*() and  referer_fetch*() function below. They take the results of the all the other top*(function) functions (see below) and format it using the "referer" XHTMl snippets in the plugin options panel. It then outputs all the data into the page.

Optional paramater $limit determins tha maximum number of results to return. If it is not given then it will return the number set in the plugin options panel. If limit is given as 0 (zero) the ALL results will be returned.

If you set option paramater $echo as FALSE then instead of print the results  they will be returned so you can perform additional formatting or concatonate  them with other data. 

string referer_topUrls([integer limit [, boolean echo]])
string referer_topHosts([integer limit [, boolean echo]])
string referer_topWords([integer limit [, boolean echo]])
string referer_topPhrases([integer limit [, boolean echo]]) 

These are wrappers for function in the Referer class. Use them in you template print a formated lists of top referers.

They take the results of the fetch*() functions (see below) and format it using the XHTMl snippets in the plugin options panel. Then they output all the data into the page. 

Optional paramater $limit determins tha maximum number of results to return. If it is not given then it will return the number set in the plugin options  panel. If limit is given as 0 (zero) the ALL results will be returned.

If you set option paramater $echo as flase then instead of print the results  they will be returned so you can perform additional formatting or concatonate  them with other data. 

array referer_fetchUrls([integer limit])
array referer_fetchHosts([integer limit])
array referer_fetchWords([integer limit])
array referer_fetchPhrases([integer limit]) 

These are wrappers for function in the Referer class. Use them in you  template to get an unformatted array of results. 

They query the database for stats about top referers. They return an array of  urls, hosts, search words and searchphrases respectively. If there was a  problem or if there are no results they return NULL. 

Optional paramater $limit determins tha maximum number of results to return. If it is not given then it will return the number set in the plugin options panel. If limit is given as 0 (zero) the ALL results will be returned.