Laravel Dwg Converter Laravel Package

Getting Started

1. Install the package with Composer and let Laravel auto-discover the service provider.
2. Publish the configuration file and review the temporary-directory setting, artifact byte limits, and the binary paths for LibreOffice and ImageMagick. The temp directory must already exist and be a directory (not a file) — the package reports invalid_configuration otherwise.
3. Verify the external binaries (soffice, convert/magick) are on the PATH or configured explicitly; conversion is process-driven, so most setup failures surface as process failures rather than input errors.
4. First use case: point the converter at a .dwg file and request a PDF or raster artifact. You receive a DwgOutput you can save to a disk, stream in a response, or inspect for metadata.
5. Where to look first: the published config (limits, temp dir, binary paths), then the DwgOutput API (bytes, size, cleanup, terminal consumption), then the failure states (invalid_configuration, image_invalid, process failure).

Implementation Patterns

• Basic conversion: resolve the converter from the container, pass the source path, and consume the returned DwgOutput immediately. Treat the output as short-lived — save it to a storage disk or stream it in the same request/job.
• Queue jobs: run conversions in a queued job and hand off the finished artifact to a disk before the job ends. Because DwgOutput rejects cloning and serialization, never put one on a queue payload, in a session, or in a cache — convert inside the job and persist the result.
• Size limits: the package enforces artifact byte limits at delivery and refreshes metadata before terminal delivery, so cached sizes can't bypass the cap. Rely on the configured limit rather than re-checking sizes yourself.
• Snapshots: use the snapshot/conversion flow when you need an isolated copy of the source before conversion (e.g., to avoid locking the original). Snapshot cleanup preserves primary failures, so a cleanup error won't mask the real conversion error.
• Thumbnails: embedded BMP/PNG/WMF thumbnails are validated for header and container bounds before being returned. Use them for fast previews without invoking a full image pipeline.
• Error handling: branch on the failure reason. invalid_configuration means fix config (temp dir, paths); image_invalid means the produced or embedded image is malformed/truncated; process failures mean LibreOffice/ImageMagick failed to run or read — surface those differently to users than "bad DWG".
• Cleanup and ownership: consume outputs explicitly at the end of the workflow. Once consumed, the destructor won't repeat cleanup. Cleanup failures are logged as a single sanitized warning through Laravel's default logger and never interrupt successful delivery or replace a primary failure.
• Logging: route the package's warnings into your normal Laravel log channels; no extra retry logic or logger wrappers are needed on your side.

Gotchas and Tips

• No cloning/serialization: DwgOutput throws LogicException on clone, serialize, or unserialize. Don't pass it across process boundaries — extract bytes or save to disk first.
• Temp directory must be a real directory: pointing config at an existing file yields invalid_configuration, not a generic filesystem error.
• NUL bytes are rejected: source and temp-directory paths containing NUL bytes fail through the input/config contracts — sanitize user-supplied paths before handing them over.
• Don't cache artifact sizes: metadata is refreshed before terminal delivery, so any size you read earlier may be stale; trust the limit enforcement at delivery.
• Cleanup is best-effort: failures during snapshot/conversion cleanup, and during destruction, are swallowed with one warning. If you need to guarantee disk hygiene, monitor logs rather than expecting exceptions.
• Thumbnail validation is structural only: headers and container bounds are checked, but there's no image decoder — don't assume pixel-level validity of returned thumbnails.
• Truncated WebP is reported as image_invalid before RIFF length is read; handle it alongside other invalid-image cases.
• Incomplete binary snapshot writes are rejected — if you see snapshot failures, check disk space and permissions first.
• Distinguish process failures from input failures: LibreOffice/ImageMagick read errors are process failures, so don't label them as bad DWG input in your UX.
• Extension points: the config contracts (temp dir, limits, binary paths) and the failure-state mapping are the intended knobs; avoid reaching into internals or wrapping DwgOutput with your own cloneable DTO unless you extract the bytes.