How to Build RPC Services with ThinkPHP Swoole: Step-by-Step Guide

Introduction

Remote Procedure Call (RPC) allows a program to invoke functions on a remote machine as if they were local calls. The ThinkPHP Swoole integration implements a TCP‑based RPC layer, enabling traditional PHP applications to build simple distributed systems.

Distributed Call Model

Server – provides and exposes services.

Client – consumes remote services.

Registry – service discovery and registration center.

Prerequisites

Compile and install the Swoole PHP extension.

Disable the Xdebug extension because it conflicts with Swoole coroutines.

Dependency Installation

composer require topthink/think-swoole

This command creates a config/swoole.php configuration file in the project.

Server Configuration

All server‑side settings are placed in config/swoole.php.

HTTP Service Settings

Enable RPC and Register Services

Enable the RPC module in config/swoole.php.

Define an RPC interface that declares the remote methods.

Implement the interface in a service class.

<?php

declare(strict_types=1);

namespace app\rpc\service;

use app\rpc\contracts\UserInterface;

class UserService implements UserInterface
{
    public function add($name)
    {
        return "You added: " . $name;
    }

    public function list()
    {
        return "list";
    }
}

The dispatcher ( think\swoole\rpc\server\Dispatcher::prepareServices) scans for these interfaces to register services.

Start the Server

# php think swoole start
Starting swoole http server...
Swoole http server started: http://0.0.0.0:8787
You can exit with `CTRL-C`

Client Configuration

Client‑side settings are also stored in config/swoole.php.

HTTP Service Settings

Configure RPC Connection

Specify the server address (host and port) in the RPC section of config/swoole.php.

Generate RPC Interface Stubs

php think rpc:interface

The command creates app/rpc.php containing the generated contract and a service map:

<?php
/**
 * This file is auto‑generated.
 */

declare(strict_types=1);

namespace rpc\contract\userservice;

interface UserInterface
{
    public function add($name);
    public function list();
}

return [
    'userservice' => ['rpc\contract\userservice\UserInterface']
];

Client Call Example

use rpc\contract\userservice\UserInterface;

public function rpctest(UserInterface $userInterface)
{
    return $userInterface->add('Tinywan');
}

The injected UserInterface proxy forwards the call to the remote server and returns the result.

Hot Reload

Swoole keeps PHP files in memory for maximum performance, so code changes require a manual reload or restart. The think‑swoole extension can watch configured directories and automatically trigger a reload when APP_DEBUG=true in the .env file. Hot reload is discouraged in production because of the additional file‑system monitoring overhead.

Common Errors

Xdebug Conflict

Swoole\Server::start(): Using Xdebug in coroutines is extremely dangerous

Solution: disable the Xdebug extension before starting the Swoole server.