Prado IO

[belisoful]

We have a TTextWriter but we don't have any solid core classes for reading and writing streams of digital bit/byte-based data. In the world of XML, HTML, and XHTML such formats may seem extraneous. However there are many data that is written and read in bits rather than text encoded.

Reading and writing IPTC, EXIF, JPEG APP tags, and other digital formats does need such classes. No doubt there are other applications for such utility... including streaming data over TCP/UDP, and other digital formed data.

I have these done already and they do a few extra things like read half floats and mini floats that typical php and PHP Readers/Writers do not do. It has push/pop for offset saving and restoring and sectioning for isolating a portion of a file as if it were its own file. The sectioning is useful for designating a portion of the file (start offset and length) as IPTC encoded data and it will start the "file offset" at the start of the IPTC block, and act like its the end of the file at the end of its length.

Necessity is often one of the greatest sources of inspiration.

[belisoful]

more utility is needed than just TDataReader and TDataWriter.

TDataStream - encapsulates a PHP Stream, standardizes stream behavior (mainly writing).
TDataReader- reads binary data in a specified endian
TDataWriter - writes binary data in a specific endian
TFileReader - initialization but with a file path. a slightly more specific TDataReader
TFileWriter - initialization but with a file path. a slightly more specific TDataWriter

TBitReader - for reading a specific number of bits at a time.
TBitWriter - for writing a specific number of bits at a time.

TDataAllocation - structured memory allocation functionality

TLZWCompressor - A common, effective, and fast compression algorithm (with expired patent)
TPackBitsCompressor - used by TIFF.

[belisoful]

TDataStream may be able to handle files is being designed for files, but I think sockets will fit and can be handled as well. Sending binary data by socket through TDataWriter would be utilitarian.

[belisoful]

This is a more interesting issue that I initially figured. Reading and writing binary numbers in a stream could mean the steam is a resource, file, socket, I/O pipe, or process pipes each with their own slighting different open and close function. Each are using fread and fwrite to receive and send data.

This adds a great abstraction layer to interprocess communication, which we may need if cron is going to spin off each cron job as its own process at some point.

I feel like I have to do at least 4 iterations of anything I do to make the work up to date with current PRADO standards. lol. eg. The very short function and miner tweak to support composer plugins was the reduction of 1.5 years of work with countless classes for making PRADO plugins before composer was a thing. in revisiting it that was how it was reduced to basically one function to support composer plugins.

[belisoful]

BTW, this is turning into a general IO package. It's looking awesome. It adds support for binary IO on StdIn, StdOut, Input, Output, StdErr, Temp Files (3 forms, including a retainable temp), Sockets, Temp-Memory, , Pipes, Processes, Files, and downloaded URLs via fopen.

I am hoping this unlocks more potential and utility of PRADO. Other packages like ASP and JAVA have IO and network classes.

this is core functionality of an asset and publishing those assets. So, before we address publishing an asset, we need to be able to read it, write it, and process it properly. I also like the standardization of reading and writing so many sources and sinks.

and, as stated, bit reader/writer, and LZW and packbits compression.

[belisoful]

Found another bug in PHPStan: phpstan/phpstan#9386

Documented here: https://phpstan.org/r/84a3c6f1-9649-4f59-8a1b-ae9d8af656eb

A trait is being used by two classes, but only one class has specific properties. The class is checked for and properties accessed. The problem is that the second class using the trait, PHPStan thinks is also executing on the class properties. The class with the properties is being checked and the class without the properties is excluded. PHPStan thinks the excluded class is executing on those properties but without the properties.

There are 4 Reader classes and two have the "Startoffset" and "fixedlength"

Technically, the issue being reported goes against standard OOP for traits. I'm refactoring it so it's not an issue, but it's still something phpstan should look at.

[belisoful]

Prado IO subsystem — PR index

The IO subsystem is in place (streams + resources)

This wraps up the stream and resource half of #904. Prado\IO now provides a PSR-7 stream core over PHP
resources, the decorator/source set, sockets with an event loop, processes and forks, stream filters and
wrappers, bit-level IO, URIs, and compression codecs — each registered in classes.php, error-coded in
messages.txt, and unit tested.

Still open: the HTTP message layer — PSR-7 TMessage/TRequest/TResponse, the PSR-17 factories, and a
PSR-18 client over a pluggable transport. The existing IO\HttpClient family (below) is the pre-PSR downloader
it will build on.

PRs in merge order; each lists its commit and the framework/IO files it adds.

#1145 · 10e908ded — HTTP client + REST consumer

Class	What it is / what it is for
THttpClient	Abstract HTTP transport; create() returns the best available. Use: one-shot request/response fetches.
TCurlHttpClient	cURL transport.
TFopenHttpClient	Stream-wrapper transport, for hosts without ext-curl.
TCachedHttpClient	Wraps any client with a TTL response cache.
THttpClientResponse	Status/headers/body value object.
THttpClientException	Transport failure.
TStreamDownloader	Streams a response body to a stream or file instead of memory. Use: large downloads.
TRestClient	REST consumer over THttpClient: encodes/decodes JSON/XML, carries auth. Symmetric to TRestService.

#1161 · 856d39f7e — TRestClient adopts THttpHeaderName/TMediaType (modifies existing IO files)

Touches TRestClient.

#1172 · d9f7025fa — URI

Class	What it is / what it is for
TResourceUri	Immutable PSR-7 UriInterface for any IO resource (file://, php://, tcp://). Base of Web\TUri.
TUriDefaultPort	Scheme → default port; drives default-port suppression in the authority.
TUriScheme	Common URI scheme name constants.

#1182 · 8c4f0c78c — IO core — resources, streams, presets, PSR-17 factory

Class	What it is / what it is for
IResource	Contract for an object wrapping a PHP resource handle.
TResource	Resource base: owns/attaches/detaches a handle, locking, metadata, events.
TResourceType	get_resource_type() name constants.
TStream	PSR-7 StreamInterface over a PHP stream resource. The layer’s workhorse; for() coerces string/resource/stream.
TStreamMetadataKey	stream_get_meta_data() key constants.
TStreamFactory	PSR-17 StreamFactoryInterface.
TStreamResourceWrapper	Exposes a PSR-7 stream as a native resource. Use: hand a stream to fgetcsv() and friends.
TFileStream	Preset: a file.
TMemoryStream	Preset: php://memory.
TTempStream	Preset: php://temp (spills to disk past a threshold).
TInputStream	Preset: php://input, the raw request body.
TStdInStream	Preset: php://stdin.
TStdOutStream	Preset: php://stdout.
TOutputStream	Preset: php://output, the response body.
TStdErrStream	Preset: php://stderr.
TFlushableStreamTrait	Adds flush() to the output presets.
TByteOrder	Endianness enum + native(); used by the binary and bit classes.

#1191 · 779ba5e8d — Sockets

Class	What it is / what it is for
TSocketStream	A socket as a PSR-7 stream: connect, TLS, timeouts, pair(). Use: clients and accepted peers.
TSocketServer	Listening socket with an accept loop.
TSocketAddress	Immutable endpoint value object (transport, host, port, unix path).

#1192 · 1fd7fdf66 — Processes

Class	What it is / what it is for
TProcess	proc_open process as a resource, with pipe streams and status. Use: run and talk to a child command.
TPipeStream	popen pipe as a stream.
TProcessStatus	Immutable status snapshot (pid, running, exit code).

#1188 · d7da4ccf3 — TStream to pure PSR-7; binary + PHP-name access

Class	What it is / what it is for
TStreamDecorator	Abstract decorator forwarding all 15 PSR-7 methods to an inner stream. Base of every stream decorator.
TBinaryStream	Typed binary fields (readInt32/writeDouble…) with per-call byte order. Use: parsing/emitting binary formats.
TBinaryStreamBehavior	The same typed methods added to any TStream as a behavior.
TPhpStreamBehavior	PHP-named aliases (fread/fwrite/fseek) on a stream.

#1198 · f46a84d92 — TUriScheme adds tcp/udp/unix/udg/ssl/tls (modifies existing IO files)

Touches TUriScheme.

#1200 · 2f0c7ab66 — Bit streams

Class	What it is / what it is for
TBitReader	Reads n-bit fields across byte boundaries (MSB/LSB, signed, float). Use: packed binary formats.
TBitWriter	Writes n-bit fields; flush() zero-pads the partial byte.
TBaseBitStream	Shared bit-accumulator base.
TBitFieldFormat	Field format enum (unsigned/signed/float).

#1212 · 6f18e6abd — TRestClient update (modifies existing IO files)

Touches TRestClient.

#1217 · d207556e4 — Socket event loop

Class	What it is / what it is for
TSocketReactor	select() loop over registered streams plus timers. Use: drives servers and any non-blocking IO.

#1223 · 37cc256e5 — Stream filters, wrappers, helper

Class	What it is / what it is for
TStreamFilter	Abstract php_user_filter base with register/append/remove helpers.
TStreamCodecFilter	Incremental codec filter base (process()/finish()). Use: streaming transforms in constant memory.
TStreamFilterName	Built-in PHP filter name constants.
TStreamFilterHandle	Handle for an attached filter, so it can be removed.
TStreamWrapper	Abstract base for a custom protocol:// stream wrapper.
TStreamHelper	Whole-stream utilities PSR-7 lacks: copyToString, copyToStream, hash, readLine.

#1226 · edd4edb89 — zlib decorators + pooling

Class	What it is / what it is for
TInflateStream	Decompresses on read (gzip/zlib/raw).
TDeflateStream	Compresses on write (gzip/zlib/raw).
IStreamDecoratorPooling	recycle()/release() contract so a decorator is reused instead of reallocated.

#1228 · 42322fb25 — Socket server as a module + CLI

Class	What it is / what it is for
TSocketServerModule	Runs a long-lived TSocketServer as an application daemon.
TSocketServerAction	prado-cli socket/serve shell action.

#1229 · 346cf7aab — REST/HTTP client hardening (modifies existing IO files)

Touches THttpClient, TRestClient.

#1231 · 588a4d8ea — FIFO buffer

Class	What it is / what it is for
TBufferStream	In-memory FIFO: writes append, reads drain, non-seekable. Use: pipe-like hand-off between producers and consumers.

#1232 · acd925ad4 — Process forking

Class	What it is / what it is for
TProcessFork	pcntl_fork child handle: run/exit, wait()/poll(), signals, optional socket channel. Use: parallel work in-process.
TResultProcessFork	Child returns a serializable result to the parent.
TLiveProcessFork	Child streams live key/value updates to the parent (ArrayAccess). Use: progress and partial results.

#1233 · 642dc17fc — TBinaryStream gains the write side (modifies existing IO files)

Touches TBinaryStream.

#1238 · 07054e174 — Reserved-space decorators

Class	What it is / what it is for
TReservedSpaceStream	Keeps 1:1 addressing while protecting reserved ranges (Clip/Fail/Skip). Use: format private spaces (EXIF maker notes).
TFreeSpaceStream	Presents only the non-reserved bytes, contiguously.
TBaseSpaceStream	Shared range algebra for both.
TReservedSpaceMode	On-access mode enum.

#1239 · 29bf48f18 — Compression codecs + content negotiation

Class	What it is / what it is for
ICompressor	Whole-string codec contract (compress/decompress).
TBuiltinCompressor	Base wrapping a native PHP codec; ext-gated, uniform failure.
TGzipCompressor	gzip (RFC 1952).
TZlibCompressor	zlib (RFC 1950) — the HTTP deflate coding.
TDeflateCompressor	raw DEFLATE (RFC 1951).
TBzip2Compressor	bzip2 (ext-bz2).
TZstdCompressor	Zstandard (ext-zstd).
TBrotliCompressor	Brotli (ext-brotli).
TCompression	Façade keyed by HTTP content-coding + Accept-Encoding negotiation. Use: pick and apply an encoding per client.
TCliCompressorTrait	Shell-free proc_open command backend for a format PHP has no extension for.
TCliCompressor	Base for a codec that is only ever a command.
TXzCompressor	xz stub — no PHP extension exists; the working codec is belisoful/prado-compression.

#1240 · 590fb1e2e — PSR-7 utility stream sources and decorators

Class	What it is / what it is for
TAppendStream	Reads several streams in sequence as one. Use: header + body without copying.
TMultipartStream	Builds a multipart/form-data body from parts. Use: file uploads.
TPumpStream	Read-only stream produced on demand by a callable. Use: adapt a generator.
TFnStream	Stream from a map of per-method closures. Use: adapt a non-stream, or override a few methods.
TFnStreamMethod	The PSR-7 method names that key that map.
TLazyOpenStream	Defers opening until first use.
TCachingStream	Makes a one-pass source seekable by caching reads. Use: re-read a response body.
TLimitStream	A byte window (offset + length) of an inner stream.
TDroppingStream	Caps size, dropping writes past the limit. Use: bound an untrusted producer.
TNoSeekStream	Hides seekability; forward-only view.
TStreamNoSeekBehavior	The same denial applied to a TStream as a behavior.

#1245 · fd614e691 — TStreamHelper completion; TMediaType extension lookup (modifies existing IO files)

Touches TStreamHelper.

---

Also in framework/IO (pre-dating this work)

TTarFileExtractor (atomic tar extraction, zip-slip hardened),
TTextWriter / ITextWriter,
TOutputWriter, TStdOutWriter,
TStreamNotificationCallback and
TStreamNotificationParameter.

[belisoful]

The THttpClient needs to be reviewed, updated and reworked for PSR-17. Potentially.

Given some WIDE margin for assumptions, this Issue is currently about 70%-90% done.

prado-rpc will need to be updated a bit for this remaining work, but that's easy.