openapi: 3.1.0
info:
  title: PHP-FPM Status and Ping Endpoints
  description: |
    PHP-FPM (FastCGI Process Manager) does not expose a public HTTP API for
    runtime configuration, but it does expose two operational HTTP endpoints
    via the web server that proxies FastCGI requests to PHP-FPM. The status
    endpoint is enabled by setting `pm.status_path` and reports pool
    metrics in plain text, full text, HTML, JSON, XML, or OpenMetrics
    format depending on a query-string flag. The ping endpoint is enabled
    by setting `ping.path` and returns a configurable static response
    (default `pong`) suitable for upstream health checks.

    The actual paths are administrator-defined; the most common
    conventions (`/fpm-status` and `/fpm-ping`) are modeled here. Authentication
    and access control are handled by the fronting web server, not by
    PHP-FPM itself.
  version: "1.0.0"
  contact:
    name: PHP-FPM documentation
    url: https://www.php.net/manual/en/install.fpm.php
  license:
    name: PHP License
    url: https://www.php.net/license/
externalDocs:
  description: PHP-FPM status page documentation
  url: https://www.php.net/manual/en/fpm.status.php
servers:
  - url: http://{host}
    description: Web server fronting PHP-FPM.
    variables:
      host:
        default: localhost
        description: Hostname of the web server proxying FastCGI requests.
tags:
  - name: Status
    description: PHP-FPM pool status.
  - name: Ping
    description: PHP-FPM liveness check.
paths:
  /fpm-status:
    get:
      tags: [Status]
      summary: Get PHP-FPM pool status
      description: |
        Returns PHP-FPM pool metrics. The output format is selected via a
        query-string flag and may include per-process detail when `full`
        is set. The default response is plain text.
      operationId: getStatus
      parameters:
        - in: query
          name: full
          schema:
            type: string
          allowEmptyValue: true
          description: When present, includes per-process detail.
        - in: query
          name: json
          schema:
            type: string
          allowEmptyValue: true
          description: Return JSON output.
        - in: query
          name: xml
          schema:
            type: string
          allowEmptyValue: true
          description: Return XML output.
        - in: query
          name: html
          schema:
            type: string
          allowEmptyValue: true
          description: Return HTML output.
        - in: query
          name: openmetrics
          schema:
            type: string
          allowEmptyValue: true
          description: Return OpenMetrics output.
      responses:
        "200":
          description: PHP-FPM status.
          content:
            text/plain:
              schema:
                type: string
            application/json:
              schema:
                $ref: "#/components/schemas/PoolStatus"
            application/xml:
              schema:
                type: string
            text/html:
              schema:
                type: string
            application/openmetrics-text:
              schema:
                type: string

  /fpm-ping:
    get:
      tags: [Ping]
      summary: PHP-FPM liveness check
      description: |
        Returns the configured `ping.response` value (default `pong`),
        confirming that the PHP-FPM master and worker pool are responsive.
      operationId: getPing
      responses:
        "200":
          description: PHP-FPM ping response.
          content:
            text/plain:
              schema:
                type: string
                example: pong

components:
  schemas:
    PoolStatus:
      type: object
      properties:
        pool:
          type: string
        process manager:
          type: string
          enum: [static, dynamic, ondemand]
        start time:
          type: integer
        start since:
          type: integer
        accepted conn:
          type: integer
        listen queue:
          type: integer
        max listen queue:
          type: integer
        listen queue len:
          type: integer
        idle processes:
          type: integer
        active processes:
          type: integer
        total processes:
          type: integer
        max active processes:
          type: integer
        max children reached:
          type: integer
        slow requests:
          type: integer