Optimizations

.github/workflows/build.yml

@@ -25,5 +25,13 @@ jobs:
         run: ./configure --enable-trochilidae
       - name: make
         run: make
-      - name: run test.php
-        run: php -d extension=`pwd`/modules/trochilidae.so -f test.php
+      - name: make test
+        run: make test
+      - name: Compile unit tests
+        run: gcc -I/usr/include/php -I/usr/include/php/main -I/usr/include/php/Zend -I/usr/include/php/TSRM -I/usr/include/php/ext -I. -DHAVE_CONFIG_H -D_GNU_SOURCE -g -O0 tests/unit_test.c trochilidae/tr_network.c trochilidae/utils.c -o tests/unit_test
+      - name: Run unit tests
+        run: ./tests/unit_test
+      - name: Compile internal unit tests (tr_array, tr_timer)
+        run: gcc -I. -Itests/stubs -DHAVE_CONFIG_H -g -O0 -Wall tests/tr_internal_test.c -o tests/tr_internal_test -lm
+      - name: Run internal unit tests
+        run: ./tests/tr_internal_test

.github/workflows/opencode.yml

@@ -0,0 +1,33 @@
+name: opencode
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+jobs:
+  opencode:
+    if: |
+      contains(github.event.comment.body, ' /oc') ||
+      startsWith(github.event.comment.body, '/oc') ||
+      contains(github.event.comment.body, ' /opencode') ||
+      startsWith(github.event.comment.body, '/opencode')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+      pull-requests: read
+      issues: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Run opencode
+        uses: anomalyco/opencode/github@latest
+        env:
+          OPENCODE_API_KEY: ${{ secrets.OPENCODE_API_KEY }}
+        with:
+          model: opencode/deepseek-v4-flash-free

.gitignore

@@ -18,4 +18,9 @@
 !test.php
 !/trochilidae
 !package.xml
-!Dockerfile
+!Dockerfile
+!.opencode
+!/docs
+
+!/tests/stubs/php.h
+!/tests/install_test.sh

.opencode/instructions.md

@@ -0,0 +1,35 @@
+# Project Guidelines: php_trochilidae
+
+This project is a C-based PHP extension for metrics collection.
+
+## Project Structure
+- `trochilidae/`: Contains core functional sub-components.
+    - `tr_array.c/h`: Buffer and array manipulation (binary serialization).
+    - `tr_network.c/h`: TCP/UDP socket communication.
+    - `tr_timer.c/h`: High-resolution timers and Zend resource management.
+    - `tr_hooks.c`: Hooks for SAPI integration (intercepting output/execution).
+    - `utils.c/h`: Helper functions and utility macros.
+- `docs/protocol.md`: Wire format specification for the UDP protocol.
+- `tests/`: Contains `.phpt` files for integration testing.
+
+## Core Conventions
+- **Naming:** 
+    - Internal functions: `tr_` prefix.
+    - PHP-exposed functions: `trochilidae_` prefix.
+- **State Management:** Use `ZEND_DECLARE_MODULE_GLOBALS` and access globals via the `TR_G()` macro.
+- **Resources:** Use Zend resource registration (`zend_register_list_destructors_ex`) for automated lifecycle management.
+- **Performance:** Maintain low overhead; use custom binary serialization over JSON where possible.
+- **Error Handling:** Use `php_error_docref`.
+
+## Build & Test Workflow
+1.  **Configuration:** `phpize && ./configure --enable-trochilidae`
+2.  **Compilation:** `make`
+3.  **PHP tests:** `make test`
+4.  **C unit tests (network):**
+    `gcc -I/usr/include/php -I/usr/include/php/main -I/usr/include/php/Zend -I/usr/include/php/TSRM -I/usr/include/php/ext -I. -DHAVE_CONFIG_H -D_GNU_SOURCE -g -O0 tests/unit_test.c trochilidae/tr_network.c trochilidae/utils.c -o tests/unit_test && ./tests/unit_test`
+5.  **C unit tests (internal — tr_array, tr_timer):**
+    `gcc -I. -Itests/stubs -DHAVE_CONFIG_H -g -O0 tests/tr_internal_test.c -o tests/tr_internal_test -lm && ./tests/tr_internal_test`
+    *Note:* These use `tests/stubs/php.h` to mock the Zend API outside of PHP context.
+
+## Stubs
+- `tests/stubs/php.h`: Minimal stub for `emalloc`/`erealloc`/`efree`/`estrdup` and `zend_resource` — used by `tr_internal_test.c` to compile without the real PHP headers.

Dockerfile

@@ -122,11 +122,11 @@ RUN apk add --no-cache unzip git && \
 # trochilidae
 RUN apk add --no-cache build-base autoconf unzip git curl
 ADD . /app
-# php /app/test.php && \
-RUN phpize && ./configure --enable-trochilidae && make clean && make install && docker-php-ext-enable trochilidae && \
-    php -m && \
-    php -r "echo 'Test TR at ',date('c'), PHP_EOL;" && \
-    echo "OK - exit" && \
-    composer install --prefer-dist && \
-    exit 1
+RUN phpize && \
+    ./configure --enable-trochilidae && \
+    make -j$(nproc) && \
+    make install && \
+    docker-php-ext-enable trochilidae && \
+    php -m | grep trochilidae && \
+    tests/install_test.sh
 

README.md

@@ -1,19 +1,96 @@
-# PHP Trochilidae extension
-A PHP extension for metrics collect
+# PHP Trochilidae
 
-[![CodeFactor](https://www.codefactor.io/repository/github/xmlex/php_trochilidae/badge/main)](https://www.codefactor.io/repository/github/xmlex/php_trochilidae/overview/main)
-[![Build Status](https://app.travis-ci.com/xMlex/php_trochilidae.svg?branch=main)](https://app.travis-ci.com/xMlex/php_trochilidae)
+A PHP extension for collecting and sending application metrics (timers, tags, request data) to a remote collector via UDP.
 
+## Requirements
+
+- PHP 7.4+
+- php-dev (for compilation)
+
+## Install
+
+```bash
+phpize
+./configure --enable-trochilidae
+make
+make test
+make install
+```
+
+Enable the extension in `php.ini`:
+
+```ini
+extension=trochilidae.so
+trochilidae.enabled=1
+trochilidae.server_list=collector1.local:30002,collector2.local:30002
 ```
-phpize && ./configure --enable-trochilidae && make && make test
-php -d extension=`pwd`/modules/trochilidae.so -f test.php
-run /home/mlex/CLionProjects/php_trochilidae/test.php
+
+## Configuration
+
+| INI directive | Type | Default | Description |
+|---|---|---|---|
+| `trochilidae.enabled` | bool | `1` | Enable or disable the extension |
+| `trochilidae.server_list` | string | empty | Comma-separated `host:port` pairs of collector servers |
+
+## How it works
+
+Trochilidae hooks into the PHP request lifecycle:
+
+1. **RINIT** — resets metrics, collects pre-request data (tags, server vars)
+2. During the request, you can add tags and use timers via PHP functions
+3. **RSHUTDOWN** — automatically serialises and sends all collected metrics to the configured collector(s) via UDP
+
+For CLI scripts, metrics are also sent on shutdown; call `trochilidae_flush()` explicitly if you need to send data before the end of the script.
+
+## Quick start
+
+```php
+<?php
+
+// Set tags and hostname
+trochilidae_set_tag('env', 'production');
+trochilidae_set_hostname('app01');
+
+// Profile a section of code
+trochilidae_timer_start('db_query');
+// ... do work ...
+trochilidae_timer_stop('db_query');
+
+// Get stats for all timers
+$info = trochilidae_timer_get_info();
+// $info['timers'][0]['startCount']        – start count
+// $info['timers'][0]['stopCount']         – stop count
+// $info['timers'][0]['totalExecutionTime'] – total time in seconds
+// $info['timers'][0]['lastExecutionTime']  – last lap in seconds
+
+//[optional] Send collected metrics (send by default, after execute script/request)
+trochilidae_flush();
 ```
 
-TODO:
-- ~~REQUEST_TIME from php~~
-- request id
-- ~~timers~~
+## PHP Functions
+
+| Function | Description |
+|---|---|
+| `trochilidae_set_tag(string $key, string $value)` | Set a custom tag |
+| `trochilidae_set_hostname(string $hostname)` | Override the default hostname |
+| `trochilidae_timer_start(string $name)` | Start or resume a named timer |
+| `trochilidae_timer_stop(string $name)` | Stop a named timer (no-op if not running) |
+| `trochilidae_timer_get_info()` | Get all timer statistics as nested array |
+| `trochilidae_flush()` | Send collected metrics to the collector |
+| `trochilidae_reset()` | Reset all collected metrics |
+
+## TODO
+
+### 🟢 Protocol (`docs/protocol.md`)
+
+| # | Change | Why |
+|---|---|---|---|
+| P2 | **tv_sec → 64-bit `long`** | Avoid Y2038 overflow (time_t is 64-bit on modern systems) |
 
+### 🔴 Stability & Scalability (code)
 
+| # | Change | Where | Why |
+|---|---|---|---|
+| S10 | **IPv6 support (`sockaddr_storage` + `getaddrinfo`)** | `tr_network.h:62` | Currently `sockaddr_in` = IPv4 only |
+| S12 | **Fix `tv_usec` calc: `1e6 * 1000` → `1e6`** | `trochilidae.c:502,508` | Double multiplication produces wrong microseconds |
 

config.m4

@@ -9,6 +9,7 @@ if test "$PHP_TROCHILIDAE" != "no"; then
   trochilidae/tr_array.c
   trochilidae/tr_network.c
   trochilidae/tr_timer.c
+  trochilidae/tr_hooks.c
   trochilidae.c"
 
   PHP_NEW_EXTENSION(trochilidae, $trochilidae_sources, $ext_shared,,)