Skip to content

PHP 8.5 Rewrite

Latest

Choose a tag to compare

@rbraunm rbraunm released this 29 Jun 11:33
317e1a9

class_dicom 2.0.0

Complete clean-room rewrite for modern PHP. New namespaced, fully-typed API with exception-based error handling, plus a drop-in compatibility layer so existing v1 code keeps working.

New API

  • Ground-up reimplementation under PSR-4 (DICOM\, PACS\, DCMTK\). File::open() returns a typed Dataset; tag reads and writes go through VR-validated accessors (getText, getDate, getTime, getPersonName, getUID, getInteger, getDecimal, and matching setters) backed by real value objects (Date, Time, PersonName, UID).
  • Conversion and networking are first-class: Convert (toJPEG, toThumbnail, toVideo, fromJpeg, fromPdf), Compress with a Compression factory (losslessSV1, lossless, baseline, extended), and PACS (EchoSCU, SCU, SCP, TransferSyntaxProposal) over a DCMTK\Toolkit abstraction.
  • Exception-based error model. Operations throw (IOException, NetworkException, InvalidArgumentException) instead of returning sentinels, so failures surface at the call site instead of silently.

Compatibility

  • Breaking: now requires PHP 8.5+ (was 8.0+). This is the reason for the major bump.
  • Drop-in v1 compatibility layer: the legacy global surface (dicom_tag, dicom_convert, dicom_net, is_dcm, Execute) is reimplemented on top of v2, so v1.1.0 code runs unchanged on PHP 8.5. dicom_net keeps the v1 parameter names and defaults; transfer_syntax is retained as an inert property that emits a deprecation pointing at PACS\TransferSyntaxProposal.

Bug fixes

  • JPEG-to-DICOM works again on current DCMTK. Convert::fromJpeg() generates UIDs directly instead of the dcm2xml template path whose warning handling blocked pixel-data embedding, resolving the jpg_to_dcm() issue tracked from v1.1.0.

Testing

  • Integration suite (tests/) cross-validated with pydicom and pynetdicom: every conversion, tag operation, compression, and network call is verified by a completely separate DICOM implementation, not just read back by the tools that wrote it. CI runs on PHP 8.5 + DCMTK.

Documentation

  • README.md rewritten v2-first with usage examples verified against live PHP and a full API reference.
  • docs/migration-v1-to-v2.md: per-class v1 to v2 mapping, with before/after recipes in examples/.

Known issues

  • Callers on PHP 8.0 through 8.4 cannot upgrade and should stay on the 1.1.x line; the compatibility shims require the same PHP 8.5 + DCMTK as the core.