README

繁體中文

Laravel DWG Converter integrates LibreDWG command-line tools into Laravel applications to extract embedded DWG thumbnails and convert DWG files to DXF or structural JSON. Creating PNG, JPEG, or WebP previews also requires LibreOffice and ImageMagick.

Features

Extract embedded DWG thumbnails.
Convert DWG files to ASCII DXF.
Export DWG files as structural JSON.
Create PNG, JPEG, or WebP previews.
Accept uploaded files, local paths, or DWG bytes.
Store or stream results with Laravel Storage.

Requirements

Requirement	Supported
PHP	8.2 or later
Laravel	12 or 13
CI-tested combinations	PHP 8.2 with Laravel 12; PHP 8.3–8.5 with Laravel 12–13, including PHP 8.2 / Laravel 12 lowest and current boundaries

Laravel 13 requires PHP 8.3 or later.

External commands are feature-specific. You do not need LibreOffice or ImageMagick when you only extract thumbnails, create DXF, or export JSON.

External commands by operation

Operation	Required commands
`Dwg::thumbnail(...)->extract()`	LibreDWG `dwgbmp`
`Dwg::toDxf(...)->convert()`	LibreDWG `dwg2dxf`
`Dwg::toJson(...)->convert()`	LibreDWG `dwgread` with JSON output support
`Dwg::toImage(...)->convert()`	LibreDWG `dwg2dxf`, LibreOffice 7.4+ `soffice`, ImageMagick 7 `magick`

The package does not download or bundle these tools. For LibreDWG installation, see the official LibreDWG repository. The external tools guide covers LibreOffice and ImageMagick installation on Ubuntu/Debian, RHEL/Fedora, and Windows.

The Unit/Feature CI matrix uses fake processes and does not install external converters. End-to-end external-tool verification has been completed locally on Windows; reproducible Linux verification remains pending a redistributable DWG corpus and a pinned toolchain.

Installation

Install the package with Composer:

composer require mattmy/laravel-dwg-converter

If a required command is not on PATH, publish the configuration and provide its absolute path:

php artisan vendor:publish --tag=dwg-converter-config

Quick start

This example extracts the DWG's embedded preview and streams it to Laravel's default disk. The source is an UploadedFile from a validated request.

use Mattmy\DwgConverter\Facades\Dwg;

$thumbnail = Dwg::thumbnail($request->file('drawing'))->extract();

$path = $thumbnail->storeAs(
    path: 'drawing-thumbnails',
);

A DWG may not contain an embedded thumbnail. Use image conversion when you need a rendered preview:

use Mattmy\DwgConverter\ImageFormat;
use Mattmy\DwgConverter\ImageResolution;

$image = Dwg::toImage(storage_path('app/private/floor-plan.dwg'))
    ->format(ImageFormat::WEBP)
    ->atResolution(ImageResolution::MEDIUM)
    ->convert();

$path = $image->storeAs('drawing-previews', 'floor-plan.webp', 's3');

Inputs and outputs

Every operation accepts a valid UploadedFile, a local absolute path, or bytes explicitly wrapped with DwgBinary::from($bytes). A plain string is always treated as a path.

Each successful operation returns a one-time DwgOutput:

extension() and mimeType() inspect trusted output metadata without consuming it.
storeAs() streams the artifact to Laravel Storage and then attempts temporary cleanup.
DwgOutput cannot be cloned, serialized, or unserialized; these attempts throw LogicException.
output() returns all bytes as a string and should only be used for outputs that safely fit in PHP memory.

Errors and operational limits

Temporary cleanup failures emit a sanitized warning through Laravel's default logger without interrupting conversion or delivery. Temporary files may remain; consumed results do not retry cleanup. Logger failures also leave the operation's result or original exception unchanged.

Failures use LibreDwgUnavailable, InvalidDwg, or DwgOperationFailed. Each exception provides a stable reason() and sanitized scalar context().

The default limits are 200 MiB input, 512 MiB general output, and 64 MiB JSON output. Set a byte limit to null, zero, or a negative integer to disable it. Keep positive limits and run untrusted DWG conversions in a resource-limited worker or container.

Successful conversion means the configured tools completed the requested operation and the artifact passed the package's format checks. It is not a DWG safety certification, a full conformance check, or an AutoCAD visual-fidelity guarantee.

Documentation

Read the complete English and Traditional Chinese documentation at mattmy.github.io/laravel-dwg-converter-doc.

Changelog

See CHANGELOG.md for the version history.

License

Laravel DWG Converter is released under the MIT License. LibreDWG is GPLv3+ software installed and distributed separately. LibreOffice and ImageMagick are also installed separately under their own licenses.

mattmy / laravel-dwg-converter

Package info

Security

Statistics