enarion.net > Google > phpSitemapNG > Development > Architecture > Plugin example

This page teaches you how to write a plugin for phpSitemapNG

As a short example a URL input plugin will be written. This allows the user to input a list of urls that will be added to the storage object of phpSitemapNG. You can follow these steps described here and download the code that finally will be created.

Step 1: Decide in which section the plugin fits

• Input plugin - add urls to the storage object
• Compute plugins -  compute additional values for the urls that are stored in the storage object and/or manipulate them
  
• Output plugin - will generate output for content of the storage object.

Our example plugin UrlInput - as the name already tells - is an input plugin.

Step 2: Write some code

1. Open your php editor - or notepad - and create an empty file. You should name it like this:
   urlinput.class.php where urlinput is the name of our plugin, the extension .class.php tells phpSitemapNG that this is a php class.
2. Now copy the source code of the plugin class (can be found in the latest phpSitemapNG archive (development version) in phpSitemapNG/classes/misc/Plugin.class.php) into the editor.
3. Modify the following values: class Plugin to class UrlInput  and add an extends Input after this to specify which kind of plugin this is (see point 1).
   Alter also the function Plugin() to functino UrlInput() - this is necessary because this specifies the name of the class and the initialisation.
4. Add content to the creation method (in this case function UrlInput). We're using an internal array that stores our settings, this array is initialized here.
   
5. Add content to the getInfo() method - you can copy this from one of the available plugins and modify it to fit your plugin.
6. Add content to the getSetupHtml() function - check first if there are not already some settings available - if not, it's nice to set some initial values. In our case it wouldn't make sense to add some random urls as default, so this is not used. The crawler and filesystem input plugins have such code.
   This function has to return some html code that allows the user to setup this plugin. We only want to display an textarea where the user will specify the urls. You don't have to add an additional form tag around - the code you're returning will be filtered (later) to minimize the caution of bogus plugins. You might be laughing, but this might be. Anyway, this code filtering is not enabled at the moment - and might never get. :)
7. Now add some code to the init - function. This function has a parameter called $setupInformation and this get's an array at runtime with (at the moment) 2 keys - PSNG_PLUGIN_INIT_SETTINGS contains the settings of the user (if already done, empty otherwise) and PSNG_PLUGIN_INIT_STORAGE contains a reference to the storage object.
   The reference to the storage object is necessary to add urls directly into the storage of phpSitemapNG. You shouldn't buffer these urls in the main memory (this means in a local variable) but should add them directly to the storage. This is necessary for ressource saving, otherwise phpSitemapNG might use 100 mb of ram because each plugin stores it's own copy of the urls in the storage object.
   Don't forget to return true - to signalize phpSitemapNG that the initialisation has been successful.
8. The run() function is the main function of the plugin - here you have to specify the algorithms that this plugin claims to do. Our goal is low level - just add the urls that the user already set to the storage object. You have to return the number of urls that have been added.
   To add an url you have to invoke the addURL function of the storage class ( code can be found in file phpSitemapNG/classes/storage/StorageSession.class.php ). The only parameter is an array which contains the following constants as keys:
   
   • PSNG_URLINFO_URL - used for the url
   • PSNG_URLINFO_ENABLED - used to tell the output plugins to use (value is 1) or to not use(value is 0) this url
   • PSNG_URLINFO_LASTMOD - used for the last modification value, this has to be a unix timestamp - optional
   • PSNG_URLINFO_CHANGEFREQ - used for the indication of the change frequency, string - but restricted to the values specified by the Google Sitemaps protocol - optional
   • PSNG_URLINFO_PRIORITY - used for indication of the priority, float from 0.0 (no priority) to 1.0 (highest priority), optional
     
   There will be more values added in the further development of phpSitemapNG.
9.  Modify the tearDown() function to clean up your internal objects, references and data structures.

Step 3: Copy and test the plugin

After the code of the plugin has been created you should now store the file (if you haven't done so fare) and copy the file into the apropriate phpSitemapNG directory. For input plugins copy the file into the phpSitemapNG/classes/input directory, for compute into phpSitemapNG/classes/compute and for output plugins into phpSitemapNG/classes/output .
When you run phSitemapNG next time and have a look at the plugins page your new created plugin will be available.
If note - make shure the plugin is stored in the correct directory and has the appropriate extension (.class.php) and derives from the correct main plugin class (Input, Compute, Output).

That's it, you have created your first phpSitemapNG plugin. It's not so hard, isn't it?
You can now download the code of the UrlInput plugin.

If you have the knowledge how to write plugins for phpSitemapNG you can now work on some of the open jobs.