The right way to arrange Laravel WebSockets on a subdomain

WebSockets are a necessary a part of many fashionable internet purposes. With WebSockets, you may create purposes that replace in real-time with out the necessity to reload the web page or frequently ballot the server for adjustments.

Laravel helps two server-side broadcasting drivers out of the field: Pusher and Ably. Whereas these two options could also be simpler to arrange and may present further functionalities, they’re each business options. This makes them unideal in case you’re on a good funds or in case you’re merely searching for an open supply answer.

Laravel WebSockets is a superb open supply various. It means that you can simply add WebSocket help to your Laravel >5.7 software. It comes with a debug dashboard and real-time statistics, amongst different options.

On this tutorial, we’re going to talk about learn how to arrange Laravel WebSockets on a subdomain. Particularly, we’ll go over the next subjects:

The connection between Laravel WebSockets and Pusher

Earlier than we start studying learn how to arrange and use Laravel WebSockets on a subdomain, let’s go over some background info on the connection between Laravel WebSockets and Pusher to forestall any confusion.

When utilizing Laravel WebSockets, you might be alleged to set Laravel’s BROADCAST_DRIVER configuration to pusher. It is best to alsoset different pusher configurations, like PUSHER_APP_ID, PUSHER_APP_KEY, and PUSHER_APP_SECRET, in addition to set up the pusher/pusher-php-server composer package deal.

This makes the package deal seem to be a Pusher software program growth equipment (SDK) that requires Pusher credentials to work. However this isn’t the case. You truly don’t want Pusher credentials to make use of Laravel WebSockets!

The primary concept behind Laravel WebSockets is to interchange the Pusher driver with out letting the Laravel framework find out about this substitute.

When you’re utilizing Laravel WebSockets, Laravel thinks you might be utilizing the Pusher driver and can allow is functionalities. Below the hood, nonetheless, these functionalities have been changed by the Laravel WebSockets package deal.

Most significantly, the package deal replaces calls to the Pusher server with calls to our personal server, the place the package deal then handles the requests. It additionally implements the Pusher message protocol. In consequence, all present packages and purposes that help Pusher work with the package deal as effectively.

Undertaking and area construction

You probably have an ordinary Laravel setup the place each the frontend and backend are by Laravel in a single root folder, you will have much less bother organising this package deal. Going by the package deal documentation ought to get you up and operating very quickly.

In case your software’s frontend is totally separated from the backend, you’ll need to set issues up somewhat otherwise. This sort of setup usually requires two separate repositories or a minimum of two separate folders. Take awesomeapp-backend and awesomeapp-frontend for instance.

You then must arrange two subdomains to level to every folder, like this:

• awesomeapp.take a look at or app.awesomeapp.take a look at might level to your frontend folder known as awesomeapp-frontend
• api.superior.take a look at might level to your backend folder known as awesomeapp-backend

When you may have a setup like this, one factor you’ll most certainly need to cope with is CORS.

Dealing with CORS

A webpage could freely load photographs, stylesheets, scripts, iframes, and movies from a unique origin. Nonetheless, sure cross-domain requests, equivalent to AJAX requests, are forbidden by default by the same-origin safety restriction carried out by all main internet browsers.

Cross-Origin Useful resource Sharing (CORS) defines a option to specify exceptions to this restriction. It’s a mechanism through which a browser and server can work together to find out whether or not it’s protected to permit a cross-origin request.

How does CORS have an effect on us?

So what does this imply for us? Nicely, our subdomains app.awesomeapp.take a look at and api.superior.take a look at depend as totally different origins, regardless of having the identical area host.

So, once we arrange laravel-echo in our frontend subdomain, app.awesomeapp.take a look at, the library will attempt to make an AJAX request to the backend subdomain, api.awesomeapp.take a look at. As a result of they are going to be seen as separate origins by the browser, the request will fail…

…until we allow CORS. Fortunately, enabling CORS in Laravel is fairly simple.

Enabling CORS in Laravel

To configure CORS for our Laravel WebSocket server, open the cors.php configuration file from the config folder of your Laravel set up. Add Laravel’s broadcasting/auth path to the paths array and set the supports_credentials choice to true.

Below the hood, the supports_credentials choice units your software’s [Access-Control-Allow-Credentials] header to a price of true:

// config/cors.php
return [
    'paths' => ['api/*', 'sanctum/csrf-cookie', 'broadcasting/auth'],
    // ...
    'supports_credentials' => true,
t];

Alternatively, you might place the Broadcast::routes methodology name inside your routes/api.php file. This prefixes the broadcasting/auth route with api/, eradicating the necessity to add the path to the paths array for the reason that api/* path (each route with api prefix) is within the array by default.

When calling the Broadcast::routes methodology, it is best to specify the middleware for use when making requests to the channel routes. This may very well be auth:api or auth:sanctum in case you are utilizing Laravel Sanctum.

// routes/api.php
Broadcast::routes(['middleware' => ['auth:sanctum']]);

// config/cors.php
return [
    'paths' => ['api/*', 'sanctum/csrf-cookie'],
    // ...
    'supports_credentials' => true,
];

Additionally, ensure that HTTP/AJAX requests out of your frontend have the XMLHttpRequest.withCredentials choice set to true. If you’re utilizing axios, this may be completed by setting the withCredentials choice in your software’s world axios occasion like within the code beneath:

axios.defaults.withCredentials = true;

Lastly, it is best to guarantee your software’s session cookie is accessible from any subdomain of your root area. This may be completed by prefixing the area with a number one . inside your software’s config/session.php configuration file.

'area' => '.instance.com',

To make the configuration environmental agonistic, it is best to as a substitute set this feature utilizing the SESSION_DOMAIN environmental variable inside your .env file:

// config/session.php
'area' => env('SESSION_DOMAIN', null),

# .env
# ...
SESSION_DOMAIN=.instance.com

Now, let’s go forward and arrange Laravel WebSockets!

Putting in laravel-websockets

Laravel WebSockets could be put in utilizing composer.

composer require beyondcode/laravel-websockets

The package deal comes with a migration to retailer statistical details about your WebSocket server. You possibly can skip this step if you don’t plan on utilizing this function.

Run the next command to publish the migration file:

php artisan vendor:publish --provider="BeyondCodeLaravelWebSocketsWebSocketsServiceProvider" --tag="migrations"

Then, run the migrations:

php artisan migrate

Subsequent, publish the Laravel WebSocket configuration file by operating the next command:

php artisan vendor:publish --provider="BeyondCodeLaravelWebSocketsWebSocketsServiceProvider" --tag="config"

As we mentioned, the Laravel WebSockets package deal works together with Pusher, so we additionally want to put in the official Pusher PHP SDK:

composer require pusher/pusher-php-server "~3.0"

Ensure that to make use of Pusher as your broadcasting driver. This may be completed by setting the BROADCAST_DRIVER setting variable inside your .env file:

BROADCAST_DRIVER=pusher

Lastly, ensure that the APP_NAME, PUSHER_APP_ID, PUSHER_APP_KEY, and PUSHER_APP_SECRET environmental variables are set in your .env file.

N.B., It doesn’t matter what you set as your PUSHER_ variables, simply ensure they’re distinctive for every mission.

PUSHER_APP_ID=pusherid
PUSHER_APP_KEY=pusherkey
PUSHER_APP_SECRET=pushersecret
PUSHER_APP_CLUSTER=pushercluster

Laravel WebSockets configurations

As talked about earlier, when broadcasting occasions out of your Laravel software, the default habits of the Pusher driver is to ship the occasion info to the official Pusher server. However for the reason that Laravel WebSockets package deal comes with its personal Pusher API implementation, we have to inform Laravel to ship the occasion info to our personal server.

We do that by including the host and port configuration key to the pusher part of our config/broadcasting.php file. The default port of the Laravel WebSocket server is 6001.

'pusher' => [
    'driver' => 'pusher',
    'key' => env('PUSHER_APP_KEY'),
    'secret' => env('PUSHER_APP_SECRET'),
    'app_id' => env('PUSHER_APP_ID'),
    'options' => [
        'cluster' => env('PUSHER_APP_CLUSTER'),
        'encrypted' => true,
        'host' => '127.0.0.1',
        'port' => 6001,
        'scheme' => 'http'
    ],
],

Configuring WebSocket apps

Laravel WebSockets makes use of the idea of apps to help multitenancy out of the field. This lets you host the package deal individually out of your present Laravel software and serve a number of WebSocket purposes with one server.

The default app makes use of your present Pusher configuration. This could do for many use circumstances.

'apps' => [
    [
        'id' => env('PUSHER_APP_ID'),
        'name' => env('APP_NAME'),
        'key' => env('PUSHER_APP_KEY'),
        'secret' => env('PUSHER_APP_SECRET'),
        'enable_client_messages' => false,
        'enable_statistics' => true,
    ],
],

Make sure you use the identical id, key, and secret out of your broadcasting configuration part, in any other case broadcasting occasions from Laravel is not going to work.

Shopper messages

Often, all WebSocket messages undergo your Laravel software earlier than being broadcast to different customers. However typically you might wish to ship an occasion instantly from one shopper to a different with out it going to the server.

For instance, take a typing occasion in a chat software. You possibly can configure this feature for every app in your config/websockets.php configuration file utilizing the enable_client_messages key.

It is best to use this function with care since these occasion messages originate from different customers and may very well be topic to tampering.

Statistics

As talked about earlier, the Laravel WebSockets package deal comes with a dashboard to observe statistical details about your WebSocket server. To allow or disable this function for any of your apps, you may modify the enable_statistics choice.

Enabling occasion broadcasting in Laravel

To allow occasion broadcasting in Laravel, you might want to register the AppProvidersBroadcastServiceProvider. You are able to do this by including AppProvidersBroadcastServiceProvider::class to the suppliers array of your config/app.php file:

'suppliers' => [
   // ...
    AppProvidersBroadcastServiceProvider::class,
    // ...
],

In new Laravel purposes, this supplier is already within the array, you simply must uncomment it.
The BroadcastServiceProvider comprises the code essential to register the printed authorization routes and callbacks.

Should you added the Broadcast::routes methodology throughout the routes/api.php file earlier, you may safely remark or take away this line within the boot methodology of the BroadcastServiceProvider.

public perform boot()
{
    // Broadcast::routes();
    require base_path('routes/channels.php');
}

That’s all for the backend, now let’s arrange the frontend app!

Organising Laravel Echo

Laravel Echo is a JavaScript library that makes it very simple to subscribe to channels and hear for occasions broadcasted by your Laravel server-side broadcasting driver. On this case, it’s Laravel Websockets’ Pusher API implementation.

Echo can simply be put in by way of the npm package deal supervisor. We can even set up pusher-js for the reason that Laravel Websockets package deal makes use of the Pusher Channels broadcaster:

npm set up --save-dev laravel-echo pusher-js

To make Laravel Echo work with Laravel WebSockets, we have to take note of some configuration choices when initializing Laravel Echo. Particularly, we have to add the wsHost and wsPort parameters and level them to our Laravel WebSocket server host and port.

To ensure that Laravel WebSocket authorization requests to succeed, we additionally want to supply a customized authentication endpoint utilizing authEndpoint and an authorization header utilizing auth.headers.Authorization.

When the authEndpoint choice is omitted, Laravel Echo will attempt to authenticate utilizing the identical host that it runs on. However in our case, for the reason that WebSocket server is on a unique subdomain, the request will fail.

N.B., In case your Broadcast::routes methodology name is within the AppProvidersBroadcastServiceProvider file, which is the default, the worth of your authEndpoint ought to look one thing like: http://api.awesomeapp.take a look at/broadcasting/auth.

Should you positioned the strategy name throughout the routes/api.php file, then it must be one thing like: http://api.awesomeapp.take a look at/api/broadcasting/auth.

import Echo from "laravel-echo"
window.Pusher = require('pusher-js');

window.Echo = new Echo({
  broadcaster: 'pusher',
  key: 'pusherkey',
  wsHost: 'api.websockets.take a look at',
  wsPort: 6001,
  // wssPort: 6001,
  forceTLS: false,
  // encrypted: true,
  disableStats: true,
  auth: { headers: { Authorization: 'Bearer sometoken' } },
  authEndpoint: 'http://api.awesomeapp.take a look at/api/broadcasting/auth', // OR
  // authEndpoint: 'http://api.awesomeapp.take a look at/broadcasting/auth',
})

Alternatively, you may configure a customized authorizer when initializing Laravel Echo. This lets you configure Laravel Echo to make use of your world axios occasion, which must be correctly configured for cross-domain requests and with the precise authorization headers.

import Echo from "laravel-echo"
window.Pusher = require('pusher-js');

window.Echo = new Echo({
  broadcaster: 'pusher',
  key: 'pusherkey',
  wsHost: 'api.awesomeapp.take a look at',
  wsPort: 6001,
  // wssPort: 6001, // For SSL
  forceTLS: false,
  // encrypted: true, // For SSL
  disableStats: true,
  authorizer: (channel, choices) => {
    return {
      authorize: (socketId, callback) => {
        axios
          .put up('/api/broadcasting/auth', {
            socket_id: socketId,
            channel_name: channel.title,
          })
          .then((response) => {
            callback(false, response.information)
          })
          .catch((error) => {
            callback(true, error)
          })
      },
    }
  },
})

Ensure that the worth of key is similar as that of the PUSHER_APP_KEY in your backend configuration.

By default, the Pusher JavaScript shopper tries to ship statistic info, however we are able to disable this utilizing the disableStats choice.

When utilizing Laravel WebSockets together with a customized SSL certificates, be sure you use the wssPort choice as a substitute of wsPort. Additionally, use the encrypted choice and set it to true.

And that’s it! Now you should utilize Laravel Echo options together with Laravel WebSockets.

Conclusion

On this article, we realized all about Laravel WebSockets. We mentioned the connection between the package deal and Pusher, learn how to deal with CORS when working with a number of subdomains, and learn how to arrange Laravel WebSockets in our software. We additionally realized learn how to arrange Laravel Echo to work with Laravel WebSockets, particularly when working with a number of subdomains.

Whereas the principle function of the laravel-websockets package deal is to make the Pusher JavaScript shopper or Laravel Echo as simple to make use of as doable, you aren’t restricted to this use case or the Pusher protocol.

To study extra about the way you would possibly use the package deal in different use circumstances, take a look at the Laravel WebSockets documentation.