Debian Codegraph @

vendor/clue/socket-raw/README.md

raw
1 # clue/socket-raw
2
3 [![CI status](https://github.com/clue/socket-raw/actions/workflows/ci.yml/badge.svg)](https://github.com/clue/socket-raw/actions)
4 [![installs on Packagist](https://img.shields.io/packagist/dt/clue/socket-raw?color=blue&label=installs%20on%20Packagist)](https://packagist.org/packages/clue/socket-raw)
5
6 Simple and lightweight OOP wrapper for PHP's low-level sockets extension (ext-sockets).
7
8 PHP offers two networking APIs, the newer [streams API](https://www.php.net/manual/en/book.stream.php) and the older [socket API](https://www.php.net/manual/en/ref.sockets.php).
9 While the former has been a huge step forward in generalizing various streaming resources,
10 it lacks some of the advanced features of the original and much more low-level socket API.
11 This lightweight library exposes this socket API in a modern way by providing a thin wrapper around the underlying API.
12
13 * **Full socket API** -
14 It exposes the whole [socket API](https://www.php.net/manual/en/ref.sockets.php) through a *sane* object-oriented interface.
15 Provides convenience methods for common operations as well as exposing all underlying methods and options.
16 * **Fluent interface** -
17 Uses a fluent interface so you can easily chain method calls.
18 Error conditions will be signalled using `Exception`s instead of relying on cumbersome return codes.
19 * **Lightweight, SOLID design** -
20 Provides a thin abstraction that is [*just good enough*](https://en.wikipedia.org/wiki/Principle_of_good_enough)
21 and does not get in your way.
22 This library is merely a very thin wrapper and has no other external dependencies.
23 * **Good test coverage** -
24 Comes with an automated test suite and is regularly tested in the *real world*.
25
26 **Table of contents**
27
28 * [Support us](#support-us)
29 * [Quickstart example](#quickstart-example)
30 * [Usage](#usage)
31 * [Factory](#factory)
32 * [createClient()](#createclient)
33 * [createServer()](#createserver)
34 * [create*()](#create)
35 * [Socket](#socket)
36 * [Methods](#methods)
37 * [Data I/O](#data-io)
38 * [Unconnected I/O](#unconnected-io)
39 * [Non-blocking (async) I/O](#non-blocking-async-io)
40 * [Connection handling](#connection-handling)
41 * [Install](#install)
42 * [Tests](#tests)
43 * [License](#license)
44
45 ## Support us
46
47 We invest a lot of time developing, maintaining and updating our awesome
48 open-source projects. You can help us sustain this high-quality of our work by
49 [becoming a sponsor on GitHub](https://github.com/sponsors/clue). Sponsors get
50 numerous benefits in return, see our [sponsoring page](https://github.com/sponsors/clue)
51 for details.
52
53 Let's take these projects to the next level together! 🚀
54
55 ## Quickstart example
56
57 Once [installed](#install), you can use the following example to send and receive HTTP messages:
58
59 ```php
60 $factory = new \Socket\Raw\Factory();
61
62 $socket = $factory->createClient('www.google.com:80');
63 echo 'Connected to ' . $socket->getPeerName() . PHP_EOL;
64
65 // send simple HTTP request to remote side
66 $socket->write("GET / HTTP/1.1\r\n\Host: www.google.com\r\n\r\n");
67
68 // receive and dump HTTP response
69 var_dump($socket->read(8192));
70
71 $socket->close();
72 ```
73
74 See also the [examples](examples).
75
76 ## Usage
77
78 ### Factory
79
80 As shown in the [quickstart example](#quickstart-example), this library uses a `Factory` pattern
81 as a simple API to [`socket_create()`](https://www.php.net/manual/en/function.socket-create.php).
82 It provides simple access to creating TCP, UDP, UNIX, UDG and ICMP protocol sockets and supports both IPv4 and IPv6 addressing.
83
84 ```php
85 $factory = new \Socket\Raw\Factory();
86 ```
87
88 #### createClient()
89
90 The `createClient(string $address, null|float $timeout): Socket` method is
91 the most convenient method for creating connected client sockets
92 (similar to how [`fsockopen()`](https://www.php.net/manual/en/function.fsockopen.php) or
93 [`stream_socket_client()`](https://www.php.net/manual/en/function.stream-socket-client.php) work).
94
95 ```php
96 // establish a TCP/IP stream connection socket to www.google.com on port 80
97 $socket = $factory->createClient('tcp://www.google.com:80');
98
99 // same as above, as scheme defaults to TCP
100 $socket = $factory->createClient('www.google.com:80');
101
102 // same as above, but wait no longer than 2.5s for connection
103 $socket = $factory->createClient('www.google.com:80', 2.5);
104
105 // create connectionless UDP/IP datagram socket connected to google's DNS
106 $socket = $factory->createClient('udp://8.8.8.8:53');
107
108 // establish TCP/IPv6 stream connection socket to localhost on port 1337
109 $socket = $factory->createClient('tcp://[::1]:1337');
110
111 // connect to local Unix stream socket path
112 $socket = $factory->createClient('unix:///tmp/daemon.sock');
113
114 // create Unix datagram socket
115 $socket = $factory->createClient('udg:///tmp/udg.socket');
116
117 // create a raw low-level ICMP socket (requires root!)
118 $socket = $factory->createClient('icmp://192.168.0.1');
119 ```
120
121 #### createServer()
122
123 The `createServer($address)` method can be used to create a server side (listening) socket bound to specific address/path
124 (similar to how [`stream_socket_server()`](https://www.php.net/manual/en/function.stream-socket-server.php) works).
125 It accepts the same addressing scheme as the [`createClient()`](#createclient) method.
126
127 ```php
128 // create a TCP/IP stream connection socket server on port 1337
129 $socket = $factory->createServer('tcp://localhost:1337');
130
131 // create a UDP/IPv6 datagram socket server on port 1337
132 $socket = $factory->createServer('udp://[::1]:1337');
133 ```
134
135 #### create*()
136
137 Less commonly used, the `Factory` provides access to creating (unconnected) sockets for various socket types:
138
139 ```php
140 $socket = $factory->createTcp4();
141 $socket = $factory->createTcp6();
142
143 $socket = $factory->createUdp4();
144 $socket = $factory->createUdp6();
145
146 $socket = $factory->createUnix();
147 $socket = $factory->createUdg();
148
149 $socket = $factory->createIcmp4();
150 $socket = $factory->createIcmp6();
151 ```
152
153 You can also create arbitrary socket protocol types through the underlying mechanism:
154
155 ```php
156 $factory->create($family, $type, $protocol);
157 ```
158
159 ### Socket
160
161 As discussed above, the `Socket` class is merely an object-oriented wrapper around a socket resource. As such, it helps if you're familar with socket programming in general.
162
163 The recommended way to create a `Socket` instance is via the above [`Factory`](#factory).
164
165 #### Methods
166
167 All low-level socket operations are available as methods on the `Socket` class.
168
169 You can refer to PHP's fairly good [socket API documentation](https://www.php.net/manual/en/ref.sockets.php) or the docblock comments in the [`Socket` class](src/Socket.php) to get you started.
170
171 ##### Data I/O:
172
173 ```
174 $socket->write('data');
175 $data = $socket->read(8192);
176 ```
177
178 ##### Unconnected I/O:
179
180 ```
181 $socket->sendTo('data', $flags, $remote);
182 $data = $socket->rcvFrom(8192, $flags, $remote);
183 ```
184
185 ##### Non-blocking (async) I/O:
186
187 ```
188 $socket->setBlocking(false);
189 $socket->selectRead();
190 $socket->selectWrite();
191 ```
192
193 ##### Connection handling:
194
195 ```php
196 $client = $socket->accept();
197 $socket->bind($address);
198 $socket->connect($address);
199 $socket->shutdown();
200 $socket->close();
201 ```
202
203 ## Install
204
205 The recommended way to install this library is [through Composer](https://getcomposer.org/).
206 [New to Composer?](https://getcomposer.org/doc/00-intro.md)
207
208 This project follows [SemVer](https://semver.org/).
209 This will install the latest supported version:
210
211 ```bash
212 $ composer require clue/socket-raw:^1.6
213 ```
214
215 See also the [CHANGELOG](CHANGELOG.md) for details about version upgrades.
216
217 This project aims to run on any platform and thus does not require any PHP
218 extensions besides `ext-sockets` and supports running on legacy PHP 5.3 through
219 current PHP 8+.
220 It's *highly recommended to use the latest supported PHP version* for this project.
221
222 ## Tests
223
224 To run the test suite, you first need to clone this repo and then install all
225 dependencies [through Composer](https://getcomposer.org/):
226
227 ```bash
228 $ composer install
229 ```
230
231 To run the test suite, go to the project root and run:
232
233 ```bash
234 $ vendor/bin/phpunit
235 ```
236
237 Note that the test suite contains tests for ICMP sockets which require root
238 access on Unix/Linux systems. Therefor some tests will be skipped unless you run
239 the following command to execute the full test suite:
240
241 ```bash
242 $ sudo vendor/bin/phpunit
243 ```
244
245 The test suite also contains a number of functional integration tests that rely
246 on a stable internet connection.
247 If you do not want to run these, they can simply be skipped like this:
248
249 ```bash
250 $ vendor/bin/phpunit --exclude-group internet
251 ```
252
253 ## License
254
255 This project is released under the permissive [MIT license](LICENSE).
256
257 > Did you know that I offer custom development services and issuing invoices for
258 sponsorships of releases and for contributions? Contact me (@clue) for details.