PHPackages                             hoa/socket - 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. [DevOps & Deployment](/categories/devops)
4. /
5. hoa/socket

AbandonedArchivedLibrary[DevOps & Deployment](/categories/devops)

hoa/socket
==========

The Hoa\\Socket library.

1.17.05.16(9y ago)62412.1k—3.1%22[3 PRs](https://github.com/hoaproject/Socket/pulls)12BSD-3-ClausePHP

Since Sep 16Pushed 5y ago14 watchersCompare

[ Source](https://github.com/hoaproject/Socket)[ Packagist](https://packagist.org/packages/hoa/socket)[ Docs](https://hoa-project.net/)[ RSS](/packages/hoa-socket/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (18)Used By (12)

 [![Hoa](https://camo.githubusercontent.com/2b5c32c5d4bc5e9298821b22d364a522e2dbc0295c1c011b1f9f86a4d07df07e/68747470733a2f2f7374617469632e686f612d70726f6a6563742e6e65742f496d6167652f486f612e737667)](https://camo.githubusercontent.com/2b5c32c5d4bc5e9298821b22d364a522e2dbc0295c1c011b1f9f86a4d07df07e/68747470733a2f2f7374617469632e686f612d70726f6a6563742e6e65742f496d6167652f486f612e737667)

---

 [![Build status](https://camo.githubusercontent.com/3c01a94cd9b25121c926f525dd72c722d92a8e46da0d31a074e97444c8092b27/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f686f6170726f6a6563742f536f636b65742f6d61737465722e737667)](https://travis-ci.org/hoaproject/Socket) [![Code coverage](https://camo.githubusercontent.com/0da5dabda0c600a77484e9cbbe4ca378669702f0264ca6f709376fba190934e0/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f686f6170726f6a6563742f536f636b65742f6d61737465722e737667)](https://coveralls.io/github/hoaproject/Socket?branch=master) [![Packagist](https://camo.githubusercontent.com/546bd8fb81324ff1d227b289d33230b8cf5531f3df73eb0b2f4b67cda728cd2f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f686f612f736f636b65742e737667)](https://packagist.org/packages/hoa/socket) [![License](https://camo.githubusercontent.com/cae524c93c0dd0b24a7348ef42de00419e8828594b798b8928ea03015c9452f5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f686f612f736f636b65742e737667)](https://hoa-project.net/LICENSE)

 Hoa is a **modular**, **extensible** and **structured** set of PHP libraries.
 Moreover, Hoa aims at being a bridge between industrial and research worlds.

Hoa\\Socket
===========

[](#hoasocket)

[![Help on IRC](https://camo.githubusercontent.com/4dbc9c9d28c30cf1ab591f4bb8212fe4dbddc734145df532a9bb86b09878d4c6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f68656c702d253233686f6170726f6a6563742d6666303036362e737667)](https://webchat.freenode.net/?channels=#hoaproject)[![Help on Gitter](https://camo.githubusercontent.com/8c4c85951788ff606b1268cb3dd946be05e3054795455d0a7b9250711bc2ac05/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f68656c702d6769747465722d6666303036362e737667)](https://gitter.im/hoaproject/central)[![Documentation](https://camo.githubusercontent.com/7059ad5f1a363f9098686c59d432f01d7330aed9d4b6c8111d985fd64cfc6c60/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f63756d656e746174696f6e2d6861636b5f626f6f6b2d6666303036362e737667)](https://central.hoa-project.net/Documentation/Library/Socket)[![Board](https://camo.githubusercontent.com/fd81654ba14b3aca3a713e1b471bc3fc3ba7b5bb3761ccffd6eea2e2ed1fa5ca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6f7267616e69736174696f6e2d626f6172642d6666303036362e737667)](https://waffle.io/hoaproject/socket)

This library provides an abstract layer to build safe, fast and modular clients and servers.

It represents a connection as a stream (please, see the [`Hoa\Stream`library](http://central.hoa-project.net/Resource/Library/Stream)) that is used to build clients and servers. A connection supports timeout, options, context, encryption, remote informations etc. Such a connection, along with an abstract connection handler, allows to embed and “merge” many connections inside the same processus side-by-side.

[Learn more](https://central.hoa-project.net/Documentation/Library/Socket).

Installation
------------

[](#installation)

With [Composer](https://getcomposer.org/), to include this library into your dependencies, you need to require [`hoa/socket`](https://packagist.org/packages/hoa/socket):

```
$ composer require hoa/socket '~1.0'
```

For more installation procedures, please read [the Source page](https://hoa-project.net/Source.html).

Testing
-------

[](#testing)

Before running the test suites, the development dependencies must be installed:

```
$ composer install
```

Then, to run all the test suites:

```
$ vendor/bin/hoa test:run
```

For more information, please read the [contributor guide](https://hoa-project.net/Literature/Contributor/Guide.html).

Quick usage
-----------

[](#quick-usage)

As a quick overview, we will look at creating a server and a client, and introduce the respective API.

### A connection behind

[](#a-connection-behind)

Both server and client extend a connection, namely the `Hoa\Socket\Connection\Connection` class, which is a stream represented by the [`Hoa\Stream` library](http://central.hoa-project.net/Resource/Library/Stream). This latter provides the common stream API whose the read and write methods (from `Hoa\Stream\IStream\In`, `Hoa\Stream\IStream\Out` and also `Hoa\Stream\IStream\Pathable`). Since it is also responsible of the connection, we are able to manipulate the underlying socket resource, the timeout, the different flags, the stream context, the encryption, the remote informations etc.

To start a connection, we will use the `connect` method (the constructor does not start the connection by itself). For a server, we will often prefer to use the `connectAndWait` method (see bellow). To stop a connection, most of the time, we will use the `disconnect` method.

A remote connection (a client for the server, a server for the client) is represented by a node: an object that holds several informations about the remote connection. The default node is `Hoa\Socket\Node` and can be easily extended. To use a new node, we have to call the `Hoa\Socket\Connection\Connection::setNodeName` method.

A connection needs a socket URI, represented by the `Hoa\Socket\Socket` class, to know where to connect. This latter represents an IPv4 or IPv6 address, a domain or a path (for Unix socket), along with the transport scheme (`tcp://`, `udp://` etc.) and the port.

### Manipulating a server or a client

[](#manipulating-a-server-or-a-client)

We will instanciate the `Hoa\Socket\Server` class and start a connection to `tcp://127.0.0.1:4242`. Then, to select active nodes, we will use the `Hoa\Socket\Connection\Connection::select` method that returns an iterator. Finally, we will read a line and write an uppercassed echo. Thus:

```
$server = new Hoa\Socket\Server('tcp://127.0.0.1:4242');
$server->connectAndWait();

while (true) {
    foreach ($server->select() as $node) {
        $line = $server->readLine();

        if (empty($line)) {
            $server->disconnect();
            continue;
        }

        echo '< ', $line, "\n";
        $server->writeLine(strtoupper($line));
    }
}
```

And then, with `telnet`:

```
$ telnet 127.0.0.1 4242
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
foobar
FOOBAR
hello world
HELLO WORLD
```

From the server, we will see:

```
< foobar
< hello world

```

To reproduce the same behavior with our own client, we will write (thanks to `Hoa\Console\Readline\Readline`, please see the [`Hoa\Console`library](http://central.hoa-project.net/Resource/Library/Console)):

```
$client = new Hoa\Socket\Client('tcp://127.0.0.1:4242');
$client->connect();

$readline = new Hoa\Console\Readline\Readline();

while (true) {
    $line = $readline->readLine('> ');

    if ('quit' === $line) {
        break;
    }

    $client->writeLine($line);

    echo '< ', $client->readLine(), "\n";
}
```

Finally:

```
$ php Client.php
> foobar
 hello world
 quit
```

### Handle servers and clients

[](#handle-servers-and-clients)

A connection has advanced operations but they are low-levels and not obvious. Moreover, there is repetitive and not so trivial tasks that we need often, such as broadcasting messages. The `Hoa\Socket\Connection\Handler` provides an easy way to create and embed a very flexible server or client. (A good and complete example is the [`Hoa\Websocket`library](http://central.hoa-project.net/Resource/Library/Websocket)).

We will focus on a server. A server has the magic `run` method that starts an infinite loop and make some computation on active nodes. This is basically the `while (true)` in our previous examples. In addition, we would like to easily send a message to a specific node, or send a message to all nodes except one. The `Hoa\Socket\Connection\Handler` class asks the user to implement only two methods: `_run` and `_send`, and provides the `run` method, along with `send`and `broadcast`. Then, we no longer need to start the connection or to take care about the implementation of different network topologies. All is managed by the handler. Thus:

```
class MyServer extends Hoa\Socket\Connection\Handler
{
    protected function _run (Hoa\Socket\Node $node)
    {
        $connection = $node->getConnection();
        $line       = $connection->readLine();

        if (empty($line)) {
            $connection->disconnect();
            return;
        }

        echo '< ', $line, "\n";
        $this->send(strtoupper($line));

        return;
    }

    protected function _send ($message, Hoa\Socket\Node $node)
    {
        return $node->getConnection()->writeLine($message);
    }
}
```

And then, all we need to do is:

```
$server = new MyServer(new Hoa\Socket\Server('tcp://127.0.0.1:4242'));
$server->run();
```

We see that the connection is embeded inside our server, and that all the logic has been moved inside the `_run` method. If we change the call to `send` by `broadcast`, we will see all connected clients receiving the message, something like:

```
        echo '< ', $line, "\n";
        $this->broadcast(strtoupper($line));
```

The `_send` method gives an implementation of “sending one message”, which is the basis. Because the `_run` method does not start an infinite loop, we have more flexibility (see the next section).

We can add listeners (please see the [`Hoa\Event`library](http://central.hoa-project.net/Resource/Library/Event)) to interact with the server, something like `$server->on('message', function ( … ) { … });` etc.

### Merging connections

[](#merging-connections)

Another huge advantage of using handlers is that they can be used inside a `Hoa\Socket\Connection\Group` object. The `run` method is an infinite loop, so we are not able to run two servers side-by-side in the same process. Fortunately, the `Hoa\Socket\Connection\Group` allows to “merge” connections (this is an underlying feature of `Hoa\Socket\Connection\Connection` but a group abstracts and manages all the complexity). Consequently, we are able to run several servers and clients together, inside the same processus, at the same time.

For example, we will run an instance of `Hoa\Irc\Client` (please, see the [`Hoa\Irc` library](http://central.hoa-project.net/Resource/Library/Irc)) with a `Hoa\Websocket\Server` (please, see the [`Hoa\Websocket`library](http://central.hoa-project.net/Resource/Library/Websocket): all messages received by the WebSocket server will be redirected on the IRC client. Thus:

```
$websocket = new Hoa\Websocket\Server(new Hoa\Socket\Server('tcp://…'));
$irc       = new Hoa\Irc\Client(new Hoa\Socket\Client('tcp://…'));
$group     = new Hoa\Socket\Connection\Group();
$group[]   = $websocket;
$group[]   = $irc;

$websocket->on(
    'message',
    function (Hoa\Event\Bucket $bucket) use ($irc) {
        $data = $bucket->getData();
        $irc->say($data['message']);

        return;
    }
);

// $irc->…

$group->run();
```

This is an illustration of the power provided by the `Hoa\Socket\Connection`classes.

Documentation
-------------

[](#documentation)

The [hack book of `Hoa\Socket`](https://central.hoa-project.net/Documentation/Library/Socket) contains detailed information about how to use this library and how it works.

To generate the documentation locally, execute the following commands:

```
$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open
```

More documentation can be found on the project's website: [hoa-project.net](https://hoa-project.net/).

Getting help
------------

[](#getting-help)

There are mainly two ways to get help:

- On the [`#hoaproject`](https://webchat.freenode.net/?channels=#hoaproject)IRC channel,
- On the forum at [users.hoa-project.net](https://users.hoa-project.net).

Contribution
------------

[](#contribution)

Do you want to contribute? Thanks! A detailed [contributor guide](https://hoa-project.net/Literature/Contributor/Guide.html) explains everything you need to know.

License
-------

[](#license)

Hoa is under the New BSD License (BSD-3-Clause). Please, see [`LICENSE`](https://hoa-project.net/LICENSE) for details.

Related projects
----------------

[](#related-projects)

The following projects are using this library:

- [PHP School](https://www.phpschool.io/), A revolutionary new way to learn PHP.

###  Health Score

46

—

FairBetter than 93% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity50

Moderate usage in the ecosystem

Community32

Small or concentrated contributor base

Maturity72

Established project with proven stability

 Bus Factor1

Top contributor holds 91.6% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~64 days

Recently: every ~115 days

Total

16

Last Release

3290d ago

Major Versions

0.15.09.08 → 1.16.01.142016-01-14

### Community

Maintainers

![](https://www.gravatar.com/avatar/a410060743cec0e0d8654661b726a7a25f5888f18059d4c942a8fd9a8128f0da?d=identicon)[Hoa](/maintainers/Hoa)

---

Top Contributors

[![Hywan](https://avatars.githubusercontent.com/u/946104?v=4)](https://github.com/Hywan "Hywan (164 commits)")[![shulard](https://avatars.githubusercontent.com/u/482993?v=4)](https://github.com/shulard "shulard (5 commits)")[![Pierozi](https://avatars.githubusercontent.com/u/5133487?v=4)](https://github.com/Pierozi "Pierozi (2 commits)")[![vonglasow](https://avatars.githubusercontent.com/u/1275202?v=4)](https://github.com/vonglasow "vonglasow (2 commits)")[![Metalaka](https://avatars.githubusercontent.com/u/5406767?v=4)](https://github.com/Metalaka "Metalaka (2 commits)")[![stephpy](https://avatars.githubusercontent.com/u/232744?v=4)](https://github.com/stephpy "stephpy (2 commits)")[![endel](https://avatars.githubusercontent.com/u/130494?v=4)](https://github.com/endel "endel (1 commits)")[![jubianchi](https://avatars.githubusercontent.com/u/327237?v=4)](https://github.com/jubianchi "jubianchi (1 commits)")

---

Tags

clienthoalibraryphpserversockettcpudpclientlibraryservertcpSocketnodeudp

### Embed Badge

![Health badge](/badges/hoa-socket/health.svg)

```
[![Health](https://phpackages.com/badges/hoa-socket/health.svg)](https://phpackages.com/packages/hoa-socket)
```

###  Alternatives

[clue/socket-raw

Simple and lightweight OOP wrapper for PHP's low-level sockets extension (ext-sockets).

35111.1M48](/packages/clue-socket-raw)[react/datagram

Event-driven UDP datagram socket client and server for ReactPHP

99759.5k36](/packages/react-datagram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)