Download the PHP package chipslays/porter without Composer

Porter 🤵‍

A simple PHP 8 websocket server and client wrapper over Workerman with events, channels and other stuff, can say this is a Socket IO alternative for PHP.

Note

Latest version 1.2 is production ready, maintenance only small features, fix bugs and has no breaking changes updates.

🧰 Installation

1. Install Porter via Composer:

2. Put javascript code in views:

3. All done.

Laravel integration can be found here.

👨‍💻 Usage

Server (PHP)

Simplest ping-pong server.

Run server.

Or run server in background as daemon process.

Client (Javascript)

Send ping event on established connection.

💡 Examples

Examples can be found here.

📚 Documentation

NOTE: The documentation may not contain the latest updates or may be out of date in places. See examples, code and comments on methods. The code is well documented.

Basics

Local development

On server with SSL

🔹 Server

Can be used anywhere as function server() or Server::getInstance().

boot(Worker $worker): self

Booting websocket server. It method init all needle classes inside.

Use this method instead of constructor.

setWorker(Worker $worker): void

Set worker instance.

setWorker(Worker $worker): void

Set worker instance.

getWorker(): Worker

Get worker instance.

addEvent(AbstractEvent|string $event): self

Add event class handler.

autoloadEvents(string $path, string|array $masks = ['*.php', '**/*.php']): void

Autoload all events inside passed path.

Note: Use it instead manual add events by addEvent method.

on(string $type, callable $handler): void

Note

Event $event class extends and have all methods & properties of AbstractEvent.

start(): void

Start server.

onConnected(callable $handler): void

Emitted when a socket connection is successfully established.

In this method available vars: $_GET, $_COOKIE, $_SERVER.

onDisconnected(callable $handler): void

Emitted when the other end of the socket sends a FIN packet.

NOTICE: On disconnect client connection will leave of all the channels where he was.

onError(callable $handler): void

Emitted when an error occurs with connection.

onStart(callable $handler): void

Emitted when worker processes start.

onStop(callable $handler): void

Emitted when worker processes stoped.

onReload(callable $handler): void

Emitted when worker processes get reload signal.

onRaw(callable $handler): void

Handle non event messages (raw data).

to(TcpConnection|Connection|array $connection, string $event, array $data = []): self

Send event to connection.

broadcast(string $event, array $data = [], array $excepts = []): void

Send event to all connections.

Yes, to all connections on server.

storage(): Storage

Getter for Storage class.

channels(): Channels

Getter for Channels class.

connection(int $connectionId): ?Connection

Get connection instance by id.

connections(): Collection[]

Get collection of all connections on server.

validator(): Validator

Create validator instance.

See documenation & examples how to use.

🔹 Channels

This is a convenient division of connected connections into channels.

One connection can consist of an unlimited number of channels.

Channels also support broadcasting and their own storage.

Channel can be access like:

create(string $id, array $data = []): Channel

Create new channel.

get(string $id): ?Channel

Get a channel.

Returns NULL if channel not exists.

all(): Channel[]

Get array of channels (Channel instances).

count(): int

Get count of channels.

delete(string $id): void

Delete channel.

exists(string $id): bool

Checks if given channel id exists already.

join(string $id, Connection|Connection[]|int[] $connections): Channel

Join or create and join to channel.

🔹 Channel

join(TcpConnection|Connection|array $connections): self

Join given connections to channel.

leave(TcpConnection|Connection $connection): self

Remove given connection from channel.

exists(TcpConnection|Connection|int $connection): bool

Checks if given connection exists in channel.

connections(): Connections

A array of connections in this channel. Key is a id of connection, and value is a instance of connection Connection.

broadcast(string $event, array $data = [], array $excepts = []): void

Send an event to all connection on this channel.

TcpConnection[]|Connection[]|int[] $excepts Connection instance or connection id.

For example, you need to send to all participants in the room except yourself, or other connections.

destroy(): void

Delete this channel from channels.

Lifehack for Channel

You can add channel to current user as property to $connection instance and get it anywhere.

Properties

$channel->data

Data is a simple implement of box for storage your data.

Data is a object of powerful chipslays/collection.

See documentation for more information how to manipulate this data.

NOTICE: All this data will be deleted when the server is restarted.

Two of simple-short examples:

🔹 Payload

The payload is the object that came from the client.

payload(string $key, mixed $default = null): mixed

Get value from data.

is(string|array $rule, string $key): bool

Validate payload data.

See documenation & examples how to use.

Properties

$payload->type

Is a id of event, for example, welcome message.

$payload->data

An object of values passed from the client.

Object of chipslays/collection.

See documentation for more information how to manipulate this data.

$payload->rules [protected]

Auto validate payload data on incoming event.

Available only in events as class.

🔹 Events

Events can be as a separate class or as an anonymous function.

Event class

Basic ping-pong example:

NOTICE: The event class must have a handle() method.

This method handles the event. You can also create other methods.

AbstractEvent

Properties

Each child class get following properties:

• Connection $connection - from whom the event came;
• Payload $payload - contain data from client;
• Server $server - server instance;
• Collection $data - short cut for payload data (as &link).;

Magic properties & methods.

If client pass in data channel_i_d with channel id or target_id with id of connection, we got a magic properties and methods.

Methods

to(TcpConnection|Connection|array $connection, string $event, array $data = []): self

Send event to connection.

reply(string $event, array $data = []): ?bool

Reply event to incoming connection.

To reply with the current type, pass only the $data parameter.

On front-end:

On back-end:

raw(string $string): bool|null

Send raw data to connection. Not a event object.

broadcast(string $event, array $data = [], TcpConnection|Connection|array $excepts = []): void

Send event to all connections.

Yes, to all connections on server.

Send event to all except for the connection from which the event came.

validate(): bool

Validate payload data.

Pass custom rules. Default use $rules class attribute.

Returns false if has errors.

hasErrors(): bool

Returns true if has errors on validate payload data.

payload(string $key, mixed $default = null): mixed

Yet another short cut for payload data.

Anonymous function

In anonymous function instead of $this, use $event.

🔹 TcpConnection|Connection $connection

It is a global object, changing in one place, it will contain the changed data in another place.

This object has already predefined properties:

See all $connection methods here.

You can set different properties, functions to this object.

Custom property channels

List of methods Porter\Connection\Channels

NOTICE: On disconnect client connection will leave of all the channels where he was.

🔹 Client (PHP)

Simple implementation of client.

See basic example of client here.

__construct(string $host, array $context = [])

Create client.

setWorker(Worker $worker): void

Set worker.

NOTICE: Worker instance auto init in constructor. Use this method if you need to define worker with specific settings.

getWorker(): Worker

Get worker.

send(string $type, array $data = []): ?bool

Send event to server.

raw(string $payload): ?bool

Send raw payload to server.

onConnected(callable $handler): void

Emitted when a socket connection is successfully established.

onDisconnected(callable $handler): void

Emitted when the server sends a FIN packet.

onError(callable $handler): void

Emitted when an error occurs with connection.

onRaw(callable $handler): void

Handle non event messages (raw data).

on(string $type, callable $handler): void

Event handler as callable.

listen(): void

Connect to server and listen.

🔹 Storage

Storage is a part of server, all data stored in flat files.

To get started you need set a path where files will be stored.

You can get access to storage like property or method:

NOTICE: Set path only after if you booting server by (server()->boot($worker) method, Storage::class can use anywhere and before booting server.

WARNING: If you not provide path or an incorrect path, data will be stored in RAM. After server restart you lose your data.

Storage::class

load(?string $path = null): self

put(string $key, mixed $value): void

get(string $key, mixed $default = null): mixed

remove(string ...$keys): self

has(string $key): bool

filename(): string

Returns path to file.

🔹 Helpers (functions)

server(): Server

worker(): Worker

channel(string $id, string|array $key = null, mixed $default = null): mixed

💡 See all helpers here.

🔹 Mappable methods (Macros)

You can extend the class and map your own methods on the fly..

Basic method:

As singletone method:

🔹 Front-end

There is also a small class for working with websockets on the client side.

Used by

• naplenke.online — The largest online cinema in Russia. Watching movies together.

Credits

• Chipslays
• Workerman by walkor
• All contributors

License

MIT