# 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 who should read this documentation:

- Anyone who wants to write plugins to customize Coppermine
- Current Coppermine coders who want to convert their hacks & mods to plugins
- Anyone who wants to add in features or modify a current plugin
- Coders who want to start customizing Coppermine but do not know where to start

#### People who do not need to read this documentation:

- Anyone learning Coppermine for the first time - the main manual is all you need at first
- Anyone who wants to download & use plugins - you can use many plugins without knowing what they do internally

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". If someone else already has created a plugin that will do something similar to your plugin, make sure to use a name that differs from the other plugin. The second part of your plugin's name could be your nickname or real name as well - something like "slideshow_nick" as a plugin short name would be OK. It's not a bright idea to try to "cheat" by naming your plugin "aaaaaaa" in an attempt to make it stand out in the plugin list (the plugin list is sorted alphabetically) - the staff on coppermine-gallery.net will rename such plugins. Also please don't use abbreviations that don't mean anything - names like "dffds" for "damn fast flash-driven slideshow" are not easy to memorize - instead you should use something like "slideshow_flash"; if a user looks at the list of plugins on his gallery using his FTP application (during upload), it should be obious what plugin each sub-folder corresponds to.
  For details on a good name for your folder, please read up the sections "Naming conventions" and "Distributing Your Plugin" as well.

- ### 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 (see "Database access").

- ### 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';

  - #### $plugin_cpg_version

    Specify the minimum coppermine version number that your plugin will work with. It is advisable to only specify the major version (i.e. `'1.5'`) if you're not using a plugin hook that has been added to the core at a later stage.
    If you already know that limit, you can speficy a maximum version as well (although that's an optional feature).
    $plugin_cpg_version = array('min' => '1.5');
    The minimum version number you specify will be compared against the constant `COPPERMINE_VERSION` on the plugin manager page for the plugins that can be installed.

  - #### $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, the 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-digits 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.
  Example:
  `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

If you are going to use superglobals in your plugin, you will have to take notice of the Coppermine code sanitization.
You will also have to include the following line to make sure you can use these superglobals:
$superCage = Inspekt::makeSuperCage();
Double check this if you're getting a 500 error.

## Database access

A plugin can access the database in the same manner that core code is accessing the database. However, there are some things to keep in mind for plugin authors:

### Direct queries

Don't use the native PHP commands (like mysql_query) to perform queries against the coppermine database tables. Instead, use the function `cpg_db_query` built into coppermine. You don't need to explicitely open the connection - it is already established for you when using the plugin API.

Bad example | $result = mysql_query("SELECT * WHERE 1=1");
Good example | $result = cpg_db_query("SELECT * WHERE 1=1");

### Accessing database tables

Don't hard-code table names into your custom queries, as your queries are bound to break if users have chosen another table prefix than the default one.
Instead, coppermine defines a variable `$CONFIG['TABLE_PREFIX']` that contains the table prefix that you can (and should) use if you need to access a table within coppermine's database and using the prefix: use the prefix for custom tables for your plugin.

Bad example | $result = cpg_db_query("SELECT * FROM cpg15x_plugin_example WHERE 1=1");
Good example | $result = cpg_db_query("SELECT * FROM {$CONFIG['TABLE_PREFIX']}plugin_example WHERE 1=1");

If you want to access an existing table (like the coppermine table that contains all categories), use the variables outlined in Database reference within coppermine code.

Bad example | $result = cpg_db_query("SELECT * FROM {$CONFIG['TABLE_PREFIX']}categories WHERE 1=1");
Good example | $result = cpg_db_query("SELECT * FROM $CONFIG['TABLE_CATEGORIES'] WHERE 1=1");

### Creating database tables

If you need to expand the database schema of coppermine to add a table for your plugin, you should follow the following rules:

- Create your table within the same database that coppermine resides in
- Respect the naming scheme by prefixing your table name with the table prefix that the user has chosen during install (stored in `$CONFIG['TABLE_PREFIX']`), followed by the word "plugin" with an underscore, followed by the short name of your plugin (the "folder name of your plugin")
  If your plugin folder name was "coffee_maker", your plugin's table name would be `$CONFIG['TABLE_PREFIX']` . '_plugin_coffee_maker'
- During your plugin's install function, make sure that your table creation progress doesn't break if a user hasn't removed your plugin previously - it's recommended to use `CREATE TABLE IF NOT EXISTS` instead of just using `CREATE TABLE`
- Don't consume more resources than you need - define the types and dimensions of your plugin fields wisely

This could be an example for a database table creation query inside your plugin's install function:

    $query = <<< EOT
    	CREATE TABLE IF NOT EXISTS `{$CONFIG['TABLE_PREFIX']}plugin_coffee_maker` (
    	  `cid` mediumint(10) NOT NULL default '0',
    	  `some_field` smallint(6) NOT NULL default '0'
    	) COMMENT='Your clever description of the table here';
    EOT;
    $result = cpg_db_query($query);

### Deleting database tables

It's important that your plugin removes all tables it created during install when the end user uninstalls it. In some rare cases it might make sense to keep the database tables if the user decides to install it later again (if the re-population of the database table records would be time-consuming or complicated). If that's the case for your plugin, you should add a form to the uninstall process of your plugin that asks the end user if the database table should be kept or not. Out of the box, the database tables that were created during install need to be deleted when the plugin is uninstalled.
It's safer to use `DROP TABLE IF EXISTS` instead of just using `DROP TABLE`. To get rid of the table created in the example above, run a query like

    cpg_db_query("DROP TABLE IF EXISTS {$CONFIG['TABLE_PREFIX']}plugin_coffee_maker");

in the uninstall function of your plugin.

### Storing your plugin's config values

If you need just a few database records to store your plugin's config settings, you don't have to create a separate table just for those few plugin config records - instead, you're encouraged to use the existing config table where coppermine stores it's core settings in as well. There are some great benefits in using the existing config table: the main benefit is that you don't have to run a query to get your setting's values - coppermine's core code will populate the `$CONFIG`-array insteadd accordingly.
It's important though that it get's obvious what your config records are being used for and from which plugin they come from. That's why there is a strict naming schema for new records in coppermine's config that a plugin should adhere to: prefix the record with the word "plugin" followed by an underscore followed by your plugin's short name followed by an underscore followed by the actual config setting name.
To make sure that your script doesn't break if such a setting already exists (e.g. if the user re-installs your plugin that hasn't been uninstalled properly before) it's advisable to use `INSERT IGNORE` instead of using an ordinary `INSERT`.
If your plugin's short name is "coffee_maker" and you need to store a setting for the height of the coffee mug with the default value of 20, the corresponding setting record could be named `plugin_coffee_maker_mug_height`
The query in the install section of your plugin could be something like

    cpg_db_query("INSERT IGNORE INTO {$CONFIG['TABLE_CONFIG']} ( `name` , `value` ) VALUES ('plugin_coffee_maker_mug_height', '20')");

and the corresponding line inside the uninstall section would be

    cpg_db_query("DELETE FROM {$CONFIG['TABLE_CONFIG']} WHERE name = 'plugin_coffee_maker_mug_height'");

The resulting element inside the `$CONFIG` array would be `$CONFIG['plugin_coffee_maker_mug_height']`

## Plugin Types

Plugins (or rather individual pages of a plugin) can roughly fall into two categories: they can reside on a page of their own (a good example would be the plugin config screen some plugins come with or a plugin that adds a contact form) or they can reside within each or some coppermine-driven pages, modifying the output or functionality of the pages they reside on (a good example would be plugins that add menu items).
It is comparatively easy to come up with plugins that fall into the first category (creating additional pages). The second option is the more advanced and powerfull option that plugins authors can use. For this purpose, there are "anchors" all over coppermine's core code that allow plugin interaction with the code, the so-called "plugin hooks".

## Using includes

Files the plugin is meant to include on the index page of the gallery can only contain one single dot that separates the actual filename from the php-extension, as suggested in "Linking to Custom Plugin Scripts"

## 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
  The tutorial is the next logical step to follow after having read the quick start guide
- Creating plugins: step by step
  Step-by-step instructions how to come up with a plugin of your own
- 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.
- Global Variables & Constants in Coppermine

## Recommended reading

Although primarily written for dev team members it's recommended for plugin authors to review the coding guidelines for coppermine.