- How do I install pdf-optimizer in a Laravel app?
- Install the package with Composer using mostafaznv/pdf-optimizer, then publish its configuration file. Laravel auto-discovery registers the service provider and facade, so you can start optimizing PDFs quickly. You must also install Ghostscript on every host that will run optimization, ideally a pinned version baked into your container image. Confirm PHP 8.2+ and a Unix-like runtime before rollout.
- Can pdf-optimizer run PDF compression asynchronously with Laravel queues?
- Yes, the package includes queue support so PDF optimization can run as a background job instead of blocking uploads or web requests. This is the recommended approach for large documents because Ghostscript can consume significant CPU and memory. Configure job timeouts and retries around your maximum document size and SLA. Validate behavior with your actual queue driver and storage disk before promoting it to live uploads.
- Which Ghostscript version should I pin for pdf-optimizer?
- Plan for Ghostscript 9 or 10 and pin a specific version in your base image rather than relying on whatever the host provides. Version drift can change compression output quality and may occasionally produce different or corrupt results. Add a startup health check that confirms the Ghostscript binary exists and reports its version. This keeps behavior consistent across local, CI, and production environments.
- Is Ghostscript's AGPL license a concern for commercial Laravel applications?
- The pdf-optimizer package itself is MIT licensed, but it shells out to Ghostscript, which is AGPL or commercially licensed by Artifex. Using AGPL Ghostscript in a network-served commercial product creates a real compliance obligation that needs legal sign-off or a commercial Ghostscript license. Treat this as the gating decision before adopting the package on a critical path. The PHP code is straightforward; the licensing posture is the main risk to resolve.
- Can I use pdf-optimizer in standalone PHP without Laravel?
- Yes, the package has a standalone core that you initialize with PdfOptimizer::init(), separate from the Laravel service provider and facade. That makes it usable in a plain PHP script, a dedicated worker, or a microservice that isolates Ghostscript from the main application. The fluent builder and option mapping are still available. Only the Laravel-specific storage and UploadedFile conveniences are absent.
- How do I optimize an UploadedFile or a PDF stored on an S3 disk?
- The Laravel integration accepts file paths, UploadedFile instances, and disk storage through methods such as fromDisk and toDisk. For S3, remember that transferring the PDF in and out adds egress cost and latency per document, so queueing is strongly advised. Test the full round trip with your configured disk and queue driver. Wrap the package in your own service interface so storage details stay out of callers.
- How does pdf-optimizer handle encrypted or password-protected PDFs?
- The package delegates actual processing to Ghostscript, so handling of encrypted, password-protected, or malformed PDFs depends on Ghostscript's behavior and the options you pass. Test these cases explicitly before broad rollout, along with linearized and scanned documents. Build failure handling around non-zero exit codes, timeouts, and unreadable input files. Do not assume every PDF that uploads successfully will optimize successfully.
- Does pdf-optimizer work on Windows or serverless runtimes?
- Windows is explicitly untested, so treat pdf-optimizer as Unix-only for production planning. Serverless and immutable runtimes complicate the system-binary dependency because Ghostscript must be present on every execution host. Container images should bake in a pinned Ghostscript version and include a health check. If you cannot ship a system binary, consider a SaaS compression service instead.
- How do I test PDF optimization without invoking Ghostscript in every test?
- Put the package behind your own PdfCompressor-style interface and mock that interface in unit tests so callers do not invoke Ghostscript. Keep a smaller set of integration tests that run real Ghostscript against fixture PDFs, including encrypted, linearized, and scanned samples. Assert on success, failure, and timeout paths rather than exact output bytes, since compression can vary by Ghostscript version. This keeps the fast test suite fast while still validating the binary dependency.
- Is pdf-optimizer actively maintained, and what are the alternatives if I need to replace Ghostscript?
- The package is a single-maintainer, donation-supported project with a small ecosystem footprint, so assess continuity risk if it sits on a critical path. Architect around your own compression interface so the vendor package is an implementation detail. Alternatives include qpdf, commercial Ghostscript licensing, or a SaaS such as Adobe PDF Services. Start with offline or batch compression, validate output quality and failure metrics, then promote it to real-time pipelines.