kislayphp/discovery

High-performance C++ PHP extension providing service discovery and registration for PHP microservices

0.0.6 2026-03-18 19:25 UTC

Requires

• php: >=8.2

Suggests

• kislayphp/config: Dynamic service configuration
• kislayphp/core: HTTP/HTTPS server foundation
• kislayphp/eventbus: Service change notifications
• kislayphp/gateway: Service-aware API gateway
• kislayphp/metrics: Service health metrics
• kislayphp/queue: Service-aware message queuing

Provides

• ext-kislayphp_discovery: *

Apache-2.0

• KislayPHP Team

• php
• microservices
• php-extension
• php-echo-system
• cpp-extension
• php-service-discovery
• php-consul
• php-etcd
• php-service-registry
• php-zookeeper
• php-health-checks
• php-microservices-discovery
• distributed-services
• php-service-mesh
• php-load-balancing

Extension name: ext-kislayphp_discovery

Supports Zend Thread Safety (ZTS): ✅

Supports non-Thread Safe mode (NTS): ✅

Supported operating systems: no restrictions

README

Thin service registry for KislayPHP. Register instances, track health, and resolve healthy URLs without embedding business logic.

Installation

Via PIE (recommended):

pie install kislayphp/discovery:0.0.6

Add to php.ini:

extension=kislayphp_discovery.so

Role In The Stack

Discovery only does:

• register service instances
• update health/status
• resolve service name to healthy instance URL
• expose thin registry HTTP endpoints when running standalone

Discovery does not do:

• business logic
• request execution
• JWT handling
• trace mutation

Quick Start

Start the registry

<?php

$registry = new Kislay\Discovery\ServiceRegistry();
$registry->listen('0.0.0.0', 9010);
$registry->run();

Register a service

<?php

$registry = new Kislay\Discovery\ServiceRegistry('http://127.0.0.1:9010');
$registry->register('user-service', 'http://127.0.0.1:9008', ['zone' => 'az-1'], 'user-1');

Resolve a service

<?php

$registry = new Kislay\Discovery\ServiceRegistry('http://127.0.0.1:9010');
$url = $registry->resolve('user-service');
var_dump($url);

Runtime Behavior

• resolve() only returns UP and heartbeat-fresh instances.
• stale instances are lazily pruned before local read paths return data.
• weighted selection uses std::mt19937, not rand().
• registration is capped per service to avoid unbounded growth.
• standalone server mode exposes registry-only HTTP endpoints.

Optional Redis Storage

Discovery supports:

• memory backend by default
• redis backend optionally for shared registry state

When Redis is configured:

• writes are mirrored locally and sent to Redis
• reads attempt Redis first
• on Redis failure, Discovery falls back to in-memory state with a warning
• fallback preserves node-local safety, not cluster-wide strong consistency

Environment Variables

Variable	Default	Description
KISLAY_DISCOVERY_HEARTBEAT_TIMEOUT_MS	90000	Max heartbeat age before stale
KISLAY_DISCOVERY_MAX_INSTANCES_PER_SERVICE	1024	Per-service registration cap
KISLAY_DISCOVERY_STORAGE	memory	memory or redis
KISLAY_DISCOVERY_REDIS_HOST	127.0.0.1	Redis host
KISLAY_DISCOVERY_REDIS_PORT	6379	Redis port
KISLAY_DISCOVERY_REDIS_DB	0	Redis DB index
KISLAY_DISCOVERY_REDIS_TIMEOUT_MS	200	Redis socket timeout
KISLAY_DISCOVERY_REDIS_PASSWORD	empty	Redis password
KISLAY_DISCOVERY_REDIS_PREFIX	kislay:discovery	Redis key prefix
KISLAY_RPC_ENABLED	0	Enable RPC mode when built with RPC support
KISLAY_RPC_DISCOVERY_ENDPOINT	127.0.0.1:9090	RPC discovery endpoint
KISLAY_RPC_TIMEOUT_MS	200	RPC timeout in ms

Notes

• In-memory mode is still the simplest local default.
• Redis mode gives shared registry storage without adding a client library dependency.
• If Redis is unavailable, fallback is safe but degrades to node-local view.

License