Download the PHP package koriym/semantic-logger without Composer
On this page you can find all versions of the php package koriym/semantic-logger. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download koriym/semantic-logger
More information about koriym/semantic-logger
Files in koriym/semantic-logger
Package semantic-logger
Short Description Type-safe structured logging with schema validation and meaningful context
License MIT
Informations about the package semantic-logger
Koriym.SemanticLogger
Type-safe semantic logging for hierarchical application workflows with tree-shaped JSON output.
Koriym.SemanticLogger records three kinds of facts as structured JSON:
open: what is startingevent: what happened while it was runningclose: how it ended
Each entry carries a schema URL and typed context data, so logs stay machine-readable and can be validated, rendered, and inspected without depending on free-form log messages.
The public log contract is structural: everything that happened inside an open is in its children, in the order it was recorded, and its matching close is nested on it. Once serialized to JSON, normal operation results are read from paths such as entries[0].close — not from a separate top-level close list.
Installation
Core Model
Semantic logs are built from matching open / close pairs plus optional events:
This gives you:
- explicit operation boundaries
- nested workflow structure
- intent vs outcome
- schema-backed context instead of ad-hoc strings
- parent-child relationships embedded in the tree — no need to correlate open/close pairs by ID
Optional RFC 8288 links can be attached at flush time when you want to point to related resources such as source code, schemas, or external specs.
Quick Start
1. Define Context Classes
The recorded context data is the JSON representation of the context: public properties by default, or the jsonSerialize() result when the context implements JsonSerializable and that result is a string-keyed array or an object. Other return shapes fall back to public properties. A context that cannot be serialized is replaced by a core-owned placeholder entry, so one bad context never loses the session.
2. Log a Workflow
3. Output Shape
flush() returns a LogJson object. Its public JSON is a tree in record order: entries lists what happened at the root, each entry has a kind of open or event, and every open carries its own children (events and nested opens, in the order they were recorded) plus its matching close. Reading the document top to bottom is reading the timeline.
close is absent while an open is still unclosed. A top-level close list appears only for orphan closes (a close whose openId matches no open in the log, or a second close for an open that is already closed); it is diagnostic output, not part of the normal tree.
The Logger Never Throws
SemanticLogger never throws — not on serialization failures, not on protocol misuse, not on empty sessions. Failures become data: core-owned diagnostic entries in the log itself.
- A context that cannot be serialized is replaced by a
semantic_logger_invalid_contextplaceholder that keeps the entry's position in the tree; children still attach to it. The loss radius of one bad context is that entry — never the session. - Protocol misuse is recorded as
semantic_logger_errorentries (see below). flush()always returns a log and always resets: an empty session is a valid empty document ("entries": []), and an unclosed session returns its live tree with anunclosed_at_flushdiagnostic.toArray()/jsonSerialize()are total, non-destructive snapshots.
Quality gates live on the reading side: the validator lists diagnostics with their own severity, and --fail-on-diagnostics lets CI turn their presence into a failing build.
Note the layer boundary: diagnostics cover the logger's own recording operations. Detecting that a cache server or database is down is monitoring's job, not this library's — record what matters to your domain as your own context types.
Open / Close Ordering
open and close must be paired in LIFO order. The logger never throws on violations — it records them as semantic_logger_error diagnostic entries with one of these kind values:
close_id_mismatch—close()called with an id other than the innermost open; the stack is left untouched (no guessing), so correct closes still workclose_without_open—close()called with no open operation on the stack; the context is discarded and the session continuesunclosed_at_flush—flush()called while opens are still pending; the live tree is returned and the session resets
Wrap work in try/finally so close() always runs — not because the logger throws, but because your log should reflect what actually happened.
Try It
A runnable end-to-end example lives under demo/ (see demo/run.php, demo/e-commerce.php). composer demo runs it with XHProf + Xdebug enabled, validates the output, and renders it with stree.
Development Logs
Use DevLogger to write logs to disk during development:
Each call writes a file named semantic-dev-<timestamp>-<pid>-<uniqid>.json (microsecond timestamp, PID, and uniqid() suffix) to the given directory, or to sys_get_temp_dir() when no directory is passed.
DevLogger writes the same public tree JSON shape returned by flush(), which works naturally with stree.
Profiling (XHProf / Xdebug)
Wrap a SemanticLogger in DevSemanticLogger to attach per-operation profiler artifacts to each matched close entry:
When XHProf and/or Xdebug are enabled, each close in the tree gains a profile object with wallTime plus xhprofProfile / xdebugTrace segments captured while that operation was active:
Segments are attributed only to the operation they ran inside — the parent's profile pauses while a child is open. No extensions required to use the logger itself; DevSemanticLogger simply skips profile attachment when XHProf / Xdebug are not loaded.
Validate Semantic Logs
The envelope (root tree) is always validated against the bundled docs/schemas/semantic-log.json shipped in the composer dist. You supply a schema directory for your own context schemas — the CLI defaults to ./schemas/ when the second argument is omitted.
Validation checks:
- nested log structure
- schema URL resolution
- context payloads against their schemas
- static context metadata: entry types must match
^[a-z_]+$outside the reservedsemantic_logger_*namespace, and schema URLs must be absolute URIs or./schemas/<name>.json - diagnostic entries recorded by the logger, listed with their own severity and validated against the bundled core schemas
- detailed validation errors when something does not match
Pass --fail-on-diagnostics to exit non-zero when the log contains logger-recorded diagnostic entries — the recommended CI gate:
Semantic Tree Visualizer
vendor/bin/stree renders semantic logs as a readable tree:
Options
| Option | Short | Description |
|---|---|---|
--threshold=T |
-t |
Time threshold filter such as 10ms or 0.5s |
--lines=N |
-l |
Maximum lines for multi-line data (0 means no limit) |
--full |
-f |
Show the full tree |
--values |
-V |
Let registered formatters show values instead of only keys |
--json |
Pretty-print raw JSON | |
--help |
-h |
Display help |
Rendering in process
stree is a thin CLI over the same renderer you can call directly. LogJson::render() takes a LogRendererInterface and hands the log to it (double dispatch), so the log never needs to know the output format — you swap the renderer instead:
This keeps the tree compact for both humans (visual parent/child structure) and AI consumers (far fewer tokens than the raw JSON). Implement LogRendererInterface to add your own output format (e.g. Markdown or Mermaid) without changing the logger.
Use Cases
- trace nested application workflows
- compare planned work vs actual result
- keep audit-friendly structured records
- inspect development logs without parsing free-form text
- render semantic logs as trees during debugging
Documentation
- Schema Portal
- MIGRATION.md — 0.8 / 1.x → 0.9 migration guide
- CHANGELOG.md