PHPackages                             pogo/pogo - 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. [Utility & Helpers](/categories/utility)
4. /
5. pogo/pogo

ActiveLibrary[Utility & Helpers](/categories/utility)

pogo/pogo
=========

High-performance pogo library for PHP (FrankenPHP Extension)

v0.0.9(4mo ago)05[10 PRs](https://github.com/y-l-g/pogo/pulls)MITPHPPHP >=8.4CI passing

Since Nov 24Pushed 1mo agoCompare

[ Source](https://github.com/y-l-g/pogo)[ Packagist](https://packagist.org/packages/pogo/pogo)[ RSS](/packages/pogo-pogo/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (9)Dependencies (3)Versions (20)Used By (0)

Pogo (PHP Over Go)
==================

[](#pogo-php-over-go)

The **Pogo Extension for FrankenPHP** is a high-performance, systems-level library designed to introduce **True Parallelism**, **Go-native Concurrency Primitives**, and **OS-Level Process Management** into the PHP ecosystem.

Unlike PHP Fibers (which provide cooperative multitasking within a single thread) or standard Async PHP libraries (which rely on the user-land event loop), this extension leverages **Goroutines**, **OS Processes**, and **Memory-Mapped Shared Memory** to execute tasks simultaneously across multiple CPU cores with near-zero overhead.

Table of Contents
-----------------

[](#table-of-contents)

- [Introduction](#introduction)
- [Usage Examples](#usage-examples)
- [API Reference](#api-reference)
    - [Global Functions](#global-functions)
    - [Classes](#classes)
    - [Internal Functions (Advanced)](#internal-functions-advanced)
- [Architecture & Tech Stack](#architecture--tech-stack)
    - [The Supervisor & Process Manager](#layer-a-the-supervisor--process-manager)
    - [The Manager & Registry](#layer-b-the-manager--registry)
    - [The "Dumb" Bridge (CGO)](#layer-c-the-dumb-bridge-cgo)
    - [The Protocol & Transport](#layer-d-the-protocol--transport)
    - [Shared Memory (Ring Buffer)](#layer-e-shared-memory)
- [Observability & Metrics](#observability--metrics)
- [Performance Engineering](#performance-engineering)
- [The Protocol Specification](#the-protocol-specification)
- [Current Status & Limitations](#current-status--limitations)

---

Introduction
------------

[](#introduction)

### Core Philosophy

[](#core-philosophy)

1. **The "OS" Pattern:** The Go Host acts as the Operating System/Supervisor. It manages memory, scheduling, I/O, and process lifecycles. The PHP Workers act as User-Space applications; they focus solely on business logic.
2. **Clean Separation:** Communication occurs over explicit IPC channels (Pipes) and Shared Memory segments. The architecture enforces a strict boundary where the Go runtime guarantees stability even if the PHP child process crashes, hangs, or leaks memory.
3. **Magic Marshalling:** Go primitives (Channels, WaitGroups) are exposed to PHP as objects. When passed between contexts, they are automatically marshalled into lightweight handles (`uintptr`), allowing PHP scripts to coordinate complex topologies without understanding the underlying Go memory pointers.
4. **Hybrid Transport:**
    - **Small Payloads (<1KB):** Travel via standard Pipes (`php://fd/3`, `php://fd/4`) for ultra-low latency.
    - **Large Payloads (>1KB):** Transparently switch to **Shared Memory (Mmap)**. This version utilizes a **Map-Backed FIFO Ring Buffer** to bypass pipe buffer limitations and reduce syscall overhead, achieving throughputs exceeding 800 MB/s.
5. **"Dumb C" Architecture:** To maximize stability, the C extension layer is kept intentionally thin. It performs no complex logic or data parsing. It simply acts as a conduit, passing raw bytes or handles between the PHP engine and the Go runtime. All serialization logic (JSON/MsgPack) resides in PHP userland or Go, mitigating the risk of segmentation faults common in complex C extensions.

---

### Quick Start

[](#quick-start)

You can get a "Hello World" running in less than 5 minutes using Docker or a pre-compiled binary.

**1. Setup Files**

Install the library via Composer:

```
composer require pogo/pogo
```

Create three files in a `public/` directory:

`public/HelloWorldJob.php` (The Business Logic):

```