public/propresenter7-php-lib
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
propresenter7-php-lib/doc/internal/decisions.md
Thorsten Bus 8e80a8af88 Upgrade proto schema to ProPresenter Proto 19beta 
Sync the bundled .proto definitions with greyshirtguy/ProPresenter7-Proto
"Proto 19beta" (dumped from ProPresenter v19 beta build 318767123,
2025-06-05). This pulls in the schema for ProPresenter 19 features
including new advertisement groups, custom options, media metadata,
prop API v1, transport API, feature flags, PSB workspace, and zone
definitions, plus refactored analytics tracked events.

Strategy: merge rather than wholesale replace. All Proto 19beta files
overwrite our existing copies so we pick up the field/message updates
upstream made between 7.16.2 and 19beta. Eleven new .proto files are
added: advertisementGroup, analyticsEdit, analyticsMediaManagement,
analyticsPowerPoint, analyticsTrackedEvents, analyticsTriggerCue,
customOptions, mediaMetadata, proCoreFeatureFlags, psbWorkspace, zone.
Three google/protobuf well-known types (any, source_context, type) are
added for completeness; only descriptor.proto is actually imported.

Five proto files are kept that are not part of Proto 19beta upstream:
calendar.proto and keyMappings.proto were extracted from PP binaries
to support our parse-calendar and parse-key-mappings tools, while
analyticsCapture/Update/WHMStore.proto are retained from the prior
7.16.2 set so existing generated descriptors keep loading.

generated/ is regenerated from scratch with `protoc --php_out=generated
--proto_path=proto *.proto` (protoc 29.3, google/protobuf PHP 4.33.5).
The full PHPUnit suite (369 tests, 1298 assertions) still passes
without any source changes - the new schema is wire-compatible with our
reference files and high-level wrappers.

Documentation references to "v7.16.2" are updated to "Proto 19beta" in
LICENSE, doc/formats/pp_song_spec.md, pp_playlist_spec.md,
pp_bundle_spec.md, and doc/internal/decisions.md.
2026-05-04 07:19:24 +02:00

1.6 KiB
Raw Blame History

Architectural Decisions

Decisions Made

Proto Version Choice

  • Decision: Use greyshirtguy/ProPresenter7-Proto, Proto 19beta (dumped from ProPresenter v19 beta build 318767123)
  • Reason: Latest available proto schema; field numbers compatible with our reference files; covers new ProPresenter 19 features
  • Retained extras: calendar.proto, keyMappings.proto (not present in 19beta upstream but extracted from PP binaries to support our parse-calendar and parse-key-mappings tools); analyticsCapture/Update/WHMStore.proto retained from the prior 7.16.2 set for backward compatibility
  • History: Originally adopted v7.16.2 (Metis analysis + typed decode validation in T2); upgraded to Proto 19beta on 2026-05-04

RTF Handling

  • Getters: Plain text only (via RtfExtractor)
  • Internal: Raw RTF preserved for round-trip integrity
  • Write: Template-clone approach (preserve formatting, swap text only)

Scope Boundaries

  • IN: Read+write existing content, parse all reference files

  • OUT: Creating new slides/groups from scratch, Laravel integration, playlist formats

  • 2026-03-01 task-2 autoload decision: added GPBMetadata\ => generated/GPBMetadata/ to composer.json so generated Rv\Data classes can initialize descriptor metadata at runtime.

  • 2026-03-01 task-2 ZIP64 repair strategy: patch archive headers in-memory only (no recompression), applying deterministic EOCD/ZIP64 size corrections before any ZipArchive access.

  • 2026-03-01 21:23:59 - ProPlaylist integration tests use temp files via tempnam() tracked in class state and cleaned in tearDown() to guarantee cleanup across all test methods.