ContentDM Explorer BETA

A PHP library for interacting with OCLC's ContentDM digital collection management system. Fetch collections, query items, retrieve metadata, and export data with ease.

Beta Notice

This library is currently in beta. While functional, some features may change and there may be undiscovered bugs. Use with caution in production environments.

Overview

This library provides a clean PHP interface to ContentDM's web services API. It includes:

skeleton.php — A minimal starting template
functions.php — Full-featured function library

Official Documentation

For complete API reference, see the OCLC ContentDM API Documentation.

Installation

Copy the files to your project directory:

📁 your-project/

📄 functions.php

📄 skeleton.php

📄 your-script.php

Include the functions library in your script:

require_once 'functions.php';

Quick Start

Get up and running in 3 lines of code:

<?php
require_once 'functions.php';

// 1. Initialize with your ContentDM server
cdm_init('https://cdm12345.contentdm.oclc.org');

// 2. Fetch all collections
$collections = cdm_get_collections();

// 3. Display them
foreach ($collections as $coll) {
    echo $coll['name'] . "\n";
}

API URL Patterns

Understanding ContentDM's URL structure:

Web Services API

https://{server}.contentdm.oclc.org/digital/bl/dmwebservices/index.php?q={function}/json

Image API

https://{server}.contentdm.oclc.org/digital/api/singleitem/image/{alias}/{pointer}/default.jpg

Common API Functions

Function	Description
`dmGetCollectionList`	List all collections on the server
`dmGetCollectionFieldInfo/{alias}`	Get metadata field definitions for a collection
`dmQuery/{alias}/{search}^.../{fields}/{limit}/{start}`	Search and retrieve items from a collection
`dmGetItemInfo/{alias}/{pointer}`	Get full metadata for a single item
`dmGetImageInfo/{alias}/{pointer}`	Get image dimensions and file info

skeleton.php

A minimal, self-contained script for quick prototyping. Use this as a starting point for simple projects or to understand how the API works.

Features

Single file, no dependencies
~100 lines of well-commented code
One simple cdm_api() function
Built-in HTML output with quick reference

Structure

// Configuration
$CDM_SERVER = 'https://cdm12345.contentdm.oclc.org';

// Helper function
function cdm_api($function) { ... }

// Fetch and display
$collections = cdm_api('dmGetCollectionList');

functions.php

A comprehensive function library for production use. Includes initialization, validation, querying, URL building, and CSV export capabilities.

Features

Global configuration management
Server URL validation
Automatic pagination handling
URL builder functions
CSV export with UTF-8 BOM
System field filtering

Tip

Always call cdm_init() before using any other functions from this library.

Initialization Functions

cdm_init($serverUrl)

Initialize the CDM API with a server URL. Must be called before using other functions.

Parameter	Type	Description
$serverUrl	string	ContentDM server URL (e.g., `https://cdm12345.contentdm.oclc.org`)

Returns: bool — True if valid URL, false otherwise

cdm_get_config()

Get the current configuration array including server, api_base, image_base, and timeout.

Returns: array — Configuration array

Core API Functions

cdm_api($function)

Make a raw API call to ContentDM. Low-level function that other functions use internally.

Parameter	Type	Description
$function	string	API function string (e.g., `"dmGetCollectionList"`)

Returns: array|null — Decoded JSON response or null on error

// Example: raw API call
$result = cdm_api('dmGetCollectionFieldInfo/photos');

cdm_validate_server($serverUrl)

Validate a ContentDM server URL by testing the API connection and fetching collections.

Parameter	Type	Description
$serverUrl	string	Server URL to validate

Returns: array — ['valid' => bool, 'error' => string|null, 'collections' => array|null]

Collection Functions

cdm_get_collections()

Get all collections from the server.

Returns: array|null — Array of collection objects with alias, name, path

$collections = cdm_get_collections();
foreach ($collections as $c) {
    echo $c['name'] . ' (' . $c['alias'] . ")\n";
}

cdm_get_collection_fields($alias)

Get metadata field definitions for a collection.

Parameter	Type	Description
$alias	string	Collection alias

Returns: array|null — Array of field definitions with name, nick, type, etc.

Item Functions

cdm_get_items($alias, $limit, $start, $search, $fields)

Query items from a collection with pagination support.

Parameter	Type	Default	Description
$alias	string	—	Collection alias required
$limit	int	100	Number of items to return optional
$start	int	0	Starting position for pagination optional
$search	string	"."	Search string (. for all) optional
$fields	string	"!title!creato"	Fields to return optional

Returns: array|null — Object with records array and pager info

cdm_get_all_items($alias, $maxItems)

Get all items from a collection, automatically handling pagination.

Parameter	Type	Default	Description
$alias	string	—	Collection alias required
$maxItems	int	1000	Maximum items to fetch optional

Returns: array — Array of all item records

cdm_get_item_info($alias, $pointer)

Get full metadata for a single item.

Parameter	Type	Description
$alias	string	Collection alias
$pointer	string	Item pointer/ID

Returns: array|null — Complete item metadata

cdm_get_image_info($alias, $pointer)

Get image information (dimensions, file size) for an item.

Parameter	Type	Description
$alias	string	Collection alias
$pointer	string	Item pointer/ID

Returns: array|null — Image info with width, height, etc.

cdm_get_item_count($alias)

Get the total number of items in a collection.

Parameter	Type	Description
$alias	string	Collection alias

Returns: int — Total item count

URL Builder Functions

cdm_get_image_url($alias, $pointer, $size)

Build the image URL for an item.

Parameter	Type	Default	Description
$alias	string	—	Collection alias
$pointer	string	—	Item pointer/ID
$size	string	"default"	Size: 'default', 'thumbnail', or pixel width

Returns: string — Full image URL

$url = cdm_get_image_url('photos', '123');
// https://server.../digital/api/singleitem/image/photos/123/default.jpg

cdm_get_item_url($alias, $pointer)

Build the public item page URL.

Returns: string — Full item page URL

$url = cdm_get_item_url('photos', '123');
// https://server.../digital/collection/photos/id/123

cdm_get_collection_url($alias)

Build the public collection page URL.

Returns: string — Full collection page URL

Export Helper Functions

cdm_export_csv($items, $skipFields)

Convert an array of items to CSV format with UTF-8 BOM for Excel compatibility.

Parameter	Type	Default	Description
$items	array	—	Array of item data
$skipFields	array	[]	Additional fields to exclude

Returns: string — CSV content ready to save or download

cdm_get_items_for_export($alias, $maxItems)

Get complete item data (with full metadata) ready for CSV export.

Parameter	Type	Default	Description
$alias	string	—	Collection alias
$maxItems	int	1000	Maximum items to fetch

Returns: array — Array of complete item data including _pointer and _collection

Performance Note

This function makes an API call for each item to fetch full metadata. For large collections, this can be slow.

Utility Functions

cdm_clean_alias($alias)

Remove leading slash from a collection alias.

Returns: string — Cleaned alias

cdm_filter_item_fields($item, $keepFields)

Remove system fields from item data, keeping only meaningful metadata.

Parameter	Type	Description
$item	array	Item data array
$keepFields	array	Additional fields to keep (optional)

Returns: array — Filtered item data

Filtered fields: dmaccess, dmimage, dmcreated, dmmodified, dmoclcno, dmrecord, restrictionCode, cdmfilesize, cdmfilesizeformatted, cdmprintpdf, cdmhasocr, cdmisnewspaper, find

Example: Basic Usage

<?php
require_once 'functions.php';

// Initialize
cdm_init('https://cdm12345.contentdm.oclc.org');

// Get collections
$collections = cdm_get_collections();

echo "Found " . count($collections) . " collections:\n\n";

foreach ($collections as $coll) {
    $alias = ltrim($coll['alias'], '/');
    $name = $coll['name'];
    $count = cdm_get_item_count($alias);
    
    echo "• {$name} ({$alias}) - {$count} items\n";
}

Example: Export to CSV

<?php
require_once 'functions.php';

cdm_init('https://cdm12345.contentdm.oclc.org');

// Get all items with full metadata
$items = cdm_get_items_for_export('photos', 500);

// Convert to CSV
$csv = cdm_export_csv($items);

// Save to file
file_put_contents('photos_export.csv', $csv);

echo "Exported " . count($items) . " items to photos_export.csv\n";

Example: Image Gallery

<?php
require_once 'functions.php';

cdm_init('https://cdm12345.contentdm.oclc.org');

// Get first 20 items from a collection
$result = cdm_get_items('photos', 20);
$items = $result['records'] ?? [];
?>

<!DOCTYPE html>
<html>
<head>
    <title>Photo Gallery</title>
    <style>
        .gallery { display: grid; grid-template-columns: repeat(4, 1fr); gap: 15px; }
        .gallery img { width: 100%; height: 200px; object-fit: cover; border-radius: 8px; }
    </style>
</head>
<body>
    <div class="gallery">
        <?php foreach ($items as $item): ?>
            <a href="<?= cdm_get_item_url('photos', $item['pointer']) ?>">
                <img src="<?= cdm_get_image_url('photos', $item['pointer']) ?>"
                     alt="<?= htmlspecialchars($item['title'] ?? '') ?>">
            </a>
        <?php endforeach; ?>
    </div>
</body>
</html>

Developed independently by Christian Abou Daher