4d10db4f17
PHP 8.4 library and CLI tools to read, modify, and generate ProPresenter 7 files: songs (.pro), playlists (.proplaylist), bundles (.probundle), themes, and the global library files (Macros, Labels, Groups, ClearGroups, CCLI, Messages, Timers, Stage, Workspace, Props, TestPatterns, Calendar, KeyMappings, CommunicationDevices). Built on the MIT-licensed ProPresenter7-Proto schema by greyshirtguy (v7.16.2). Includes 18 CLI parsers, comprehensive API docs in doc/, binary-format specs, and a synthetic 369-test PHPUnit suite covering RTF extraction, translation slides, ZIP64 repair, round-trip fidelity, and end-to-end generation.
111 lines
2.8 KiB
Markdown
111 lines
2.8 KiB
Markdown
# Messages Library API
|
|
|
|
> PHP module for reading and writing the global ProPresenter `Messages` file
|
|
> (raw protobuf, no extension) and exposing each message definition.
|
|
|
|
## Quick Reference
|
|
|
|
```php
|
|
use ProPresenter\Parser\MessagesFileReader;
|
|
use ProPresenter\Parser\MessagesFileWriter;
|
|
|
|
$library = MessagesFileReader::read('/path/to/Messages');
|
|
|
|
foreach ($library->getMessages() as $message) {
|
|
$message->getTitle();
|
|
$message->getUuid();
|
|
$message->getMessageText();
|
|
}
|
|
|
|
$library->addMessage('Lobby Notice', '11111111-1111-1111-1111-111111111111');
|
|
MessagesFileWriter::write($library, '/path/to/Messages');
|
|
```
|
|
|
|
---
|
|
|
|
## File Layout
|
|
|
|
The `Messages` file is the protobuf-serialised
|
|
[`MessageDocument`](../../proto/messages.proto):
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `application_info` | `ApplicationInfo` | ProPresenter metadata |
|
|
| `messages` | repeated `Message` | Message definitions in document order |
|
|
|
|
---
|
|
|
|
## Reading
|
|
|
|
```php
|
|
$library = MessagesFileReader::read('/Users/me/.../Messages');
|
|
```
|
|
|
|
Throws `InvalidArgumentException` for missing files and `RuntimeException` for
|
|
empty / unreadable files.
|
|
|
|
---
|
|
|
|
## MessageLibrary
|
|
|
|
```php
|
|
$library->getMessages(); // Message[]
|
|
$library->count(); // int
|
|
$library->getMessageByUuid($uuid); // ?Message (case-insensitive)
|
|
$library->getMessageByName($title); // ?Message (case-sensitive title)
|
|
$library->addMessage($title, $uuid); // Message
|
|
$library->removeMessage($uuid); // bool
|
|
$library->getApplicationInfo(); // ?\Rv\Data\ApplicationInfo
|
|
$library->getDocument(); // \Rv\Data\MessageDocument
|
|
```
|
|
|
|
---
|
|
|
|
## Message
|
|
|
|
```php
|
|
$message->getUuid();
|
|
$message->setUuid($uuid);
|
|
$message->getTitle();
|
|
$message->setTitle($title);
|
|
$message->getTimeToRemove();
|
|
$message->setTimeToRemove($seconds);
|
|
$message->isVisibleOnNetwork();
|
|
$message->setVisibleOnNetwork(true);
|
|
$message->getMessageText();
|
|
$message->setMessageText($text);
|
|
$message->getClearType();
|
|
$message->setClearType($enumValue);
|
|
$message->getTokens(); // raw repeated Token protos
|
|
$message->getProto(); // \Rv\Data\Message
|
|
```
|
|
|
|
---
|
|
|
|
## CLI Tool
|
|
|
|
```bash
|
|
php bin/parse-messages.php /path/to/Messages
|
|
```
|
|
|
|
---
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `src/MessageLibrary.php` | Document wrapper with title / UUID indexes |
|
|
| `src/Message.php` | Single message wrapper |
|
|
| `src/MessagesFileReader.php` | Reads the `Messages` file |
|
|
| `src/MessagesFileWriter.php` | Writes the `Messages` file |
|
|
| `bin/parse-messages.php` | CLI summary tool |
|
|
| `generated/Rv/Data/MessageDocument.php` | Generated document class |
|
|
|
|
---
|
|
|
|
## Scope Notes
|
|
|
|
Tokens and token values are preserved as raw generated protobuf objects. The
|
|
wrapper exposes them for advanced callers but does not interpret template
|
|
rendering semantics.
|