Tc Lib File Laravel Package

Product Decisions This Supports

• Build vs. buy for binary parsing. Any roadmap item that touches PDF object streams, font subsetting, image header parsing (PNG/JPEG/TIFF), or embedded file extraction needs big-endian byte readers. This package supplies getByte/getUShort/getULong/getFixed with bounds-checked reads and \RangeException on overflow — a day of work you don't re-spend, and one you'd otherwise get wrong at the edge cases.
• Whether to accept user-supplied URLs in document generation. The single highest-leverage decision this enables is SSRF posture. If a feature lets a customer paste a URL for an image, logo, or remote HTML asset, File provides strict-deny allowedHosts/allowedPaths allowlists, per-hop redirect validation against the allowlist, CURLOPT_MAXREDIRS => 0 by default, and a maxRemoteSize cap measured on inflated bytes. That's a security-reviewed control you can point to in a threat model instead of writing yourself.
• Multi-tenant file scoping. allowedPaths with canonical/realpath() normalization, symlink-root handling (current -> releases/42), NUL-byte rejection, and per-volume case-sensitivity probing answers "can tenants escape their directory?" — a question that otherwise surfaces as a pentest finding.
• Caching strategy for derived artifacts. Cache gives prefixed, CSPRNG-suffixed temp files with scoped delete() semantics and deleteOlderThan(). Supports decisions like "cache rendered thumbnails for 24h" or "evict per-tenant" without inventing a naming convention that later deletes the wrong tenant's files.
• Platform/roadmap scope. Explicit Windows known limitations (8.3 short names, ADS, trailing dots) and macOS NFC folding (only with ext-intl) directly inform whether Windows Server or macOS-hosted deployments are in scope, or need a documented support boundary.
• Dependency policy. LGPL-3.0 (Packagist metadata says NOASSERTION — reconcile before legal sign-off). This constrains distribution models: fine for SaaS and internal services, needs review for redistributed binaries or closed-source on-prem appliances.

When to Consider This Package

Consider it when:

• You are already in, or adjacent to, the TCPDF / tc-lib-pdf ecosystem. This is a first-party component of a stack with 100M+ installs; adopting it is maintenance consolidation, not a new vendor.
• Your feature is document generation, report rendering, or image/font import where byte-level reads are unavoidable.
• You need a hardened remote-fetch path more than a featureful one. The allowlist-first design, redirect re-validation, control-character rejection on URLs, and in-memory size bounding are the product.
• You want strict-deny defaults — it fails closed and forces you to declare trust, which is the right shape for a security review.
• PHP 8.2+, ext-curl, ext-pcre are already in your base image (they almost certainly are).

Look elsewhere when:

• You need general filesystem abstraction (S3, GCS, SFTP, Flysystem-style adapters). This is local-plus-cURL, not a storage layer.
• You need streaming large payloads. Byte is an immutable reader over an in-memory string, and remote responses are buffered under a 50 MB default cap. Gigabyte media pipelines are the wrong fit.
• You need an HTTP client — retries, middleware, PSR-18, auth flows. Use Guzzle/Symfony HttpClient and pass validated URLs in.
• You need high-level image manipulation (resize, crop, format conversion) — Intervention Image, not this.
• Your use case is a fopen + unpack() call in one place. The dependency isn't worth it for a single trivial read.
• Licensing is a blocker. LGPL-3.0 in a redistributed closed-source product needs legal review; don't let it slide in as a transitive dep unnoticed.
• You need community support depth. 8 stars, 0 listed dependents, README-level maturity. Bus factor is the author plus the TCPDF ecosystem. That's acceptable for a leaf utility in a document pipeline; it is not acceptable as a load-bearing platform dependency for a security-critical service without a vendoring/fork plan.

How to Pitch It (Stakeholders)

For executives (30 seconds):

This is a small, mature utility from the team behind TCPDF — the PDF library with over 100 million installs. We need byte-level file reading and safe remote fetching for [feature]. Building it ourselves means re-implementing SSRF protection, path allowlisting, redirect validation, and size limits — exactly the class of code that produces security incidents when hand-rolled. Adopting it removes that risk and roughly [X] days of build plus ongoing security upkeep, at the cost of one dependency. The one item for legal is its LGPL-3.0 license, which is fine for our hosted model but needs a check if we ever ship on-prem binaries.

For engineering:

tecnickcom/tc-lib-file — PHP 8.2+, ext-curl + ext-pcre, ext-intl optional (enables NFC path folding on macOS). Five classes: File (local/remote reads behind host and path allowlists), Byte (bounds-checked big-endian reads, throws \RangeException), Cache (prefixed temp files, scoped deletes), Dir (writable parent lookup, open_basedir-aware), Exception.

Defaults are strict-deny — empty allowedHosts and allowedPaths mean everything is rejected until you configure them. Wire the allowlists from config, never from request input, and never use '*'. Redirects are off by default (CURLOPT_MAXREDIRS => 0); if you enable them, every Location target is re-checked against the allowlist. Remote responses are buffered and capped at maxRemoteSize (50 MB default), counted post-inflation. The library reserves WRITEFUNCTION, PROGRESSFUNCTION, XFERINFOFUNCTION, NOPROGRESS, and (with redirects) HEADERFUNCTION — your setCurlOpts() values for those are replaced.

Two API traps worth knowing up front: isValidURL()/isValidFile() take arguments by reference and rewrite them — use isAllowedUrl()/isAllowedFile() for literals or expressions. And Cache::delete(null, $key) throws by design; a key requires its type.

Scope boundaries to respect: 32-bit readers assume a 64-bit PHP build; Windows does not expand 8.3 short names, ADS, or trailing dots before allowlist matching; macOS Unicode folding is a no-op without ext-intl. Document these if those platforms are in scope.

Operational risk: 8 GitHub stars and no listed Packagist dependents. It's maintained as part of TCPDF, not as a standalone project. If it becomes load-bearing, plan to vendor or fork rather than depend on upstream responsiveness.