{"id":13792462,"url":"https://github.com/clue/socket-raw","last_synced_at":"2025-04-06T19:13:10.127Z","repository":{"id":42192727,"uuid":"9278081","full_name":"clue/socket-raw","owner":"clue","description":"Simple and lightweight OOP wrapper for PHP's low-level sockets extension (ext-sockets)","archived":false,"fork":false,"pushed_at":"2022-04-14T14:59:12.000Z","size":132,"stargazers_count":331,"open_issues_count":0,"forks_count":48,"subscribers_count":19,"default_branch":"1.x","last_synced_at":"2024-07-09T08:42:34.204Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clue.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"clue","custom":"https://clue.engineering/support"}},"created_at":"2013-04-07T14:52:49.000Z","updated_at":"2024-07-02T22:31:21.000Z","dependencies_parsed_at":"2022-09-05T13:30:40.834Z","dependency_job_id":null,"html_url":"https://github.com/clue/socket-raw","commit_stats":null,"previous_names":["clue/php-socket-raw"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clue%2Fsocket-raw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clue%2Fsocket-raw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clue%2Fsocket-raw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clue%2Fsocket-raw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clue","download_url":"https://codeload.github.com/clue/socket-raw/tar.gz/refs/heads/1.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247535519,"owners_count":20954576,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T22:01:12.493Z","updated_at":"2025-04-06T19:13:10.105Z","avatar_url":"https://github.com/clue.png","language":"PHP","funding_links":["https://github.com/sponsors/clue","https://clue.engineering/support"],"categories":["类库"],"sub_categories":["未归类"],"readme":"# clue/socket-raw\n\n[![CI status](https://github.com/clue/socket-raw/actions/workflows/ci.yml/badge.svg)](https://github.com/clue/socket-raw/actions)\n[![installs on Packagist](https://img.shields.io/packagist/dt/clue/socket-raw?color=blue\u0026label=installs%20on%20Packagist)](https://packagist.org/packages/clue/socket-raw)\n\nSimple and lightweight OOP wrapper for PHP's low-level sockets extension (ext-sockets).\n\nPHP 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).\nWhile the former has been a huge step forward in generalizing various streaming resources,\nit lacks some of the advanced features of the original and much more low-level socket API.\nThis lightweight library exposes this socket API in a modern way by providing a thin wrapper around the underlying API.\n\n* **Full socket API** -\n  It exposes the whole [socket API](https://www.php.net/manual/en/ref.sockets.php) through a *sane* object-oriented interface.\n  Provides convenience methods for common operations as well as exposing all underlying methods and options.\n* **Fluent interface** -\n  Uses a fluent interface so you can easily chain method calls.\n  Error conditions will be signalled using `Exception`s instead of relying on cumbersome return codes.\n* **Lightweight, SOLID design** -\n  Provides a thin abstraction that is [*just good enough*](https://en.wikipedia.org/wiki/Principle_of_good_enough)\n  and does not get in your way.\n  This library is merely a very thin wrapper and has no other external dependencies.\n* **Good test coverage** -\n  Comes with an automated test suite and is regularly tested in the *real world*.\n\n**Table of contents**\n\n* [Support us](#support-us)\n* [Quickstart example](#quickstart-example)\n* [Usage](#usage)\n  * [Factory](#factory)\n    * [createClient()](#createclient)\n    * [createServer()](#createserver)\n    * [create*()](#create)\n  * [Socket](#socket)\n    * [Methods](#methods)\n      * [Data I/O](#data-io)\n      * [Unconnected I/O](#unconnected-io)\n      * [Non-blocking (async) I/O](#non-blocking-async-io)\n      * [Connection handling](#connection-handling)\n* [Install](#install)\n* [Tests](#tests)\n* [License](#license)\n\n## Support us\n\nWe invest a lot of time developing, maintaining and updating our awesome\nopen-source projects. You can help us sustain this high-quality of our work by\n[becoming a sponsor on GitHub](https://github.com/sponsors/clue). Sponsors get\nnumerous benefits in return, see our [sponsoring page](https://github.com/sponsors/clue)\nfor details.\n\nLet's take these projects to the next level together! 🚀\n\n## Quickstart example\n\nOnce [installed](#install), you can use the following example to send and receive HTTP messages:\n\n```php\n$factory = new \\Socket\\Raw\\Factory();\n\n$socket = $factory-\u003ecreateClient('www.google.com:80');\necho 'Connected to ' . $socket-\u003egetPeerName() . PHP_EOL;\n\n// send simple HTTP request to remote side\n$socket-\u003ewrite(\"GET / HTTP/1.1\\r\\n\\Host: www.google.com\\r\\n\\r\\n\");\n\n// receive and dump HTTP response\nvar_dump($socket-\u003eread(8192));\n\n$socket-\u003eclose();\n```\n\nSee also the [examples](examples).\n\n## Usage\n\n### Factory\n\nAs shown in the [quickstart example](#quickstart-example), this library uses a `Factory` pattern\nas a simple API to [`socket_create()`](https://www.php.net/manual/en/function.socket-create.php).\nIt provides simple access to creating TCP, UDP, UNIX, UDG and ICMP protocol sockets and supports both IPv4 and IPv6 addressing.\n\n```php\n$factory = new \\Socket\\Raw\\Factory();\n```\n\n#### createClient()\n\nThe `createClient(string $address, null|float $timeout): Socket` method is\nthe most convenient method for creating connected client sockets\n(similar to how [`fsockopen()`](https://www.php.net/manual/en/function.fsockopen.php) or\n[`stream_socket_client()`](https://www.php.net/manual/en/function.stream-socket-client.php) work).\n\n```php\n// establish a TCP/IP stream connection socket to www.google.com on port 80\n$socket = $factory-\u003ecreateClient('tcp://www.google.com:80');\n\n// same as above, as scheme defaults to TCP\n$socket = $factory-\u003ecreateClient('www.google.com:80');\n\n// same as above, but wait no longer than 2.5s for connection\n$socket = $factory-\u003ecreateClient('www.google.com:80', 2.5);\n\n// create connectionless UDP/IP datagram socket connected to google's DNS\n$socket = $factory-\u003ecreateClient('udp://8.8.8.8:53');\n\n// establish TCP/IPv6 stream connection socket to localhost on port 1337\n$socket = $factory-\u003ecreateClient('tcp://[::1]:1337');\n\n// connect to local Unix stream socket path\n$socket = $factory-\u003ecreateClient('unix:///tmp/daemon.sock');\n\n// create Unix datagram socket\n$socket = $factory-\u003ecreateClient('udg:///tmp/udg.socket');\n\n// create a raw low-level ICMP socket (requires root!)\n$socket = $factory-\u003ecreateClient('icmp://192.168.0.1');\n```\n\n#### createServer()\n\nThe `createServer($address)` method can be used to create a server side (listening) socket bound to specific address/path\n(similar to how [`stream_socket_server()`](https://www.php.net/manual/en/function.stream-socket-server.php) works).\nIt accepts the same addressing scheme as the [`createClient()`](#createclient) method.\n\n```php\n// create a TCP/IP stream connection socket server on port 1337\n$socket = $factory-\u003ecreateServer('tcp://localhost:1337');\n\n// create a UDP/IPv6 datagram socket server on port 1337\n$socket = $factory-\u003ecreateServer('udp://[::1]:1337');\n```\n\n#### create*()\n\nLess commonly used, the `Factory` provides access to creating (unconnected) sockets for various socket types:\n\n```php\n$socket = $factory-\u003ecreateTcp4();\n$socket = $factory-\u003ecreateTcp6();\n\n$socket = $factory-\u003ecreateUdp4();\n$socket = $factory-\u003ecreateUdp6();\n\n$socket = $factory-\u003ecreateUnix();\n$socket = $factory-\u003ecreateUdg();\n\n$socket = $factory-\u003ecreateIcmp4();\n$socket = $factory-\u003ecreateIcmp6();\n```\n\nYou can also create arbitrary socket protocol types through the underlying mechanism:\n\n```php\n$factory-\u003ecreate($family, $type, $protocol);\n```\n\n### Socket\n\nAs 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.\n\nThe recommended way to create a `Socket` instance is via the above [`Factory`](#factory).\n\n#### Methods\n\nAll low-level socket operations are available as methods on the `Socket` class.\n\nYou 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.\n\n##### Data I/O:\n\n```\n$socket-\u003ewrite('data');\n$data = $socket-\u003eread(8192);\n```\n\n##### Unconnected I/O:\n\n```\n$socket-\u003esendTo('data', $flags, $remote);\n$data = $socket-\u003ercvFrom(8192, $flags, $remote);\n```\n\n##### Non-blocking (async) I/O:\n\n```\n$socket-\u003esetBlocking(false);\n$socket-\u003eselectRead();\n$socket-\u003eselectWrite();\n```\n\n##### Connection handling:\n\n```php\n$client = $socket-\u003eaccept();\n$socket-\u003ebind($address);\n$socket-\u003econnect($address);\n$socket-\u003eshutdown();\n$socket-\u003eclose();\n```\n\n## Install\n\nThe recommended way to install this library is [through Composer](https://getcomposer.org/).\n[New to Composer?](https://getcomposer.org/doc/00-intro.md)\n\nThis project follows [SemVer](https://semver.org/).\nThis will install the latest supported version:\n\n```bash\ncomposer require clue/socket-raw:^1.6\n```\n\nSee also the [CHANGELOG](CHANGELOG.md) for details about version upgrades.\n\nThis project aims to run on any platform and thus does not require any PHP\nextensions besides `ext-sockets` and supports running on legacy PHP 5.3 through\ncurrent PHP 8+.\nIt's *highly recommended to use the latest supported PHP version* for this project.\n\n## Tests\n\nTo run the test suite, you first need to clone this repo and then install all\ndependencies [through Composer](https://getcomposer.org/):\n\n```bash\ncomposer install\n```\n\nTo run the test suite, go to the project root and run:\n\n```bash\nvendor/bin/phpunit\n```\n\nNote that the test suite contains tests for ICMP sockets which require root\naccess on Unix/Linux systems. Therefor some tests will be skipped unless you run\nthe following command to execute the full test suite:\n\n```bash\nsudo vendor/bin/phpunit\n```\n\nThe test suite also contains a number of functional integration tests that rely\non a stable internet connection.\nIf you do not want to run these, they can simply be skipped like this:\n\n```bash\nvendor/bin/phpunit --exclude-group internet\n```\n\n## License\n\nThis project is released under the permissive [MIT license](LICENSE).\n\n\u003e Did you know that I offer custom development services and issuing invoices for\n  sponsorships of releases and for contributions? Contact me (@clue) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclue%2Fsocket-raw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclue%2Fsocket-raw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclue%2Fsocket-raw/lists"}