cpmfetch updated to V2.2. August 2024.

[406man]

Recently I became aware of cpmfetch and thought it could be very useful to display images from the gallery that I run on a Wordpress site. My site uses CPG 1.6.26 and PHP 8.2.19. Unfortunately cpmfetch didn't run properly with this combination so I set about getting it working. Initial tests were successful and, as  I was impressed with what it could do, decided to fix the code where existing functionality didn't work properly, add new features and update the documentation. During the whole process I tried to maintain existing functionality but ran into lots of bugs which I've fixed. The code base used was release 2.0.1 which is the most recent "working" version. The original author Vuud released a development version 2.1.1 but this was incomplete so to avoid confusion I've numbered the new version 2.2.

There was a lot of interest in cpmfetch in the past so I'm submitting the updated code to this forum in the hope that other members will find it useful.

Thanks are due to a number of people who have updated cpmfetch in over the years since vuud moved on, particularly ron4mac who updated it to PHP 7 to make it compatible with CPG 1.6.x.  Thanks are also due to gmc who runs a copy of the cpmfetch documentation on his web site as the original site run by vuud is no longer active. Most of the documentation is still applicable but there have been a few changes and corrections. Gmc's site is here:
http://gallery.gmcdesign.com/cpmfetch/docs/basic/

While getting it working I found what for me was a major problem impacting categories when there is a hierarchy of categories. Whether it's a bug, feature or intended behaviour I don't know and will explain with an example.

Suppose you have a gallery for pictures of cities around the world and you have categories for the continent and country. The categories are  North America, South America, Europe
In the North America category are categories USA, Canada, Greenland.
Albums containing pictures are Los Angeles and Miami in the USA category, Toronto, Vancouver and Ottawa in the Canada category. Plus others.

You might want cpmfetch to choose a random picture from North America, expecting it to dig down to the Los Angeles, Miami, Toronto etc albums. But this wouldn't work and the set of pictures would be blank. As far as I can see from the code, this is because the code only drops down one level of categories to find albums. But the USA / Canada / Greenland categories below North America are two levels down in the hierarchy. It would only return some pictures if you picked the USA or Canada categories instead of North America. While this is workable it's more awkward than if cpmfetch worked by accessing every album in the hierarchy below a particular category. To fix this I've updated the category function so that it works down through the category hierarchy. In the example you just need to enter, for example, the category number for North America and all the city albums will be accessible.

The whole situation around owner has changed. Owner is another way of referring to the user who uploaded the image. The owner_name field was removed from the CPG database some time before version 1.6 so I've changed the code to use its replacement - owner id. This has meant a change to the $source parameter. By changing its name to ownerid rather than leaving it as owner it's clear that the meaning has changed.

I found it awkward to test the various functions of cpmfetch so created a couple of test programs. As this is a major area on its own I've created a separate forum topic. The first program is called testfetch.php. It's run in a web browser and displays the cpmfetch code and the pictures taken from Coppermine in the simplest possible way with no added CSS. The idea is that you can check and debug your cpmfetch calls in the test program and then, when you're happy, add them to your Wordpress site or whatever and finalise the formatting there. To run the test program use your web browser with a URL like this – tailored to suit your gallery:
https://yourgallery.com/whatever/cpmfetch/testfetch.php

The second test program creates a slideshow which cycles through a configurable number of images. A separate article describes the test programs in more detail.

A major feature I added is the use of separate files called Include files where the actual cpmfetch code goes. These are included into either the test program or web site when needed. They allow you to develop the cpmfetch setup using the test programs, then go to the web site to run them without making any changes once the initial setup is done. These are described in a separate article.

Here is an example of the cpmfetch code:
$options = array( 'imageheight' => '350', 'imagesize' => 'int' );
$objCpm-> cpm_viewRandomMediaFrom("album=256", 1, 3, $options);
In the above:
•   "album=256" is the $source parameter and is where cpmfetch searches for images. Note that only publicly visible images can be displayed
•   1 is the number of rows created
•   3 is the number of columns. Or number of images in the row if there's only one row.
•   $options is the $options array which is in the line above it

Some other examples of the main cpmfetch routine are below where I've changed the $source parameter. Only one of these is used at a time.
$objCpm-> cpm_viewRandomMediaFrom("cat=9:keyword=xyz", 1, 3, $options);
$objCpm-> cpm_viewRandomMediaFrom("ownerid=171",1, 3, $options);
$objCpm-> cpm_viewRandomMediaFrom("text=amsterdam",1, 3, $options);

High level documentation is provided in this forum thread.
Detailed documentation on the $options, $source and functions are provided in a .htm file in the cpmfetch main directory. Open this file in a web browser.

A separate article in this forum describes how to link Wordpress to a Coppermine gallery.

I hope other Coppermine users find this updated version useful. I've tried to maintain all the original functions although some changes have been required and I've also removed functions that were deprecated and duplicated other functions. It's inevitable in a complex program like cpmfetch that there will be some more bugs so if you find one that means you can't do what you want to, let me know in this forum by including:
- what you want to achieve
- a description of what happened
- the error message if you have one
- the cpmfetch code being used. Preferably attach the relevant include file to the forum topic.

-----------------------------------------------------
Major Bugs fixed

• PHP 8.2 deprecation warnings
• Option to use intermediate images failed if the image didn't exist. This is allowed by the rules of intermediate images if the full size image is smaller than the intermediate so I altered the code to use the full size image (Called large in cpmfetch terminology) if the intermediate doesn't exist
• Fetching images using keyword search caused a crash.
• getRandomSeed function generated error message
• Some of the options to set CSS style name and properties didn't work properly
• Replaced old problem.gif which was corrupted

New or substantially revised Features

• Works with CPG 1.6.26 and PHP 8.2.19.
• The actual cpm configuration commands optionally go in a separate file which is included into the test program or final website.
• A large number of example Include files containing cpmfetch commands are provided which can be used as a base rather than having to type everything in
• Slideshow runs and optionally displays a subtitle. Has a test program called testslideshow
• As described above, a category search will find images in the hierarchy below that category, rather than just albums with that category as their parent.
• Large images can be displayed in a separate screen by clicking on the fetched image using windowtarget= '_blank-js'
• New functions cpm_viewMediaFromAlbum and cpm_viewMediaFromCategory allow fetching of images in a way that matches the sequence in the CPG gallery thumbnail display. The same 8 sorting choices are available

Installing cpmfetch
The installation procedure is unchanged. Unzip the contents of the distribution file and move the directory tree so that cpmfetch is inside the Coppermine gallery family of directories. A standard gallery will have directories name albums, bridge, css etc. The cpmfetch must be beside these directories at the same level. If it is put anywhere else, cpmfetch will not work. Once it is in the right place run the installation procedure from a web browser:
https://yourgallery.com/yourgallerypath/cpmfetch/install.php
Check the output to be confirm that it has worked correctly.

-------------------------------------
Background
Cpmfetch is an add-on set of programs for Coppermine created by user vuud around 2006 for CPG 1.3.x. It's a versatile PHP program used for pulling images out of the Coppermine system for display in other web applications. The forum post by vuud here gives a lot of information on it:
https://forum.coppermine-gallery.net/index.php/topic,35450.0.html
Sadly vuud is no longer active in the Coppermine world and cpmfetch has drifted in recent times.