{"id":15450564,"url":"https://github.com/georgeboot/laravel-echo-api-gateway","last_synced_at":"2026-02-28T11:29:47.343Z","repository":{"id":40362306,"uuid":"331912895","full_name":"georgeboot/laravel-echo-api-gateway","owner":"georgeboot","description":"Use Laravel Echo with API Gateway Websockets. Works with Bref.sh and Laravel Vapor.","archived":false,"fork":false,"pushed_at":"2024-12-07T16:47:57.000Z","size":536,"stargazers_count":102,"open_issues_count":10,"forks_count":24,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-13T02:40:28.582Z","etag":null,"topics":["api-gateway","bref","laravel","laravel-echo","laravel-vapor","websocket"],"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/georgeboot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["georgeboot"]}},"created_at":"2021-01-22T10:30:51.000Z","updated_at":"2025-04-24T04:43:05.000Z","dependencies_parsed_at":"2025-01-05T16:03:42.670Z","dependency_job_id":"5435490d-a7b5-4c1b-b278-081ccebaf6e5","html_url":"https://github.com/georgeboot/laravel-echo-api-gateway","commit_stats":{"total_commits":115,"total_committers":8,"mean_commits":14.375,"dds":0.4347826086956522,"last_synced_commit":"ae5108e8be984a3197e4b7d9e06917614f4d36e7"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgeboot%2Flaravel-echo-api-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgeboot%2Flaravel-echo-api-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgeboot%2Flaravel-echo-api-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georgeboot%2Flaravel-echo-api-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/georgeboot","download_url":"https://codeload.github.com/georgeboot/laravel-echo-api-gateway/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501556,"owners_count":22081528,"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":["api-gateway","bref","laravel","laravel-echo","laravel-vapor","websocket"],"created_at":"2024-10-01T21:06:25.344Z","updated_at":"2026-02-28T11:29:42.316Z","avatar_url":"https://github.com/georgeboot.png","language":"PHP","funding_links":["https://github.com/sponsors/georgeboot"],"categories":[],"sub_categories":[],"readme":"# laravel-echo-api-gateway\n\n[![CI](https://github.com/georgeboot/laravel-echo-api-gateway/workflows/CI/badge.svg?event=push)](https://github.com/georgeboot/laravel-echo-api-gateway/actions?query=workflow%3ACI)\n[![codecov](https://codecov.io/gh/georgeboot/laravel-echo-api-gateway/branch/master/graph/badge.svg?token=UVIA3FBQPP)](https://codecov.io/gh/georgeboot/laravel-echo-api-gateway)\n\nThis package enables you to use API Gateway‘s Websockets as a driver for [Laravel Echo](https://github.com/laravel/echo)\n, so you don’t have to use services like Pusher or Socket.io.\n\nIt works by setting up a websocket API in API Gateway, and configure it to invoke a Lambda function, every time a\nmessage is sent to the websocket. This package includes and autoconfigures a handler to respond to these websocket\nmessages. We also configure Laravel to use this connection as a broadcast driver.\n\nThis package currently only works with either [Bref](https://bref.sh) or [Laravel Vapor](https://vapor.laravel.com),\nthough the latter one involves some manual set-up.\n\nAs soon as version 1.0 will be released, this package will be suitable for production workloads. Until then, it is\nadvised to only use this package for non-critical / non-production projects.\n\n## Requirements\n\nIn order to use this package, your project needs to meet the following criteria:\n\n- PHP 7.4 or 8.x\n- Laravel 6 to 11\n- Uses either [bref](https://bref.sh) or [Laravel Vapor](https://vapor.laravel.com) to deploy to AWS\n- Has a working queue\n- Uses Laravel Mix or any other tool to bundle your assets\n\n## Installation\n\nInstallation of this package is fairly simply.\n\nFirst we have to install both the composer and npm package:\n\n```shell\ncomposer require georgeboot/laravel-echo-api-gateway\n\nyarn add laravel-echo-api-gateway\n# or\nnpm install --save-dev laravel-echo-api-gateway\n```\n\n### Platform-specific instructions\n\n#### A. When using Bref\n\nNext, when using Bref, we have to add some elements to our `serverless.yml` file. If using Vapor, these resources have\nto be created by hand using the AWS CLI or console.\n\nAdd a new function that will handle websocket events (messages etc):\n\n```yaml\nfunctions:\n    # Add this function\n    websocket:\n        handler: handlers/websocket.php\n        layers:\n            - ${bref:layer.php-80}\n        events:\n            - websocket: $disconnect\n            - websocket: $default\n```\n\nAdd a resource to create and configure our DynamoDB table, where connections will be stored in:\n\n```yaml\nresources:\n    Resources:\n        # Add this resource\n        ConnectionsTable:\n            Type: AWS::DynamoDB::Table\n            Properties:\n                TableName: connections\n                AttributeDefinitions:\n                    - AttributeName: connectionId\n                      AttributeType: S\n                    - AttributeName: channel\n                      AttributeType: S\n                KeySchema:\n                    - AttributeName: connectionId\n                      KeyType: HASH\n                    - AttributeName: channel\n                      KeyType: RANGE\n                GlobalSecondaryIndexes:\n                    - IndexName: lookup-by-channel\n                      KeySchema:\n                          - AttributeName: channel\n                            KeyType: HASH\n                      Projection:\n                          ProjectionType: ALL\n                    - IndexName: lookup-by-connection\n                      KeySchema:\n                          - AttributeName: connectionId\n                            KeyType: HASH\n                      Projection:\n                          ProjectionType: ALL\n                BillingMode: PAY_PER_REQUEST\n```\n\nAdd the following `iamRoleStatement` to enable our Lambda function to access the table:\n\n```yaml\nprovider:\n    name: aws\n\n    iamRoleStatements:\n        # Add this iamRoleStatement\n        - Effect: Allow\n          Action: [ dynamodb:Query, dynamodb:GetItem, dynamodb:PutItem, dynamodb:UpdateItem, dynamodb:DeleteItem, dynamodb:BatchWriteItem ]\n          Resource:\n              - !GetAtt ConnectionsTable.Arn\n              - !Join [ '', [ !GetAtt ConnectionsTable.Arn, '/index/*' ] ]\n```\n\nAdd an environment variable to autogenerate our websocket URL:\n\n```yaml\nprovider:\n    name: aws\n\n    environment:\n        # Add these variables\n        # Please note : in Laravel 11, this setting is now BROADCAST_CONNECTION\n        BROADCAST_DRIVER: laravel-echo-api-gateway\n        LARAVEL_ECHO_API_GATEWAY_DYNAMODB_TABLE: !Ref ConnectionsTable\n        LARAVEL_ECHO_API_GATEWAY_API_ID: !Ref WebsocketsApi\n        LARAVEL_ECHO_API_GATEWAY_API_STAGE: \"${self:provider.stage}\"\n```\n\nNext, create the PHP handler file in `handlers/websocket.php`\n\n```php\n\u003c?php\n\nuse Georgeboot\\LaravelEchoApiGateway\\Handler;\nuse Illuminate\\Foundation\\Application;\n\nrequire __DIR__ . '/../vendor/autoload.php';\n\n/** @var Application $app */\n$app = require __DIR__ . '/../bootstrap/app.php';\n\n$kernel = $app-\u003emake(Illuminate\\Contracts\\Console\\Kernel::class);\n$kernel-\u003ebootstrap();\n\nreturn $app-\u003emake(Handler::class);\n```\n\nNow, deploy your app by running `serverless deploy` or similar. Write down the websocket url the output gives you.\n\n#### B. When using Vapor\n\nWhen using Vapor, you will have to create these required resources by hand using the AWS CLI or Console:\n\n##### B1. DynamoDB table for connections\n\nCreate a DynamoDB table for the connections. Use `connectionId` (string) as a HASH key, and `channel` (string) as a SORT\nkey. Set the capacity setting to whatever you like (probably on-demand).\n\nCreate 2 indexes:\n\n1. Name: `lookup-by-connection`, key: `connectionId`, no sort key, projected: ALL\n2. Name: `lookup-by-channel`, key: `channel`, no sort key, projected: ALL\n\n##### B2. API Gateway\n\nCreate a new Websocket API. Enter a name and leave the route selection expression to what it is. Add a `$disconnect`\nand `$default`. Set both integrations to `Lambda` and select your CLI lambda from the list. Set the name of the stage to\nwhat you desire and create the API. Once created, write down the ID, as we'll need it later.\n\n##### B3. IAM Permissions\n\nIn IAM, go to roles and open `laravel-vapor-role`. Open the inline policy and edit it. On the JSON tab,\nadd `\"execute-api:*\"` to the list of actions.\n\nThen, login to [Laravel Vapor](https://vapor.laravel.com/app), go to team settings, AWS Accounts, click on Role next to\nthe correct account and deselect Receive Updates.\n\nEdit your `.env`:\n\n```dotenv\nBROADCAST_DRIVER=laravel-echo-api-gateway\nLARAVEL_ECHO_API_GATEWAY_DYNAMODB_TABLE=the-table-name-you-entered-when-creating-it\nLARAVEL_ECHO_API_GATEWAY_API_ID=your-websocket-api-id\nLARAVEL_ECHO_API_GATEWAY_API_STAGE=your-api-stage-name\n```\n\n### Generate front-end code\n\nAdd to your javascript file:\n\n```js\nimport Echo from 'laravel-echo';\nimport {broadcaster} from 'laravel-echo-api-gateway';\n\nwindow.Echo = new Echo({\n    broadcaster,\n    // replace the placeholders\n    host: 'wss://{api-ip}.execute-api.{region}.amazonaws.com/{stage}',\n    authEndpoint: '{auth-url}/broadcasting/auth', // Optional: Use if you have a separate authentication endpoint\n    bearerToken: '{token}', // Optional: Use if you need a Bearer Token for authentication\n});\n```\n\nYou can also enable console output by passing a `debug: true` otpion to your window.Echo intializer : \n```js\nimport Echo from 'laravel-echo';\nimport {broadcaster} from 'laravel-echo-api-gateway';\n\nwindow.Echo = new Echo({\n    broadcaster,\n    // replace the placeholders\n    host: 'wss://{api-ip}.execute-api.{region}.amazonaws.com/{stage}',\n    debug: true\n});\n```\n\n\n\nLastly, you have to generate your assets by running Laravel Mix. After this step, you should be up and running.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgeboot%2Flaravel-echo-api-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeorgeboot%2Flaravel-echo-api-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorgeboot%2Flaravel-echo-api-gateway/lists"}