Coppermine Photo Gallery v1.5.x: Documentation and Manual

Plugin Writing for Coppermine

Quick Start Guide

Coppermine comes with a plugin architecture that allows skilled users to come up with plugins that can be installed by the end user with just some clicks in the plugin manager section. Main benefit of plugins is that end users don't have to hack core code files. As a result, plugins don't need to be applied when upgrading between minor versions of coppermine (when replacing all core files due to maintenance releases).

Many things that could be done using core hacks can be accomplished using plugins as well. The only disadvantage of plugins is the fact that the plugin author needs to become a bit more familiar with coppermine's plugin API.

This short guide is supposed to help possible plugin authors to get familiar with the plugin system. You have to understand though that this section will not teach you how to edit PHP - this would be beyond the scope of this documentation. We asume that you're familar both with HTML as well as PHP to some extent. This section of the docs will definitely not teach you how to code in the first place, nor is it a beginner's tutorial for programming. If you have never written one line of PHP code you should get familiar with PHP first and apply some hacks before actually considering to come up with a plugin of your own.

Plugins from Coppermine 1.4.x may not work in 1.5. If the plugin uses superglobals like $_POST and $_GET, you need to rewrite those superglobal calls using the new code sanitization in 1.5. See the section "Use of Superglobals". Also, the plugin may include Coppermine files that Coppermine 1.5 now includes for you. You can change "require" to "require_once" or remove the call if Coppermine will always include the file you want. Finally, check the notices under the Debug box to see if any constants you define may already be defined by Coppermine and include checks in the plugin before defining such constants.

Intended Audience

Here's a list of who should and who should not (or doesn't need to) read this documentation. The categories overlap in many places, so make sure to read the entire list. Find yourself in the list and then decide whether you should read on.

People interested in using plugins but who do not need to modify them or write their own should read the main documentation instead - the plugins section describes everything you need to know.

Why write plugins?

The biggest advantage of a plugin over a mod is the fact that plugins will remain when updating Coppermine, while mods (aka "modifications" or "hacks") need to be re-applied after updating.

It's pretty easy to come up with a plugin of your own. This page and it's sub-pages is meant to explain how to come up with your first home-made plugin.

Preparations

Before starting to hack away, you should make some preparations and maybe sketch the layout of your plugin.

• Choose a name

  Your plugin needs a meaningfull, simple name. Make sure that a plugin doesn't already exist with the same name you've chosen. Then create a sub-folder within the plugin folder and name it as you see fit. Make sure to use web-safe names (only alphanumerals, all lower-case, no special chars except underscore.
  For clarification: there can be only alphanumerals in a plugin's folder name. There mustn't be any dots or other special chars in it. The only exception is the underscore (_)
  your_coppermine_folder/plugins/coffee_maker/
  Coming up with a folder name sounds easy, and you may be tempted to just use the name my_plugin or foobar to be able to start coding right away. However, you have to keep in mind that while you progress writing your plugin, the folder name will appear hard-coded into your plugin (possibly many times), so it will be hard to change it later. That's why it's advisable to come up with a good folder name in the first place: it should be descriptive, consist of two or three words and mean something initially. A folder named "coppermine_candy" wouldn't mean much - the word "coppermine" would make no point, as the plugin already resides within coppermine, and the word "candy" would no describe what your plugin does. Better, self-explanatory names for plugins would be "rename_users", "thumbnail_dropshadow" or "backup_files". For details on a good name for your folder, please read up the section "Naming conventions".

• Consider translations

  Coppermine is an international project, with users from all over the world. If you should decide to contribute your custom plugin later, it would be a good idea to design it properly in the first place: keep all strings that could need translation in a separate include file and only hard-code the corresponding vars into your code.

• Consider a config screen

  If your plugin is only going to add one single feature to coppermine without anything to configure, then there's no need to provide a separate config screen for your plugin. However, if your plugin has options the end user could configure, it's a good idea to come up with a config screen for your plugin.

• Database changes

  If your plugin needs to write to the database or even changes the structure of tables, it's almost mandatory to come up with a routine to write the needed database changes during install of the plugin. It's a good idea as well to come up with a method to undo the database changes if the user should later decide to disable/uninstall your plugin. If this is the case, you should preferably come up with a database setup screen as well.

• Support issues

  For every non-trivial plugin that gets published on the coppermine home page, there will be an announcement thread on the board. It's a good idea to provide the URL of the announcement thread together with your plugin, preferably even a clickable link.

• Plugin versions

  Although you may not plan to develop your plugin even further, others may do so. Therefore, it's a good idea to provide a version number with your plugin.

Core files

Every plugin contains at least two mandatory files: codebase.php and configuration.php:

• codebase.php
  In this file, the various actions that a plugin can execute are being defined. Think of it as the plugin's core file, where the core logic of the plugin resides in.
• configuration.php
  When the plugin manager is run, it scans through all sub-folders of the plugins folder and looks for a file named configuration.php. If such a file exists, the information provided within this file will be displayed as a record in the list of not-installed or installed plugins.
   
  You can use these vars inside configuration.php:
  • $name
    The full name of your plugin (not only the web-safe folder name chosen initially, but a name that indicates what the plugin does).
    
    $name = 'Coffee Maker';
  • $description
    A short description that explains what your plugin actually does.
    
    $description = 'Turns your Coppermine gallery into a coffee machine.';
  • $author
    Obviously, this is the place for your credits. You can use your real name or a nickname (or even both). You can even slightly promote your site by adding a link to it within the content of this variable.
    
    $author = 'John Smith (aka "<a href="http://yoursite.tld/" rel="external" class="external">NeoIsDead</a>").';
  • $version
    The version of your plugin - usually starting with 1.0 (although you're welcome to come up with any other numbering scheme as long as the difference between versions will be obvious). A lot of coders try to indicate the stage their code is in using the first digit of the version number. That's why many start modestly counting from zero, with the zero versions indicating alpha or beta stage. While the coppermine dev team welcomes this for entire applications we don't consider this usefull for a plugin, which is not an application of it's own, but just "lives" within the application as an add-on. That's why the Coppermine dev team recommends starting to count from one for the first digit and zero for the second digit. Using a third digit is inappropriate for nearly all plugins.
    
    $version = '1.0';
  • $extra_info
    Is displayed with the title of a plugin that is not installed and can be used to present extra information. Use it for example to present an additional link to the plugin documentation if your plugin needs detailed explanation. When using larger pieces of HTML, it's recommended to use the heredoc-syntax to define the variable to make the code better readable.
    
    $extra_info = <<<EOT
    <table border="0" cellspacing="0" cellpadding="0">
    <tr>
    <td class="admin_menu">
    <a href="http://yoursite.tld/coffee_maker/docs/" title="Plugin Documentation" rel="external" class="external">Documentation</a>
    </td>
    </tr>
    </table>
    EOT;
  • $install_info
    Is displayed with the title of a plugin that is installed and can be used to present extra information. When using larger pieces of HTML, it's recommended to use the heredoc-syntax to define the variable to make the code better readable.
    
    $install_info = <<<EOT
    <div class="admin_menu_wrapper">
    <div class="admin_menu admin_float">
    <a href="index.php?file=coffee_maker/admin&action=config" title="Configuration">Plugin configuration</a>
    </div>
    <div class="admin_menu admin_float">
    <a href="http://coppermine-gallery.net/forum/index.php?foo=bar" title="Plugin Support">Support thread</a>
    </div>
    <div style="clear:left;"></div>
    </div>
    EOT;
• readme.txt
  It's a good idea (not mandatory though) to provide a plain-text file within your plugin's folder as well (readme.txt or similar) that contains copyright and support information and basic instructions what your plugin does and how the end user can install it.
  It's not a bad idea to include a changelog and license information in that readme file.

Naming conventions

Even if you plan to write a plugin just for your purposes you should pay attention to the naming conventions for plugins to make sure that your plugin will not stop working as expected at a later stage (e.g. after an update).

The naming conventions exist for two purposes: they enable Coppermine's developers to come with restrictive rules for Coppermine's core code to prevent hacking. Unsanitized user input can have a huge impact in hacking scenarios, that's why there are rules for plugins as well. Additionally, naming conventions are supposed to make maintenance and support easier, and finally, end users will find their way around easier as well.

• Folders

  Use web-safe names:
  • only alphanumerals
  • all lower-case
  • no special chars except underscore (_)
  your_coppermine_folder/plugins/coffee_maker/

• Files

  Use web-safe names:
  • only alphanumerals
  • all lower-case
  • no special chars except underscore (_) and only one dot (.) to separate the actual file name from the extension
  your_coppermine_folder/plugins/coffee_maker/my_file.php

• Archives

  You only need to worry about naming conventions for archives if you plan to release your plugin for the public. The zip-archives for plugin releases follow a naming convention - it's advisable to adopt to that convention to prevent confusion for end-users.
  • only alphanumerals
  • all lower-case
  • no special chars except underscore (_), hyphen (-) and dot (.)
  • All archives start with the official abbreviation "cpg" to indicate that the archive is meant to be used with coppermine or is related to coppermine
  • The major version an archive is meant to be used with comes right after that - the minor version being replaced with an x. Possible values for plugins can currently be 1.4.x and 1.5.x. The Coppermine version is being followed by an underscore
  • The word "plugin" to indicate that the archive contains a plugin (opposed to a theme or similar), followed by an underscore
  • The name of the actual plugin, preferably using the same name that has been used as folder name. The plugin name should usually consist of at least two words. Unlike the naming convention for folders, then words in the archive name are being separated with hyphens (-) to make them distinguishable from the underscore that separates the components of the file name. In above example, where the folder name coffee_maker was used, the corresponding part of the archive file name would be coffee-maker.
    To separate the actual plugin name component in the file name from the rest, another underscore should be used
  • All plugins have versions. Even if you don't plan to create more versions after having released your initial plugin, others may want to do so. That's why you should always populate the version number inside configuration.php. The same version should show through in the archive file name, with the letter "v" prepended to indicate the word "version". Major and minor version numbers should be separated with dots. Coppermine itself currently features three digits for the version number. We advise plugin authors to use a two-folder version numbering scheme, where the first digit indicates the major version and the second digit indicates the minor version change (usually a maintenance release).
    This two-digit version numbering scheme for plugins is not written in stone - plugin authors can use a three-digit notation as well if they desire.
    The Coppermine dev team suggests starting the numbering at version 1.0
  • The extension zip can of course not be edited. We strongly suggest only to use zip and not some other archive format like rar or 7z even if those other formats may have advantages. The archive-type zip is most commonly used; everybody should have a tool to extract zip files.
  cpg1.5.x_plugin_coffee-maker_v1.0.zip

• Coding

  There are naming conventions as well as far as the stuff within your files is concerned: you should take a look at the coding guidelines for Coppermine as well to get an idea how to name your functions, variables and constants.

Use of Superglobals

Plugin Types

Using includes

Files the plugin is meant to include can only contain one single dot that separates the actual filename from the php-extension!

Sub-sections

These plugin documents are a work-in-progress, and a to-do list. The following sub-sections exist so far that are recommended to read:

• Tutorial, Plugin API, Coppermine Global Variables & Constants
  The tutorial is the next logical step to follow after having read the quick start guide
• Reference List of Plugin Hooks
  The reference list is meant as a source for experienced plugin writer who need to look up the names of hooks.