PHPackages                             inwebo/item-metadata - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. inwebo/item-metadata

ActiveLibrary[API Development](/categories/api)

inwebo/item-metadata
====================

PHP client library for the Internet Archive Item Metadata API

1.0.0(1mo ago)10MITPHPPHP >=8.1CI failing

Since Apr 23Pushed 1mo agoCompare

[ Source](https://github.com/inwebo/archive.org-item-metadata-api)[ Packagist](https://packagist.org/packages/inwebo/item-metadata)[ RSS](/packages/inwebo-item-metadata/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependencies (6)Versions (2)Used By (0)

Internet Archive Item Metadata API Client
=========================================

[](#internet-archive-item-metadata-api-client)

A PHP client library for the Internet Archive Item Metadata Write API. It allows you to programmatically update item metadata using JSON Patch (RFC 6902).

Overview
--------

[](#overview)

This library provides a clean, object-oriented interface to interact with the Internet Archive (IA) Metadata API. It simplifies the process of creating JSON Patch documents and sending them to the IA servers with proper authentication and formatting.

Key features:

- Fluent builder for JSON Patch operations (add, remove, replace, move, copy, test).
- Support for IA S3 authentication (Access Key and Secret Key).
- Handles double-encoding requirements of the Metadata API.
- Integration with Symfony HttpClient for robust networking.
- Specific helper for adding Wayback Machine URLs to user items.

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require inwebo/archive.org-item-metadata-api
```

API Documentation
-----------------

[](#api-documentation)

### ItemMetadataClient

[](#itemmetadataclient)

The main entry point for the library.

- `__construct(Credentials $credentials, HttpClientInterface $httpClient)`: Initializes the client.
- `patch(MetadataWriteRequest $request): MetadataWriteResponse`: Sends a JSON Patch request to the API.
- `addWebArchiveUrl(string $userIdentifier, string $archiveUrl, string $target = 'web-archive'): MetadataWriteResponse`: Convenience method to append a Wayback Machine URL to a specific target (usually for user-owned items).

### Credentials

[](#credentials)

Used to hold your Internet Archive S3 credentials.

- `__construct(string $accessKey, string $secretKey)`: Requires keys obtained from [archive.org/account/s3.php](https://archive.org/account/s3.php).

### JsonPatch

[](#jsonpatch)

A fluent builder to create RFC 6902 JSON Patch documents.

- `JsonPatch::create()`: Starts a new patch document.
- `add(string $path, mixed $value)`: Appends an "add" operation. Use `/-` to append to an array.
- `remove(string $path)`: Appends a "remove" operation.
- `replace(string $path, mixed $value)`: Appends a "replace" operation.
- `move(string $from, string $path)`: Appends a "move" operation.
- `copy(string $from, string $path)`: Appends a "copy" operation.
- `test(string $path, mixed $value)`: Appends a "test" operation.

### MetadataWriteRequest

[](#metadatawriterequest)

Encapsulates the data needed for a write operation.

- `__construct(string $identifier, string $target, JsonPatch $patch, int $priority = 0)`:
    - `identifier`: The IA item identifier (e.g., `my-item` or `@my-user`).
    - `target`: The metadata target (e.g., `metadata`, `files/picture.jpg`, or a custom user JSON target).
    - `patch`: The `JsonPatch` object containing operations.
    - `priority`: Optional task priority (defaults to 0).

### MetadataWriteResponse

[](#metadatawriteresponse)

The object returned after a successful API call.

- `isSuccess(): bool`: Returns true if the operation was successful.
- `getTaskId(): int`: Returns the IA task ID created for this update.
- `getLog(): string`: Returns the URL to the task log on archive.org.

Usage Examples
--------------

[](#usage-examples)

### Basic Metadata Update

[](#basic-metadata-update)

Updating the title and adding a collection to an item:

```
use Inwebo\ItemMetaData\ItemMetadataClient;
use Inwebo\ItemMetaData\Auth\Credentials;
use Inwebo\ItemMetaData\Patch\JsonPatch;
use Inwebo\ItemMetaData\Request\MetadataWriteRequest;
use Symfony\Component\HttpClient\HttpClient;

$client = new ItemMetadataClient(
    new Credentials('your_access_key', 'your_secret_key'),
    HttpClient::create()
);

$patch = JsonPatch::create()
    ->replace('/title', 'New Improved Title')
    ->add('/collection/-', 'opensource_movies');

$request = new MetadataWriteRequest(
    identifier: 'my-archive-item-id',
    target: 'metadata',
    patch: $patch
);

try {
    $response = $client->patch($request);
    echo "Success! Task ID: " . $response->getTaskId();
} catch (\Exception $e) {
    echo "Error: " . $e->getMessage();
}
```

### Adding a Wayback Machine URL

[](#adding-a-wayback-machine-url)

A common use case for specific user JSON targets:

```
$client->addWebArchiveUrl(
    userIdentifier: '@my_username',
    archiveUrl: 'https://web.archive.org/web/20240101000000/https://example.com'
);
```

License
-------

[](#license)

This project is licensed under the MIT License.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance90

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

47d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/845359?v=4)[Inwebo Veritas](/maintainers/inwebo)[@inwebo](https://github.com/inwebo)

---

Top Contributors

[![inwebo](https://avatars.githubusercontent.com/u/845359?v=4)](https://github.com/inwebo "inwebo (2 commits)")

---

Tags

archive-orgmetadata-apiwayback-machinemetadatajson patchinternet-archivearchive.orgwayback-machine

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/inwebo-item-metadata/health.svg)

```
[![Health](https://phpackages.com/badges/inwebo-item-metadata/health.svg)](https://phpackages.com/packages/inwebo-item-metadata)
```

###  Alternatives

[temporal/sdk

Temporal SDK

4082.7M22](/packages/temporal-sdk)[storyblok/php-management-api-client

Storyblok PHP Client for Management API

1229.6k2](/packages/storyblok-php-management-api-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)