Repository navigation
Releases
v3.0.0-rc v1 Shim Removal & Project Plan Update
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\*andPACS\*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
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 typedDataset; 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),Compresswith aCompressionfactory (losslessSV1,lossless,baseline,extended), and PACS (EchoSCU,SCU,SCP,TransferSyntaxProposal) over aDCMTK\Toolkitabstraction. - 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_netkeeps the v1 parameter names and defaults;transfer_syntaxis retained as an inert property that emits a deprecation pointing atPACS\TransferSyntaxProposal.
Bug fixes
- JPEG-to-DICOM works again on current DCMTK.
Convert::fromJpeg()generates UIDs directly instead of thedcm2xmltemplate path whose warning handling blocked pixel-data embedding, resolving thejpg_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.mdrewritten 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 inexamples/.
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
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.dcmcjpeganddcmdjpegbinary 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
$templateand$temp_dirproperty declarations ondicom_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.mdwith usage examples verified against live PHP, API reference, and testing instructions. ROADMAP.mdoutlining 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.