Skip to content

Releases

v3.0.0-rc v1 Shim Removal & Project Plan Update

Choose a tag to compare

@rbraunm rbraunm released this 29 Jun 23:02

First release candidate for 3.0.0. This release removes the deprecated v1 compatibility shim: the global procedural surface (dicom_tag, dicom_convert, dicom_net, and the is_dcm / Execute helpers) that the 2.x line carried so existing v1 code could keep running unchanged. The namespaced object API (DICOM\*, PACS\*) introduced in 2.0 is now the only surface.

Nothing else changes for the namespaced API. The library still wraps the DCMTK command-line toolkit, still targets PHP 8.5, and is still Apache-2.0. If you are already on the 2.x namespaced API, there is nothing to do.

Breaking change

The v1 global API is gone. Code still calling it will fail to autoload. The removed symbols and their namespaced replacements:

Removed (v1) Use instead
dicom_tag DICOM\File (open plus typed accessors) or DICOM\Dataset (raw group/element)
dicom_convert DICOM\Convert (JPEG, thumbnail, JPEG/PDF import, multiframe video) and DICOM\Compress
dicom_net PACS\EchoSCU, PACS\SCU, PACS\SCP (with Peer, Association, TransferSyntaxProposal)
is_dcm() DICOM\File::isDICOM()
Execute() removed; it was an internal toolkit-invocation helper with no public replacement

The examples/ directory shows the current API for every operation.

Installing the pre-release

Composer treats this as a pre-release, so stable installs will not pick it up. To try it:

composer require "rbraunm/class_dicom:^3.0@RC"

Existing ^2.0 consumers are unaffected and will not be upgraded automatically.

Unchanged

  • PHP 8.5 and a DCMTK install remain the only runtime requirements.
  • The DICOM\* and PACS\* API and its behavior are identical to 2.0.0.
  • License stays Apache-2.0; provenance is recorded in NOTICE.

Status

This is a release candidate. The namespaced API is unchanged from 2.0.0, so the surface area of this release is just the shim removal. Barring a blocker, it ships as the final 3.0.0 after a soak period. Please report anything that breaks against the RC.

Full history is in the CHANGELOG; the complete diff from the last stable is v2.0.0...v3.0.0-RC1.

PHP 8.5 Rewrite

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.

v1.1.0

Choose a tag to compare

@rbraunm rbraunm released this 27 May 19:44
bd42d28

PHP 8.x compatibility, bug fixes, integration tests, and documentation.

Bug fixes

  • compress() was broken. An undefined variable meant the method silently did nothing on every call. Fixed.
  • dcmcjpeg and dcmdjpeg binary paths were swapped. Compress was calling the decompressor and vice versa. Fixed in both the Windows and Linux path blocks.
  • PHP 8.2 dynamic property deprecations. Added missing $template and $temp_dir property declarations on dicom_convert.

Compatibility

  • Now requires PHP 8.0+ (declared in composer.json). Tested through PHP 8.4.
  • No breaking API changes from v1.0.0.

Testing

  • New integration test suite (tests/) using pydicom and pynetdicom for independent cross-validation. Every conversion, tag operation, and network call is verified by a completely separate DICOM implementation — not just read back by the same tools that wrote it.

Documentation

  • Full README.md with usage examples verified against live PHP, API reference, and testing instructions.
  • ROADMAP.md outlining v2.0.0 (modern PHP refactor) and feature expansion plans.

Known issues

  • jpg_to_dcm() does not work on current DCMTK versions due to warning-handling logic that prevents pixel data embedding. Tracked for v2.0.0.

v1.0.0

Choose a tag to compare

@rbraunm rbraunm released this 02 Sep 17:47
ae9dc75

This release allows for version pinning for this class to allow backward compatibility as it is brought forward to more modern standards and current PHP versions. This commit represents the long-standing stable release for the last decade.