PHPackages                             opa/opa-php - 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. opa/opa-php

ActiveLibrary

opa/opa-php
===========

PHP library for generating and reading Open Prompt Archive (OPA) files

v1.0.1(1w ago)0383—0%[1 PRs](https://github.com/shannah/opa-php/pulls)MITPHPPHP &gt;=8.1CI passing

Since Mar 8Pushed 1w agoCompare

[ Source](https://github.com/shannah/opa-php)[ Packagist](https://packagist.org/packages/opa/opa-php)[ RSS](/packages/opa-opa-php/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (1)Versions (4)Used By (0)

opa-php
=======

[](#opa-php)

A minimal PHP library for generating, reading, signing, and verifying [Open Prompt Archive (OPA)](https://github.com/shannah/opa-spec) files.

OPA is a portable, ZIP-based archive format for packaging AI agent prompts together with session history, data assets, and execution metadata.

Requirements
------------

[](#requirements)

- PHP 8.1+
- Extensions: `zip`, `json`, `openssl`

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

[](#installation)

```
composer require opa/opa-php
```

Quick Start
-----------

[](#quick-start)

### Creating an archive

[](#creating-an-archive)

```
use OPA\OpaArchive;

$archive = new OpaArchive('Summarize the attached report.');
$archive->getManifest()
    ->setTitle('Report Summary')
    ->setExecutionMode('batch');

$archive->addDataFromString('data/report.csv', $csvContent);
$archive->save('summary-task.opa');
```

### Reading an archive

[](#reading-an-archive)

```
use OPA\OpaReader;

$reader = OpaReader::open('summary-task.opa');

echo $reader->getManifest()->getTitle();
echo $reader->getPromptContent();

if ($reader->hasSessionHistory()) {
    foreach ($reader->getSessionHistory()->getMessages() as $msg) {
        echo "[{$msg->getRole()}] {$msg->getContent()}\n";
    }
}

$reader->close();
```

### Signing and verification

[](#signing-and-verification)

```
use OPA\OpaArchive;
use OPA\Signer;
use OPA\Verifier;

// Sign on create
$signer = new Signer($privateKeyPem, $certificatePem);
$archive = new OpaArchive('Analyze the data.');
$archive->save('signed.opa', $signer);

// Verify
$result = Verifier::verify('signed.opa');
if ($result->isSigned() && $result->isValid()) {
    echo "Signature verified.\n";
}

// Verify against a specific trusted certificate
$result = Verifier::verify('signed.opa', $trustedCertPem);
```

API Reference
-------------

[](#api-reference)

### OpaArchive (builder)

[](#opaarchive-builder)

```
$archive = new OpaArchive(string $promptContent);
$archive->getManifest(): Manifest;
$archive->setSessionHistory(SessionHistory $history): self;
$archive->setDataIndex(DataIndex $index): self;
$archive->addDataFromString(string $archivePath, string $content): self;
$archive->addDataFromFile(string $archivePath, string $localPath): self;
$archive->addSessionAttachmentFromString(string $filename, string $content): self;
$archive->addSessionAttachmentFromFile(string $filename, string $localPath): self;
$archive->save(string $outputPath, ?Signer $signer = null): void;
```

### OpaReader

[](#opareader)

```
$reader = OpaReader::open(string $path): OpaReader;
$reader->getManifest(): Manifest;
$reader->getPromptContent(): string;
$reader->hasSessionHistory(): bool;
$reader->getSessionHistory(): ?SessionHistory;
$reader->hasDataIndex(): bool;
$reader->getDataIndex(): ?DataIndex;
$reader->getFileContent(string $archivePath): ?string;
$reader->listEntries(): array;
$reader->isSigned(): bool;
$reader->extractTo(string $directory): void;
$reader->close(): void;
```

### Manifest

[](#manifest)

```
$manifest->setTitle(string $title): self;
$manifest->setDescription(string $description): self;
$manifest->setCreatedBy(string $createdBy): self;
$manifest->setCreatedAt(string $createdAt): self;
$manifest->setAgentHint(string $agentHint): self;
$manifest->setExecutionMode(string $mode): self;       // interactive, batch, autonomous
$manifest->setPromptFile(string $promptFile): self;
$manifest->setSessionFile(string $sessionFile): self;
$manifest->setDataRoot(string $dataRoot): self;
$manifest->setSchemaExtensions(string $extensions): self;
```

### SessionHistory &amp; Message

[](#sessionhistory--message)

```
$history = new SessionHistory(
    sessionId: 'uuid-here',
    createdAt: '2026-03-01T10:00:00Z',
);
$history->addMessage(new Message(
    role: 'user',           // user, assistant, system, tool
    content: 'Hello',       // string or array of content blocks
    id: '1',
    timestamp: '2026-03-01T10:00:00Z',
));
```

### Signing

[](#signing)

```
// Signer supports SHA-256 (default), SHA-384, SHA-512
// MD5 and SHA-1 are rejected per spec
$signer = new Signer($privateKeyPem, $certificatePem, 'SHA-256');

// Sign an existing archive in place
$signer->sign('archive.opa');

// Or sign during creation
$archive->save('archive.opa', $signer);
```

### Verification

[](#verification)

```
$result = Verifier::verify('archive.opa');
$result->isSigned(): bool;    // whether signature files are present
$result->isValid(): bool;     // whether all verification checks passed
$result->getError(): ?string; // error message if verification failed
```

The verifier checks the full signature chain:

1. Digital signature on `SIGNATURE.SF`
2. Manifest digest matches actual `MANIFEST.MF`
3. Per-entry section digests in SF match manifest sections
4. File content digests in manifest match actual archive contents

Archive Structure
-----------------

[](#archive-structure)

```
archive.opa
├── META-INF/
│   ├── MANIFEST.MF            # Required manifest
│   ├── SIGNATURE.SF           # Signature file (if signed)
│   └── SIGNATURE.RSA          # Signature block (if signed)
├── prompt.md                  # Required prompt file
├── session/
│   ├── history.json           # Session history (optional)
│   └── attachments/           # Session attachments (optional)
└── data/
    ├── INDEX.json             # Data index (optional)
    └── ...                    # Data assets

```

Examples
--------

[](#examples)

See [`examples/generate-hn-pirate-summary.php`](examples/generate-hn-pirate-summary.php) — fetches the Hacker News RSS feed, bundles it into a signed OPA archive with a prompt asking an AI to summarize articles in pirate speak and output styled HTML.

```
php examples/generate-hn-pirate-summary.php
```

Testing
-------

[](#testing)

```
composer install
vendor/bin/phpunit
```

Specification
-------------

[](#specification)

This library implements the [OPA specification](https://github.com/shannah/opa-spec).

License
-------

[](#license)

MIT

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance98

Actively maintained with recent releases

Popularity18

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 75% 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

Every ~0 days

Total

2

Last Release

13d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d7e97280d632c68997f78c2552fe2e5f93da0786aa4ed58d514f2e5fc9060091?d=identicon)[shannah](/maintainers/shannah)

---

Top Contributors

[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (6 commits)")[![shannah](https://avatars.githubusercontent.com/u/2677562?v=4)](https://github.com/shannah "shannah (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/opa-opa-php/health.svg)

```
[![Health](https://phpackages.com/badges/opa-opa-php/health.svg)](https://phpackages.com/packages/opa-opa-php)
```

PHPackages © 2026

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