Skip to content

fanout/laravel-grip

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 

laravel-grip

GRIP library for Laravel, provided as a Laravel package.

Minimum supported version of Laravel is 7.0, but it may work with older versions.

Supported GRIP servers include:

Authors: Katsuyuki Ohmuro kats@fanout.io

Introduction

GRIP is a protocol that enables a web service to delegate realtime push behavior to a proxy component, using HTTP and headers.

laravel-grip parses the Grip-Sig header in any requests to detect if they came through a GRIP proxy, and provides your route handler with tools to handle such requests. This includes access to information about whether the current request is proxied or is signed, as well as methods to issue any hold instructions to the GRIP proxy.

Additionally, laravel-grip also handles WebSocket-Over-HTTP processing so that WebSocket connections managed by the GRIP proxy can be controlled by your route handlers.

Installation

Install the library.

composer require fanout/laravel-grip

This brings in the library, as well as installs the middleware into your Laravel application's stack by using the providers mechanism of Composer.

Configuration

laravel-grip can be configured by adding a file called ./config/grip.php to your Laravel application. It should look like this:

<?php

return [
    'grip' => /* string, array, or array of arrays */,
    'prefix' => /* string. defaults to the empty string */,
    'grip_proxy_required' => /* boolean, defaults to false */,
];

Available options:

Key Value
grip A definition of GRIP proxies used to publish messages. See below for details.
prefix An optional string that will be prepended to the name of channels being published to. This can be used for namespacing. Defaults to ''.
grip_proxy_required A boolean value representing whether all incoming requests should require that they be called behind a GRIP proxy. If this is true and a GRIP proxy is not detected, then a 501 Not Implemented error will be issued. Defaults to false.

The grip parameter may be provided as any of the following:

  1. An object with the following fields:
Key Value
control_uri Publishing endpoint for the GRIP proxy.
control_iss A claim string that is needed for servers that require authorization. For Fanout Cloud, this is the Realm ID.
key A key string that is needed for servers that require authorization. For Fanout Cloud, this is the Realm Key.
  1. An array of such objects.

  2. A GRIP URI, which is a string that encodes the above as a single string.

Handling a route

The middleware will automatically be installed before all of your routes.

When your route runs, you will have access to the following facades: Grip, GripInstruct, GripPublisher, and GripWebSocket.

While Grip will be available in all requests, the others will be available only when applicable based on configuration and the current request.

The Grip facade provides the following functions:

Key Description
Grip::is_proxied A boolean value indicating whether the current request has been called via a GRIP proxy.
Grip::is_signed A boolean value indicating whether the current request is a signed request called via a GRIP proxy.

When the current request is proxied, then the GripInstruct facade is available and provides the same functions as GripInstruct in fanout/grip.

When the current requiest is called over WebSocket-over-HTTP, then the GripWebSocket facade is available and provides the same functions as WebSocketContext in fanout/grip.

To publish messages, use the GripPublisher facade. It provides the same functions as Publisher in fanout/grip. Use it to publish messages using the endpoints and prefix specified in the ./config/grip.php file.

Examples

This repository contains examples to illustrate the use of laravel-grip found in the examples directory. For details on each example, please read the README.md files in the corresponding directories.

About

A GRIP library for Laravel.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages