WebSockets are a ubiquitous tool for building real-time experiences for users. They provide a persistent, bidirectional connection between a client and a server. For example, say the frontend of your app needs to stay up-to-date within seconds of your backend to do things like deliver notifications, status updates, etc. You may have implemented this as a periodic check, or poll, of the backend via some API like REST or GraphQL. Now that you have more users, and/or your processes have become more complex, these requests can start to weigh on your infrastructure capacity. That’s a problem that WebSockets can help solve.
\nLaravel and its ecosystem play a significant role in our stack at Knack, and recently we embarked on a new WebSocket server implementation which would work closely with our Laravel-based core API. For the uninitiated, Laravel is a popular PHP framework and ecosystem that provides a rich set of tools and features for building modern web applications. We decided to use the swooletw/laravel-swoole library to build our server-side implementation of a custom subprotocol and I had the opportunity to document some of my experiences along the way. I’ll show how to get started with the library, provide some background information, some caveats to consider, and drop a few tips. Let’s get started!
\nFirst, we are working with the assumption that you want, or need, to host your own WebSocket server, and that you want to do so in PHP. With a stateful protocol like WebSockets we need to be able to run PHP concurrently. There are basically two different approaches: language-level and extension-level.
\nLanguage-level libraries and frameworks implement concurrency in pure PHP. Examples include AMPHP and ReactPHP. In contrast, extensions are written in a lower-level language, typically C/C++, and expose APIs at the PHP-level to access the extension-level functionality. Swoole and OpenSwoole are examples of PHP extensions. In short, Swoole is an event-driven, asynchronous, multithreaded framework that makes it easy to build performant, concurrent servers.
\nNow let’s evaluate pre-packaged WebSocket Server solutions that easily plug into a Laravel app. On the language-level side we have the seemingly most popular choice: the beyondcode/laravel-websockets, a package by Beyond Code. It is built on Ratchet (which is built on ReactPHP), has a Pusher protocol implementation, and plugs well into the Laravel framework’s broadcasting API. While this supports a lot of use cases and does so in a familiar “Laravel way” it is not very flexible when you need something like a custom subprotocol implementation, and it is inherently limited in performance due to being built on a PHP server core rather than a C/C++ one.
\nOn the extension-level side we have two libraries that are built around Swoole: swooletw/laravel-swoole and hhsxv5/laravel-s. They are both established packages with a wide contributor base, but my colleagues and I ultimately concluded that the sandbox and safety features within laravel-swoole were a bit more mature and reliable in our testing.
\nThere are a few blog posts out there on getting started with laravel-s but not as many for laravel-swoole, so I felt particularly motivated to write and publish this article. The laravel-swoole default WebSocket implementation is built with Socket.io in mind, where laravel-s is a bit more agnostic in its implementation. Both packages have some feature overlap but some differences as well. I would consider both of them for your project and evaluate the best fit!
\nFirst, let’s install either Swoole or OpenSwoole. I’ll be using Swoole for this example. Be sure to enable support for WebSockets on installation when prompted like so:
\nNext, require the laravel-swoole package and publish its config files: Here we’ll also want to adjust the config to enable the WebSocket server by default. Now, for this basic example we’ll just have our handlers defined inline as closures in the websockets “routes” definition. For anything that is more than a simple exploration I would recommend creating controllers or Laravel Actions to store the handler code. Now we can test it out! Let’s start the Swoole server and test things out. Note: You will need to disable Xdebug before you can run any Swoole code. If you skip this step your terminal will be overwhelmed with warning logs when you run this next command and things might not behave properly. If you expect to be doing a lot of Swoole development then you may want to configure a tool or script to enable or disable loading the Xdebug extension. For macOS there’s an open source tool to add a toggle button in the menu bar called xDebugToggler. Try navigating to If you’re wondering what those 1-2 digit numbers prefixing the server messages are, those are Socket.io packet type encodings. You can remove these and adjust anything about frame parsing by creating your own implementation of Let’s send a We now have a WebSocket server and a way to authenticate connections! This example is very basic, but I hope it gives a background to build something great with. If you end up using a Swoole-based solution for your WebSocket server, why not serve HTTP requests using Swoole as well? Laravel’s request lifecycle by default is actually pretty redundant: for each incoming request that your Laravel app handles it needs to be fully bootstrapped every time: framework, service providers and all. There is a first-party solution to this: Laravel Octane, which uses your choice of Swoole (or OpenSwoole) or RoadRunner to provide a relatively easy way to serve many more requests by booting and loading the application into memory. Laravel Octane with RoadRunner is very likely to be a drop-in replacement for Nginx/PHP FPM for your Laravel app if you’d rather not add Swoole to your stack. Either way, it could be an easy win to dramatically increase your throughput for typical HTTP server needs using Laravel Octane, laravel-swoole, laravel-s, or another similar solution. Be sure to choose your room driver, which associates WebSocket connections with users as well as membership in channels, appropriately for your use case. By default, the library will use a Swoole table to store these records. Swoole tables are an incredibly performant data store compared to Redis, as Cerwyn Cahyono concluded in May 2021. One consideration however is horizontal scaling: if you have more than one WebSocket server behind a load balancer, for instance, you need to consider that Swoole tables are only accessible by the Swoole server process and its forks. If you need to have a common record among all of your WebSocket server instances with laravel-swoole then you may want to consider the provided Redis driver ( You may also find that you’d like to have middleware for all incoming WebSocket messages. If all you need to do is interact with parts of the Frame then you can add this handling in a custom handler or parser. These are defined in If you have a system where a Swoole WebSocket server stands alongside other pieces like an HTTP server, queue worker, etc. then you will need to implement some kind of global pub/sub infrastructure that coordinates between the Swoole WebSocket server and everything else. Redis is one way to fill that need. You could have an async Redis client boot with the Swoole server and When installing the Swoole extension on both ARM64 and x64 macOS machines I’ve run into a few issues and wanted to share how I resolved them. If you get this error when installing Swoole then you need to be sure you have Then you can use the Brew CLI to grep the location of the This guide doesn’t require building Swoole with OpenSSL support, but if you do you may need to set your OpenSSL directory during the build config. You can do so by first ensuring that you have OpenSSL installed locally, on macOS you can also do this using Brew: Then you can once again use the Brew CLI to get your OpenSSL directory and pass it in during the extension build configuration, right after executing Be sure to pay attention to the For me this has been Firecamp, but I have gotten frustrated with the bugs and poor performance of the app. It has a lot of potential, so I’m definitely going to keep watching it! Insomnia just added WebSocket support, but it is still immature and lacking features. As of Jan 2023 I recommend using Postman, though note that even for them WebSockets support is somewhat of a beta. Be sure to implement some kind of heartbeat function for persistent WebSocket connections. It’s a good general practice, and helps when you have or want infrastructure configurations that close inactive connections. With many subprotocols the heartbeat is client-initiated. There are many patterns for authenticating WebSocket connections, but can be categorized as either during the initial connection request (authentication-on-connection) or afterwards within the established connection (authentication-after-connection). During the initial connection request the two most common approaches are to either use a cookie, or a token in the header or body. Typically, with the authentication-on-connection approach the connection is closed by the server if the authentication check fails. With the authentication-after-connection approach typically servers have a timeout which closes connections that don’t authenticate within a given timeout. At Knack, we created a WebSocket backend that implemented the graphql-transport-ws subprotocol which frontend library enisdenjo/graphql-ws supports. For reference, laravel-swoole is configured by default for authentication and other middleware to be run on the initial connection request. While this is a valid approach, my impression is that the dominant WebSocket authentication pattern is to support authentication-after-connection. For this guide I implemented an authentication-after-connection flow as a barebones custom subprotocol. Before proceeding with your project be sure to consider what kinds of clients will be connecting to your WebSocket server and choose your approach accordingly. This article has been cross-posted on my personal blogcomposer require swooletw/laravel-swoole\nphp artisan vendor:publish --tag=laravel-swoole'websocket' => [\n 'enabled' => env('SWOOLE_HTTP_WEBSOCKET', true),\n],<?php\n\ndeclare(strict_types=1);\n\nuse App\\Models\\User;\nuse Laravel\\Sanctum\\PersonalAccessToken;\nuse SwooleTW\\Http\\Websocket\\Facades\\Websocket;\n\nWebsocket::on('whoami', function (SwooleTW\\Http\\Websocket\\Websocket $websocket) {\n $websocket->emit(\n 'message',\n $websocket->getUserId() === null\n ? 'You are not authenticated'\n : \"Your userID is {$websocket->getUserId()}\"\n );\n});\n\nWebsocket::on('login', function (SwooleTW\\Http\\Websocket\\Websocket $websocket, mixed $data) {\n if (is_string($data)) {\n $tokenInstance = PersonalAccessToken::findToken($data);\n\n if (\n $tokenInstance instanceof PersonalAccessToken &&\n $tokenInstance->tokenable instanceof User\n ) {\n $websocket->loginUsing($tokenInstance->tokenable);\n $websocket->emit('message', $tokenInstance);\n }\n }\n});php artisan swoole:http starthttp://127.0.0.1:1215 and seeing if you are able to register and login just like if you were to run php artisan serve. From there, head to the API Tokens section:\\SwooleTW\\Http\\Websocket\\Parser.whoami payload using this JSON:[\n \"whoami\"\n]Appendix
\nNotes on using Swoole and laravel-swoole
\nTry Using Swoole (or RoadRunner) to serve your app
\nChoosing a WebSocket Room Driver
\n\\SwooleTW\\Http\\Websocket\\Rooms\\RedisRoom), or creating your own implementation. Be sure to add a prefix unique to the server for all records, that way you don’t end up sending a message intended for one WebSocket connection on Server A to another, unrelated WebSocket connection on Server B.Implementing middleware for WebSocket frames/messages
\nconfig/swoole_websocket.php. If you need to get the user ID and interact with a WebSocket instead then you’ll have to override and extend the \\SwooleTW\\Http\\Concerns\\InteractsWithWebsocket trait to directly modify the Swoole onMessage handler.Adding Swoole to an existing stack/system
\nSUBSCRIBE to a given channel. The client could listen for a JSON payload which could simply have a user ID and data to emit to the authenticated WebSocket connection. That way, you could issue WebSocket messages from non-Swoole contexts by simply PUBLISHing the JSON payload to the corresponding channel. This does have the added overhead of having to establish a Redis connection for each emit from a non-Swoole context, but you get the flexibility of cooperating well with your existing system.Troubleshooting installation of Swoole extension
\nfatal error: ‘pcre2.h’ file not found
\npcre2 installed. On macOS, you can do this using Brew:brew install pcre2pcre2.h file and link it under your current PHP version’s include/php/ext/pcre/ directory.brew list pcre2 | grep 'pcre2\\.h$'\n\nln -s /opt/homebrew/Cellar/pcre2/xx.yy/include/pcre2.h /opt/homebrew/Cellar/php@x.y/x.y.z/include/php/ext/pcre/pcre2.hfatal error: ‘openssl/ssl.h’ file not found
\nbrew install opensslpecl install. When prompted to enable OpenSSL support, type out “yes” and then add the --with-openssl-dir flag inline like so:brew --prefix openssl\npecl install swoole\n\n\nenable openssl support? [no] : yes --with-openssl-dir=/opt/homebrew/opt/openssl@3Notes on WebSockets
\nSubprotocol gotcha
\nSec-WebSocket-Protocol HTTP header on the initial connection request. If the client request specifies a protocol in the header and the server doesn’t respond with that protocol, or any, then some browsers like Chrome will just drop the connection, which technically follows the WebSocket spec more closely, and others like Firefox and Safari will connect without hesitation.Which WebSocket dev client to use?
\nGive your WebSocket server a heart(beat)
\nAuthentication Patterns
\n