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

Integrating the script with another application (bridging)

What bridging does

Coppermine can be integrated with other applications in terms of user management and sharing a common login on your overall website; this is what we call "bridging". It can create a more seamless end user experience, as your users will only have to register once; their login will stick both on the Coppermine pages as well as the pages you bridge with.

By default, bridging is turned off, and those who do not want to use it can safely leave it off forever. There are however issues when bridging at a later stage (after there is already content in Coppermine), so if you intend to use bridging you should enable it before you start adding content.

Originally, Coppermine bridging was designed to bridge with BBS apps. Later, bridges for other apps (that don't fall into the category "BBS") have been added - mostly Content Management Systems (CMS). However, the reference to BBS apps remained in some documents and strings. No reason to get alarmed.

Bridging does not integrate your gallery and the application you bridge with in terms of visual appearance. If you want a seamless visual integration, create a custom theme for your gallery that matches the look of your bridge app or your overall site and add links pointing from Coppermine's navigation to your bridge app and vice versa.

When bridging is turned on, Coppermine drops the user management it comes with and uses the user management of the app you bridge with (i.e. your BBS app). Subsequently, your users will register and log in on your bridge app (BBS). After they do, they may be redirected to coppermine (if they came from coppermine's login page in the first place and your bridge app allows redirects).

Available bridge files

Coppermine can be integrated with the following applications (eg. Coppermine and your bulletin board will share the same user database).

• Invision Power Board
• Mambo
• MyBB
• Phorum
• phpBB 2
• phpBB 3
• PunBB 1.15
• PunBB 1.2 (also works with FluxBB 1.2)
• SMF 1.x
• SMF 2.x
• vBulletin
• XMB
• Xoops2

Pre-requistes

Authentication by cookie

The login integration uses your bulletin board cookies, therefore it won't work if your board cookies are not visible by Coppermine. So unless you are an expert, keep things simple and install Coppermine and your bridge app on the same domain.

The cookie path in the forum's configuration should be set to '/' where this option is available.

The cookie names of your bridge app and coppermine must not be the same - they must differ!

Some bridging apps have an option to enable sub-domain independant cookies that you should enable if you own the entire domain.

Some bridging apps use a cookie path by default that will make the cookie only available for the bridging app itself and not for other apps that reside in different folders on the webserver. If this is the case for you, you have to review your bridging app's config first and make sure that it is set to allow the cookie from the bridging app to be read by coppermine.

In SMF 1.1.x, the setting is named "local storage of cookies". When enabled, the cookies issued by SMF will be accessible only for the forum and not for other apps. Therefore, when bridging Coppermine with SMF, you have to go to SMF's admin panel first and turn local storage of cookies off. In SMF, that option can be found under "Admin" → "Server Settings" → "Feature configuration" → "Enable local storage of cookies".
For other bridging apps, the setting may be named differently and may reside in a different navigation structure, but the result should be the same: the cookie issued by the bridging app should be stored in a way that makes it accessible for other apps on the same domain.

In many recent BBS apps you can specify whether you want to handle authentication of users by cookie or by session. If you want to bridge, you have to make sure that the app you bridge with is using cookies as authentication method - coppermine doesn't work with session-driven authentication!

Standalone version first

To avoid confusion, make sure to set up both coppermine and your bridge app as standalone first. Make sure they both run correctly without integration. Test all features of coppermine (like upload, registration etc.) when Coppermine is installed, before you even start integration.

Coppermine users, groups and pics uploaded by users are lost when integrating

Warning: If you already have users and custom groups in your coppermine database when you enable bridging, be aware that they will be lost. If your coppermine users have already created private albums and uploaded pics to them, they will be lost as well!

Detailed explanation:
As most community applications, coppermine stores everything that users (including the admin) do (like uploading pics, posting comments, rating files) inside the database. The reference to each user action is being kept using a unique user ID. The correlation between the user actions and the corresponding user profile is being kept by storing the user ID within each record in the database that determines the user action.
When bridging is enabled, coppermine's user management is being dropped in favor of the user management that comes with the application you bridge with. Subsequently, the user IDs from your bridging app (that differ from Coppermine's user IDs) are being taken into account.

Summary:
Correlation between the actions that the unbridged coppermine users have performed and the "new" accounts from the app you bridged with is lost. Subsequently, you don't actually lose files that have been uploaded previously, but they appear to have been uploaded by a different user.

Backup

It is very advisable to backup both your coppermine database and your files before enabling bridging, so you can safely go back if the integration fails.

In fact you're encouraged to backup your database on a regular basis, and especially before applying code changes.

However, don't be afraid that bridging might cause your bridging app to malfunction: coppermine doesn't harm your forum (or the app you bridge with) at all. When enabling bridging, coppermine doesn't run write/alter queries against the bridging app's database tables nor does coppermine modify any of the files of the bridging app. The worst thing that may happen if something goes wrong is your coppermine gallery becoming inaccessible. It is completely impossible that coppermine bridging will do harm to your bridging application.

Integration steps

From cpg1.4.x on you can use the Bridge Manager that will provide a wizard-like interface to enable/disable bridging.

Using the bridge manager

The bridge manager is a new feature in cpg1.4, it is not available in older versions. Instead of manually editing coppermine code files, you can enable/disable bridging in your browser, using a wizard-like user interface. To start the bridge manager, log in as admin, choose "Bridge Manager" from the admin menu.

Note: with each step in the wizard, some information is being written to the coppermine database. Unlike other wizards (mostly on your local machine), the bridge manager doesn't have a "cancel" button! Once you have enabled bridging and everything is working fine, you shouldn't change any values just out of curiosity, as they will get written to the database, which might result in a bridging that used to work not working any more after "playing" with it.

Side-note
If you have a custom-made bridge file, just copy that bridge file into coppermine's bridge folder and it will show up on the bridge manager interface (the bridge file must reside in the coppermine sub-folder "bridge").

If a reset button () is displayed next to an input field, the field value doesn't have the default value. It can be perfectly OK to have a non-default value in a field, however you should keep in mind that if you have "played" with the bridge manager before, previous settings might exist in a field that are not correct - do not light-heartedly skip a step without paying attention to it. Use the reset button to revert to the default value (not necessarily "your" default value though).

Choose application to bridge coppermine with

In the first actual step of the wizard "choose application to bridge coppermine with", you have to choose the application you actually want to coppermine with. Note that you must have this application already installed on your webserver, it has to be properly configured and must be up-and-running. Don't use the bridge manager yet if you only plan to integrate coppermine with another application later.

Choose one of the available bridge files

Click "next"

The next steps

The next steps depend on the application you have chosen to bridge with: some applications need URLs to be entered, or paths. Some need cookie data to be entered, others don't. The point of the wizard is that it will only "ask" you the relevant settings for your application - if one or more items of the following description doesn't turn up for your application, there's no need to worry - just keep filling in the mandatory information and then hit "next". However, you have to understand that coppermine can proof-check only some of your input - some input goes unvalidated.

Path(s) used by your bridge app

There are various different ways used by coppermine's bridging mechanisms to get connected to the bridge application. Basically, the settings made in the bridge manager at this stage "tell" coppermine where your bridge app resides at and where the bridge app's config file is located that contains data that is being used by coppermine to "hook up" to the bridge app. As there are different approaches of bridge apps how this can be done, the method used in the bridge wizard might differ, depending on the bridge app you picked in the first step of the wizard. Therefore, not all of the settings mentioned below will apply for you. Just run the wizard and then look up the needed settings and enter them carefully.

• Bridge app URL

  Full URL of your bridge app folder (including the leading http:// bit, e.g. http://www.yourdomain.tld/forum).

  Please note that you mustn't specify a file at the end of the URL - if your bridge app actually resides at http://www.yourdomain.tld/forum/index.php, just specify the URL of the folder that contains the bridge app's index file.

• Absolute bridge app path

  Absolute path to your bridge app seen from the webroot

  • If your bridging app is at http://www.example.com/forum/, enter /forum/ into this field
  • If your bridging app is at http://www.example.com/foo/bar/, enter /foo/bar/ into this field

  You have to understand that this setting is not the absolute path on file system level on your web-server, but only the absolute path seen from the webroot.

  On file system level of your web-server, the absolute path your webroot might be something like /var/www/your_account_name/public_html/. Subsequently, the app you bridge with might reside in an absolute path on file system level like this: /var/www/your_account_name/public_html/forum/. Your coppermine gallery might reside in an absolute path on file system level that looks like this: /var/www/your_account_name/public_html/gallery/. However, it's the webroot folder that matters in this aspect - coppermine doesn't dig deeper on file system level and doesn't take the absolute paths into account that you might be using with other applications or to include files - it just uses the path seen from the webroot (the stuff that can be accessed directly in the browser). Hence, in this example the absolute path seen from the webroot would be /forum/ - nothing more, nothing less.

• Relative path to your bridge app's config file

  Relative path to your bridge app, seen from your Coppermine folder (e.g. "../forum/" if your bridge app is at http://www.yourdomain.tld/forum/ and Coppermine at http://www.yourdomain.tld/gallery/)

  A relative path does not start with a slash - that's the visual difference to an absolute path. You need to think on folder/sub-folder level to understand the concept of relative paths. Imagine that all folders on your webserver where the branches of a tree that was turned upside down: the root being at the top and branches going to the bottom. The relative path describes the way you need to take from a particular folder (the folder where coppermine resides in) to another folder (the folder where your bridge app resides in). The notation for relative paths contains a special way to say "one level up": that's two dots, followed by a forward slash (../). This being said, let's look at some examples:

  Your coppermine install	Your bridge app install	Relative path
  http://example.com/gallery/	http://example.com/forum/	../forum/
  http://example.com/gallery/	http://example.com/community/board/	../community/board/
  http://example.com/pictures/coppermine/	http://example.com/bbs/	../../bbs/
  http://example.com/gallery/	http://example.com/	../
  http://example.com/	http://example.com/forum/	forum/
  http://example.com/community/pix/	http://example.com/community/	../
  http://example.com/some/very/complicated/folder/	http://example.com/	../../../../
  http://example.com/gallery/	http://example.com/community/forum/	../community/forum/

• Cookie prefix

  This has to be the cookie name of the application you bridge with. Do not enter the cookie prefix of your coppermine gallery here! You can not make this setting up - you have to look it up in the documentation or settings that come with the application you're going to bridge with.

  The popular BBS application "phpBB2" is using the default cookie prefix phpbb2mysql - this can be changed by the forum administrator, so if you're not sure what your cookie prefix is, go to the config panel of the app you bridge with and look the cookie prefix up.

  The cookie prefix must not be confused with the cookie path - they are entirely different animals. The cookie prefix (in some applications it is being called "cookie name" as well) is something on application level - something the people who designed your bridge app have come up with.

Bridge app-specific settings

• Use bridge app custom groups?

  Should Coppermine import the special groups that exist in your bridge app? If you select no, then Coppermine will use the standard groups it comes with (Administrator, Registered and Anonymous) which makes administration easier. If you enable this option by selecting yes, you will have a more granular permissions management in coppermine and you can assign permissions in coppermine based on the membership within custom groups of your bridge app. You can change this setting later as well.

Enable/disable bridging

This is the last step of the bridge manager - it summarizes up the settings you have made in previous steps - you can enable or disable integration here. By default, integration is set to "disabled" after the bridge manager has been run for the first time. You should only enable integration if you're sure your bridge app is set up correctly. Click the "Finish" button in any case to finally write to the database, even if you choose to keep the current settings (leaving integration "disabled").

• Enable integration/bridging with XXX

Recover from failed bridging

If you have provided improper settings using the bridge manager, your integration might fail, resulting (in the worst case) in a stituation where bridging is enabled, but you can not log in as admin to switch it off again (e.g. if you provided improper cookie settings that stops authentication from working). For this situation a recovery setting was built into the bridge manager: if you are not logged in as coppermine admin (in fact: not logged in at all) and you access the URL of your bridge manager (http://yourdomain.tld/your_coppermine_folder/bridgemgr.php) by entering it manually into the address bar of your browser, you are prompted to enter your admin account details - use the admin account you used to install coppermine with in the first place (the standalone admin account). This will not log you in, but switch integration off, so you can fix improper bridging settings then. To avoid others trying to guess your admin account details, there's a login threshold that rises every time you enter wrong credentials, so enter your admin account details with care.

Synchronising the bridge app groups with Coppermine's groups

Login using the admin account of your board. Go to the gallery, enter admin mode and click on the "Groups" button. This will synchronize Coppermine groups with those of your board. The permission you will see for each group will be completely messy, so take some time to set them properly.

Each time you add or delete a group in your board you will need to do the operation above in order to keep the synchronisation of the groups.

When you will try to login / logout or manage users from Coppermine, you will be redirected to the corresponding page of your bulletin board. Once the login or logout is performed you won't be redirected automatically to the gallery because your board does not have any function for that. It's up to you to add a link on your board to get you back to the gallery.

It's mandatory that you (as admin) go to the groups page directly after bridging or whenever you change anything in your bridging configuration or if you change anything in your groups settings on your bbs, as you need to trigger the re-sync.

Bridging support

With the explanations given above you should be able to bridge your (BBS) application with Coppermine. However, if things don't work as expected, you're welcome to look for help using the coppermine support board. When asking for support, please keep in mind that the supporters will need some information to enable them to help you:

• Search the board before posting - maybe somebody had similar issues to yours that have been solved already
• Post on the board that deals with your version - bridging mechanisms have changed from version to version, that's why it's important to post on the board that actually corresponds to your coppermine version
• Don't hijack threads - when looking for bridging support, start your own thread
• Read the sticky threads before posting
• Make sure you are using the latest versions of the bridging files, they are kept up to date between formal Coppermine releases. Download the relevant files from the SVN. Update udb_base.inc.php and the file that corresponds to the bridge you are using and upload them into your bridge directory, overwriting the old ones. Of course you should make sure to use the most recent stable coppermine release in the first place.
• When requesting bridge support, please post a link to your site, a test user account, and what you have set in the bridge manager.
  Make sure that the test user account doesn't have admin privileges. When posting the requested data, make sure to replace passwords with asterisks.
   
  This is how your posting should look like (with actual data from your setup instead of the dummy placeholders given here as an example - highlighted in red):
  

  I have the following issue when trying to bridge coppermine and XXX:
  [error message or problem description here]
  
  Coppermine install: http://mysite.tld/my_coppermine_folder/
  Bridging app install: http://mysite.tld/my_forum_folder/
  Coppermine version: cpg1.5.0
  Bridging app version: SuperDuper BBS app v0.8.15
  Test user account: some_testuser_name / the_password_for_the_test_user_account
  
  BridgeManager settings:
  Bridge app URL:  http://mysite.tld/test/foo_bar
  Relative path to your bridge app's config file:  ../bla/
  Cookie name or prefix:  forum
  Use post-based groups?:  1  

• Supporters need to look at the pages in question - make sure that you have bridging actually enabled when asking for support
• The test user account you're supposed to post must not be an admin account, but a regular user account. The test user account needs of course to be created in the application you bridge with, not a coppermine account (as coppermine's user management is being dropped when bridging, so there's no use for supporters to have a standalone coppermine account)

Some config options get disabled

As explained on this page, coppermine will drop the user management it comes with in favor of the user management of the bridging app if you enable bridging. Subsequently, coppermine config options that apply to coppermine's user management will no longer apply (e.g. the user profile fields). Therefore, the config options that apply only to a standalone, unbridged coppermine will be disabled on the config screen if bridging is enabled.

Bridging files

In coppermine's root folder, you will find a subfolder named "bridge" - this is where the bridge files reside in. When coppermine is run (i.e. a visitor browses a coppermine-driven page), coppermine includes the bridge file that relates to the app you have bridged with. Using this file, coppermine does what is needed to authenticate the visitor. Even if coppermine is not bridged at all, there is still a file that is being included from the bridge folder ("coppermine.inc.php") that determines what tables to use.

Usually, you should not edit the files within the bridge folder - in fact the only important thing that you have to remember is that coppermine needs the bridge folder and the contents even if you haven't enabled the bridging feature. Just leave the files as they are. Power users who really know their way around are of course welcome to edit the bridge files and adjust them to their needs.

There have been users who tried to "run" the bridge files themselves directly in your browser - this will not work and do nothing but result in an error message. The bridge files are not meant to be run standalone - they get included by coppermine during runtime. If you have no idea what this means, just ignore those files and leave all in place. It won't hurt to have bridge files reside on your webspace even if you don't use the bridge that corresponds to a particular bridge file.

Creating a custom bridge file

In theory, coppermine could be bridged with all forms of third party applications that have a user management/authentication. There are thousands of applications available that could be potential candidates. Just because of the sheer number of possible bridges, but as well because of other restrictions (non-free software, lack of time, lack of need), the coppermine devs can not come up with a huge number of bridge files. That's why there is only a comparatively small number of bridge files available. If you are looking for a bridge file for another application that is not being covered by the bridge files that come with coppermine out-of-the-box, you're welcome to search the coppermine support board if there already is an existing user-contributed bridge, or (even better) you're encouraged to come up with a bridge file of your own and publish it on the board. We (the coppermine dev team) have to rely on user contributions for most potential bridge candidates.

Sadly, there is no particular piece of documentation available (yet) that explains how to create a custom bridge file, so the best method to create your custom bridge file is to look at existing bridge files and modify one to fit your needs.

Bridging philosophy

The coppermine developers believe that the bridging mechanism should not interfere with the application coppermine is being bridged with. That's why a genuine bridge file that can be considered to go into coppermine's core code can not be designed to make edits to the bridging app's code nor is it an option that the database structure of the bridging app is being modified by queries performed by Coppermine.
The reason for our reluctance to allow bridging to interfere with the bridging app is that we don't want the bridging app to break if something goes wrong.

However, there are bridge files contributed by third parties that don't work in the unobstrusive manner that we propose (like the Mehdi bridge for Joomla). We don't claim that those third party bridges are bad - in fact we appreciate that those bridge files are being made available. You have to understand though that we can not support those third party apps. We recommend that you make backups before bridging when using those third-party apps.

Individual bridge issues

There are some additional remarks that apply to particular bridge files:

• phpBB3

  Logout redirection: to accomplish logout redirection when using the phpBB3 bridge file, you need to edit the phpbb file ucp.php:
  Find

  meta_refresh(3, append_sid("{$phpbb_root_path}index.$phpEx"));
  $message = $message . '<br /><br />' . sprintf($user->lang['RETURN_INDEX'], '<a href="' . append_sid("{$phpbb_root_path}index.$phpEx") . '">', '</a> ');

  and replace with

  meta_refresh(3, request_var('redirect', append_sid("{$phpbb_root_path}index.$phpEx")));
  $message = $message . '<br /><br />' . sprintf($user->lang['RETURN_INDEX'], '<a href="' . request_var('redirect', append_sid("{$phpbb_root_path}index.$phpEx")) . '">', '</a> ');

  Admin recognition for upgraded forums: if your forum has been upgraded from phpBB2 to phpBB3 you need to perform an additional step.

  Edit phpbb3.inc.php, find

  $this->admingroups = array(5);
  

  Change the 5 to the admin group in phpbb3. You can find this out by doing the following
  Go to your forum, log into AdminCP; click on the tab "Users and Groups" and go to "Manage groups". you'll see all your forum groups now and next to them 3 links (Settings/Members/Delete); click on "Settings" next to the group you want to give portal admin permissions. now take a look at the address line, which should similarly to this: http://yourdomain.com/phpbb3/adm/index.php?i=groups&sid=[randomnumbersandletters]&icat=12&mode=manage&action=edit&g=64 In our example above, the group's ID is 64;
  
  

• PunBB1.1.5

  For login/logout redirection:
  Edit punbb's login.php, find:

  $page_title = pun_htmlspecialchars($pun_config['o_board_title']).' / '.$lang_common['Login'];

  and add before it

   $redirect_url = (isset($_GET['redir'])) ? $_GET['redir'] : $redirect_url;

  Then find:

  redirect('index.php', $lang_login['Logout redirect']);

  and change to:

  redirect(isset($_GET['redir']) ? $_GET['redir'] : 'index.php', $lang_login['Logout redirect']);

• PunBB1.2

  For login/logout redirection:
  Edit punbb's login.php and find:

  $page_title = pun_htmlspecialchars($pun_config['o_board_title']).' / '.$lang_common['Login'];

  and add before it

  $redirect_url = (isset($_GET['redir'])) ? $_GET['redir'] : $redirect_url;

  Then find

  redirect('index.php', $lang_login['Logout redirect']);

  and change to

  redirect(isset($_GET['redir']) ? $_GET['redir'] : 'index.php', $lang_login['Logout redirect']);

• XMB

  Cookie fix (if your board is not installed to site root): edit XMB's file functions.php, find the function definition for put_cookie (c. line 1414) and add

  $path = '/';

  just inside the top of the function

Subdomain issues

There are a lot of users who frequently ask on the coppermine support board if bridging across sub-domains is possible: the answer is "yes", at least in theory. As suggested above, you can not bridge across different domains (using the word domain in a broader sense, it should actually be "second level domains"), but you can bridge across different subdomains of the second level domain if certain requirements are met that hardly can be influenced by the coppermine developers: the cookies from the domain where your bridge app resides on must be readable for coppermine and the both domains need to physically reside on the same server. This is the case for almost all users on shared webhosting.