PHPackages coffee-r/tekagami-php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [HTTP & Networking](/categories/http) 4. / 5. coffee-r/tekagami-php ActiveLibrary[HTTP & Networking](/categories/http) coffee-r/tekagami-php ===================== PHP library for observing HTTP request behavior and recording as JSONL for specification investigation v0.1.0(1mo ago)00MITPHPPHP >=7.0 Since Jun 2Pushed 1mo agoCompare [ Source](https://github.com/coffee-r/tekagami-php)[ Packagist](https://packagist.org/packages/coffee-r/tekagami-php)[ RSS](/packages/coffee-r-tekagami-php/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (3)Versions (2)Used By (0) tekagami-php ============ [](#tekagami-php) Note This package is experimental. `coffee-r/tekagami-php` is the PHP observer for tekagami. It records what a running PHP web application actually did as one `tekagami-v1` JSONL record per HTTP request. The observer emits observed facts: HTTP input/output shapes, SQL timeline, custom events, write effects, and capture errors. It does not infer business rules, name specifications, or measure performance as an APM. For the language-neutral JSONL contract, see [`contracts/schema`](../contracts/schema/README.md). For deterministic `summary`, `report`, `export`, and `diff` commands, see [`tools/tekagami-data`](../tools/tekagami-data/README.md). Installation ------------ [](#installation) ``` composer require coffee-r/tekagami-php ``` Runtime requirement: PHP 7.0 or later. Development tests require PHP 7.3 or later because PHPUnit `^9.5` is used. Basic Usage ----------- [](#basic-usage) Create one collector per HTTP request, call `start()` near request entry, add observed events during the request, then call `finish()` near response output. ``` use CoffeeR\Tekagami\Collector; use CoffeeR\Tekagami\Config; use CoffeeR\Tekagami\Flow; use CoffeeR\Tekagami\Http\HttpInput; use CoffeeR\Tekagami\Http\HttpResponse; use CoffeeR\Tekagami\Sink\JsonlSink; use CoffeeR\Tekagami\Sql\SqliteSqlAnalyzer; $collector = new Collector( new Config(getenv('TEKAGAMI_SECRET') ?: null), new JsonlSink('/var/log/tekagami/your-app.production.jsonl'), new SqliteSqlAnalyzer() ); $http = new HttpInput($request->method(), $request->path()); $http->pathPattern = '/products/{id}'; $http->queryRaw = $request->query(); $http->requestRaw = $requestBody; $http->requestHeadersRaw = $requestHeaders; $collector->start($http); // Use Flow only when a development or QA scenario needs explicit correlation. // $collector->start($http, new Flow('qa-order-cod-001', 1)); // Preferred: placeholder SQL plus binds. $collector->addSql($sql, $binds, ['source' => 'db-wrapper']); // Fallback: expanded SQL from last_query() or query history. $collector->addExpandedSql($db->last_query(), ['source' => 'ci3-last_query']); // Stable labels can act as observation anchors for important branches. $collector->addCustom('purchase_limit_rejected', ['reason' => 'one_time']); $response = new HttpResponse(); $response->status = http_response_code(); $response->responseKind = 'json'; $response->contentType = 'application/json'; $response->responseHeadersRaw = $responseHeaders; $response->responseBodyRaw = $responseData; $collector->finish($response); ``` If no `Flow` is passed, `flow.flow_id` and `flow.seq` are recorded as `null`. This is the normal mode. Flow is for explicit investigation scenarios, not for inferring business workflows from production sessions. Public API ---------- [](#public-api) `Collector` implements `CollectorInterface`: MethodPurpose`start(HttpInput $http, $flow = null)`Starts one request trace.`getActiveTraceId()`Returns the active trace id, or `null`.`addSql($sql, array $binds = [], array $options = [])`Records placeholder SQL plus binds. Preferred when available.`addExpandedSql($sql, array $options = [])`Records already-expanded SQL. Lower confidence because binds are lost.`addCustom($label, $data = null)`Records a custom observation with `data_shape`.`addError($type, $message = null, $at = null)`Records an observed application or capture error.`finish(HttpResponse $response)`Builds and writes the JSONL record, then resets the collector.All methods are designed not to throw into the observed application. If sink writing fails, tekagami writes to PHP `error_log()` and lets the application continue. Configuration ------------- [](#configuration) Constructor: ``` new Config($secret = null, array $options = []) ``` `$secret` is the HMAC-SHA256 shared secret. Other settings are passed through `$options`. OptionTypeDefaultDescription`secret``stringnull``null``keepKeys``array``[]`Case-insensitive allowlist of query/body keys whose raw values may be recorded in `*_values`.`keepHeaderKeys``array``[]`Case-insensitive allowlist of request headers to record as shape/token. Empty means no request header presence is recorded.`keepResponseHeaderKeys``array``[]`Case-insensitive allowlist of response headers to record as shape/token. Empty means no response header presence is recorded.`sqlValueAllowlist``array``[]`SQL value allowlist, using `table.column` or `column`, for `observed_values`.`enabled``bool``true`When `false`, collector methods return immediately. Lower cost than `NullSink`.`captureText``bool``false`Stores raw SQL in `statement_text`. Plaintext and not recommended for production.`captureEffects``bool``true`Emits write summaries in `effects[]`.`tokenHmacLength``int``12`Hex length of generated HMAC token fragments.`maxDepth``int``10`Maximum recursion depth for shape generation.`maxShapeNodes``int``10000`Maximum visited nodes during shape generation.`maxTimelineSize``intnull``500`Value Safety ------------ [](#value-safety) Raw values are not recorded by default. Shapes preserve structure and scalar types. HMAC tokens, when `secret` is set, allow correlation of equal values without storing the original value. Only values explicitly allowed by `keepKeys` or `sqlValueAllowlist` are stored as plaintext. Do not allowlist passwords, tokens, email addresses, phone numbers, addresses, postal codes, authentication data, payment data, customer ids, order ids, or other values strongly tied to people or transactions. Use tokens for correlation-only use cases. Request and response headers are stricter: only headers named in `keepHeaderKeys` or `keepResponseHeaderKeys` are recorded, and header raw values are never stored. `Authorization`, `Cookie`, `Set-Cookie`, `Location`, and `X-Api-Key` are sensitive even as presence information, so keep them out unless there is a specific investigation reason. Avoid passing raw exception messages to `addError()` in production. They can contain DSNs, SQL, file paths, or user data. Prefer fixed error types or sanitized messages. SQL Capture ----------- [](#sql-capture) Use the highest-quality SQL source available. APIInput`analysis.input_quality`Typical source`addSql($sql, $binds, ['source' => '...'])`Placeholder SQL plus binds`bound_sql`PDO wrapper, DB middleware, Laravel `DB::listen`, Doctrine middleware, patched CI3 DB driver`addExpandedSql($sql, ['source' => '...'])`Expanded SQL`expanded_sql`CI3 `last_query()` or query history when binds are unavailable`addExpandedSql()` records warnings such as `expanded_sql_may_fragment_statement_hash`. It is useful when there is no better source, but prefer `addSql()` for migration comparison because statement hashes are more stable. `sqlValueAllowlist` extraction is best-effort and regex based. It handles common `INSERT ... VALUES (...)`, `UPDATE ... SET ...`, and `WHERE col = value` cases, but may miss values inside functions, strings with commas, complex subqueries, or dialect-specific literals. Missing extraction does not fail the observation; `statement_normalized`, `statement_hash`, and `statement_fingerprint` remain the primary evidence. SQL Dialect ----------- [](#sql-dialect) The SQL analyzer is required as the third `Collector` constructor argument. Bundled analyzers: - `CoffeeR\Tekagami\Sql\OracleSqlAnalyzer` - `CoffeeR\Tekagami\Sql\SqliteSqlAnalyzer` ``` $collector = new Collector( $config, $sink, new CoffeeR\Tekagami\Sql\OracleSqlAnalyzer() ); ``` The selected dialect is recorded on each SQL event as `analysis.dialect`. For PostgreSQL, MySQL, SQL Server, or another database, implement `SqlAnalyzerInterface` or extend `AbstractSqlAnalyzer`, then inject that implementation into `Collector`. Custom Events ------------- [](#custom-events) `addCustom()` is for observations that SQL alone cannot explain: cache access, external HTTP calls, queue pushes, file writes, or important application branches. The `data_shape` is not part of behavior pattern signatures. If a branch must be compared as a distinct behavior, encode the stable distinction in the label, for example `payment_method_rejected_cod` rather than only `payment_method_rejected` with a data value. Log Volume ---------- [](#log-volume) Primary controls: - `maxTimelineSize`: prevents one request from producing an unbounded timeline. - `maxShapeNodes`: bounds very large JSON or view variable shapes. - OS-level log rotation: keeps JSONL files manageable over time. When a limit is reached, tekagami truncates only its own observation and records a `capture_failure` in `errors[]`. The application request continues. Data Tools ---------- [](#data-tools) This package only writes `tekagami-v1` JSONL. Process those logs from the repository root with the language-neutral data tools: ``` php tools/tekagami-data/bin/tekagami summary trace.jsonl php tools/tekagami-data/bin/tekagami report trace.jsonl php tools/tekagami-data/bin/tekagami export trace.jsonl > trace.export.json php tools/tekagami-data/bin/tekagami diff legacy.export.json target.export.json ``` See [`tools/tekagami-data/README.md`](../tools/tekagami-data/README.md) for CLI options and behavior. Schema ------ [](#schema) Output records must conform to [`contracts/schema/tekagami-v1.schema.json`](../contracts/schema/tekagami-v1.schema.json). Tests in this package include schema conformance checks for fixtures and collector output. Running Tests ------------- [](#running-tests) ``` cd observer-php composer install ./vendor/bin/phpunit ``` License ------- [](#license) MIT License - Copyright 2026 coffee-r ### Health Score 29 — LowBetter than 57% of packages Maintenance90 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity18 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 52d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/60351025?v=4)[coffee-r](/maintainers/coffee-r)[@coffee-r](https://github.com/coffee-r) --- Top Contributors [![coffee-r](https://avatars.githubusercontent.com/u/60351025?v=4)](https://github.com/coffee-r "coffee-r (3 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/coffee-r-tekagami-php/health.svg) ``` [![Health](https://phpackages.com/badges/coffee-r-tekagami-php/health.svg)](https://phpackages.com/packages/coffee-r-tekagami-php) ``` ### Alternatives [php-http/cache-plugin PSR-6 Cache plugin for HTTPlug 25026.1M82](/packages/php-http-cache-plugin)[httpsoft/http-message Strict and fast implementation of PSR-7 and PSR-17 87965.9k122](/packages/httpsoft-http-message)[serpapi/google-search-results-php Get Google, Bing, Baidu, Ebay, Yahoo, Yandex, Home depot, Naver, Apple, Duckduckgo, Youtube search results via SerpApi.com 69127.2k](/packages/serpapi-google-search-results-php)[swoft/websocket-server swoft websocket server component 16135.7k5](/packages/swoft-websocket-server)[thesis/nats Async (fiber based) client for Nats. 754.4k](/packages/thesis-nats)[jasny/http-signature Implementation of the IETF HTTP Signatures draft RFC 10104.7k](/packages/jasny-http-signature) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)