Download the PHP package bycerfrance/json-fragments without Composer

JsonFragments

PHP library for externalizing JSON branches into immutable storage fragments, inspecting references, and resolving their content lazily.

• Package: bycerfrance/json-fragments
• Namespace: ByCerfrance\JsonFragments
• Requirements: PHP 8.3 or later.

Features

• Non-mutating JSON transformations using JSON Pointer paths.
• Wildcard branch selection with multiple or terminal * segments.
• Reference value objects preserving $ref and sibling properties.
• Explicit resolvers deciding which references they support.
• Lazy fragments and reference inspection without storage access.
• Progressive JSON output as a standard PHP stream resource, ready to wrap in a PSR-7 body.
• One storage per storage resolver, using jsonfragment:// by default.
• An optional Flysystem 3 adapter with immutable fragments, each assigned its own random identifier within the supplied filesystem.

Installation

Install the library with Composer:

For the Flysystem integration:

Install the Flysystem adapter for your backend separately (for example, league/flysystem-aws-s3-v3 for S3). The core library does not require Flysystem.

Construction and storage context

Configure an optional physical prefix directly on FlysystemFragmentStorage. The supplied filesystem can be a Flysystem Filesystem or MountManager:

Each new inline fragment gets a random 128-bit identifier. Supported existing references are validated and reused without I/O or existence checks. The caller must restore the same filesystem and storagePrefix when reading a persisted document. The application supplies this context; it is never inferred from the JSON reference.

Use an existing MountManager

A reference jsonfragment://abc.json maps to results://<result_uuid>/abc.json, which the mount manager routes to <result_uuid>/abc.json on the results mount. The physical prefix never appears in a generated JSON reference. The application keeps the lightweight root document in its database and stores fragments in this context.

Relative prefixes such as documents/<uuid> and mounted prefixes accept an optional trailing slash. A mount-only prefix such as results:// is also supported and retains its :// separator. An empty prefix preserves the original paths and behavior; existing positional and named constructor calls remain compatible.

Relative fragment keys are validated before prefixing. Absolute paths, parent/dot segments and ambiguous keys are rejected before filesystem access. supports() only inspects the public reference format, independently of the physical prefix. Neither constructing the storage nor calling stream() opens a fragment.

No path-prefixing decorator is required for this feature. Flysystem's optional PathPrefixedAdapter remains usable when scoping the filesystem itself is preferred.

Copying between storage contexts must be explicit: resolve using the source fragmenter, then externalize the resulting values using the destination fragmenter. Passing a source reference directly to a destination store does not copy its content.

Repeatedly externalizing inline data creates new fragments, even when the content is identical. Reuse the returned references to avoid rewriting existing fragments. There is no content-based deduplication.

Document persistence and storage cleanup belong to the integrating application. The library has no framework or ORM dependency.

Transformations

All methods accept decoded JSON values, including arrays, stdClass, scalars, JsonSerializable values, backed enums (BackedEnum), references and lazy fragments. A string is a JSON string value, not an encoded document. Decode textual JSON explicitly:

Using associative: false preserves the difference between JSON objects and lists, including {} and []. Stored JSON objects are resolved as stdClass; PHP associative arrays are therefore not guaranteed to round-trip as PHP arrays.

The supplied structure is never modified. Arbitrary JsonSerializable values are normalized by invoking their serialization method; their own side effects remain the caller's responsibility. Existing fragments retain their lazy caches, which may be populated during resolution. Object values returned from those caches are defensive copies.

Backed enums are normalized to their string or integer backing value, including when nested in arrays or objects. JsonSerializable takes precedence when an enum implements it. Backing values undergo the same JSON validation as other scalars, including UTF-8 validation for strings. Non-backed enums are rejected unless they implement JsonSerializable.

Select branches using JSON Pointer

• '' selects the entire document; '/' selects an empty property name.
• Escape / as ~1 and ~ as ~0 in property names.
• Array indices must be non-negative integers without leading zeroes.
• Missing paths are ignored; existing null values are externalized.
• Duplicate or overlapping paths are rejected before writes.
• externalize() treats * as a literal property name; use externalizeMatching() for wildcards.
• URI-fragment pointers such as #/samples are not supported.
• Pointers traverse inline arrays and objects, not the contents of lazy fragments or reference objects. Resolve those first to select a deeper branch.

Transformations enforce a maximum nesting depth of 128 levels and reject cyclic input structures and unsupported PHP values such as resources.

Select branches using wildcards

Each whole-segment * matches every immediate child of a list or object. Multiple wildcards and terminal wildcards are supported. For example, /items/*/detail/*/test can select /items/0/detail/0/test and /items/0/detail/1/test. Property names retain JSON Pointer escaping (~0 and ~1). Only a complete * segment is special: item* and ** are literal property names, not partial or recursive wildcards. Use externalize() to target a literal * key.

• Missing branches, empty collections and scalars encountered before the end of a pattern produce no matches. Existing null values at the end are externalized.
• Exact array indices must be non-negative integers without leading zeroes; invalid indices encountered on non-empty lists are rejected.
• '' selects the root, and '/' selects an empty property name.
• All patterns are expanded against one normalized copy of the input before writes. Duplicate concrete selections and parent/descendant overlaps are rejected. Combining /items/* and /items/*/detail/*/test therefore fails if both select overlapping branches.
• Selection never loads stored content or traverses JsonFragment or JsonReference objects. Plain inline arrays and objects are traversed normally.
• Each selected branch uses the same storage behavior as externalize(): supported existing references may be reused, and nested supported references may be resolved when storing a selected branch.

Serialize references or complete content

JsonReference::jsonSerialize() emits the $ref envelope. JsonFragment::jsonSerialize() emits the resolved value. Always use dehydrate() when persisting a structure that may contain lazy fragments.

For eager resolution, use $fragmenter->resolve($decoded) instead of hydration. References inside a loaded file are returned as data, not recursively resolved. The library does not implement recursive JSON Schema or JSON Reference resolution.

Stream complete JSON with bounded fragment reads

Use stream() when the output is being transmitted or exported rather than manipulated as PHP values. Unlike resolve() followed by json_encode(), it does not materialize the complete resolved document or its encoded output.

Opening the output performs no fragment reads or inline serialization. Reading it starts a lazy producer that emits JSON punctuation, inline values and the content of supported references. PHP may read ahead by a small stream buffer, so a small fread() can cause a bounded amount of additional production.

The output is a read-only, non-seekable resource with unknown size. Rewinding and random access are not supported. Multiple output resources can be consumed independently. Keep the supplied input unchanged while its stream is open: streaming deliberately does not take a deep snapshot of the input document.

Native streaming and fallback

Resolver\StreamingJsonReferenceResolverInterface extends the standard resolver:

FlysystemFragmentStorage implements both JsonFragmentStoreInterface and this streaming interface. Its readStream() delegates directly to Flysystem's readStream(). Its resolve() reads that stream completely, decodes the JSON and closes the resource.

For output produced by JsonFragmenter::stream():

• A streaming resolver supplies a blocking, readable resource containing one complete JSON value. Its bytes are forwarded without decoding or re-encoding the fragment.
• A classic resolver remains supported: the producer calls resolve() and encodes its returned PHP value progressively. This fallback materializes that fragment in memory.
• A JsonFragment uses its own bound resolver and original storage context. Native streaming reads the storage directly, without populating or using the fragment's decoded cache.
• Unsupported references retain their envelopes and sibling properties.
• References inside resolved content are not followed recursively.

The native path trusts the resolver to supply valid JSON. It does not validate a file's full contents before sending them; malformed stored JSON will produce malformed output. Inline values and fallback values are encoded with JSON_THROW_ON_ERROR.

Only the current fragment stream is opened. It is consumed from its current position, without rewinding, and closed at EOF, on an error or when the output resource is closed. The resolver transfers ownership of each returned resource to the consumer.

Memory overhead for native fragments consists primarily of reading buffers and traversal state. The input's inline values are already in memory; large inline strings still need an encoded string allocation. Custom serializers, fallback resolvers and underlying filesystem adapters can also allocate memory. Calling stream_get_contents() on the output or collecting all chunks into a string materializes the complete result again.

Use as a PSR-7 response body

Ownership passes to the PSR-7 body after successful construction; closing it closes the output and any currently open fragment. The HTTP emitter must read the body in chunks rather than cast it to a string. Do not set a guessed Content-Length. PSR-7 is not a runtime dependency of this library.

Encoding, opening and read errors propagate while consuming the stream. Bytes already sent cannot be withdrawn, so an error after transmission starts may leave an incomplete JSON response. The library registers an internal PHP stream wrapper under the reserved bycerfrance-json-fragments scheme; applications should not replace or unregister it.

References and resolvers

A reference is a value object, not a request to access a resource. Its scheme is derived from its identifier. The resolver decides whether it supports the complete reference envelope.

The Flysystem implementation recognizes the configured reference prefix (jsonfragment:// by default) and accepts only envelopes without sibling properties. Natural web references, local JSON Pointers and annotated references are preserved. HTTP resources are never downloaded automatically.

This prefix identifies the reference format; it does not configure the filesystem directory. Use the same format when reading stored documents.

Inspect all references

Inspection reports every string-valued $ref, including unsupported references and those inside sibling properties. Each occurrence is retained, even when several paths refer to the same resource. Lazy fragments are inspected without being loaded. Files referenced by the document are not traversed.

Validate references before use

validateReferences() traverses the root document, including reference sibling properties, but never the content of stored fragments. It:

• ignores unsupported references, such as HTTP and #/... references;
• checks identical references bound to the same resolver only once;
• checks a lazy JsonFragment with its own bound resolver and storage context, without loading it;
• throws a LogicException, before any storage access, if a supported reference's resolver cannot check existence;
• throws a RuntimeException naming the reference and its JSON Pointer if a fragment is missing;
• propagates storage errors unchanged.

Existence checking is a capability declared by Resolver\ExistenceCheckingJsonReferenceResolverInterface:

It must not open, read or decode the target. false means the target is confirmed missing; when existence cannot be determined, the implementation throws rather than returning true. FlysystemFragmentStorage implements it with Flysystem's fileExists(), using the same physical path and storagePrefix as reads.

A successful validation reflects the storage state at the time of the check; a fragment deleted afterwards still fails on resolution or streaming.

Implement another storage or resolver

Resolver\JsonReferenceResolverInterface defines:

Storage\JsonFragmentStoreInterface extends it with:

JsonFragmenter accepts a JsonFragmentStoreInterface directly. Reference formats, storage keys and scope configuration belong to the implementation, not the fragmenter. supports() must not perform I/O. store() must complete a new write before returning its reference; it may reuse an existing supported reference without reading it. JsonFragment can also use a read-only resolver directly.

Failure and lifecycle contract

• Invalid JSON values and encodings fail explicitly; they are not converted to null.
• Unsupported references remain data. Supported but missing references fail on resolution.
• A failed lazy resolution is not cached and can be retried.
• A failed externalization may leave files from earlier successful writes. There is no rollback across storage operations.
• Reprocessing inline content generates new fragment IDs; abandoned writes require application-level cleanup.
• No operation deletes stored fragments. Delete a filesystem prefix only after the application has established that its data is no longer in use.
• The filesystem context is part of the document's persistence contract. References alone do not identify a bucket or physical prefix.

Development

GitHub Actions is configured for PHP 8.3, 8.4 and 8.5, with lowest and current stable dependencies.

See CONTRIBUTING.md for development conventions.

License

MIT.