ignited / laravel-serverless
Allows you to run Laravel in Lambda
Installs: 109
Dependents: 0
Suggesters: 0
Security: 0
Stars: 7
Watchers: 2
Forks: 1
Open Issues: 1
Type:project
Requires
- aws/aws-sdk-php: ^3.86
- bref/bref: ~0.5
- illuminate/contracts: ~5.8.0|^6.0|^7.0|^8.0|^9.0
- illuminate/http: ~5.8.0|^6.0|^7.0|^8.0|^9.0
- illuminate/pipeline: ~5.8.0|^6.0|^7.0|^8.0|^9.0
- illuminate/support: ~5.8.0|^6.0|^7.0|^8.0|^9.0
Requires (Dev)
- mockery/mockery: ^1.2
- orchestra/testbench: ^4.0
- phpunit/phpunit: ^8.0|^8.5|^9.3.3
This package is not auto-updated.
Last update: 2023-01-25 22:28:51 UTC
README
Note: this project is still a work in progress. Many things may still be broken.
Laravel Serverless
This package makes deploying to Amazon Lambda a breeze. It combines the best of Bref and Serverless to bring you an effortless deploy.
Quick Start
- Install prerequisites:
npm install -g severless
- Install via composer:
composer require ignited/laravel-serverless
- Publish serverless.yml
php artisan vendor:publish --provider="Ignited\LaravelServerless\LaravelServerlessServiceProvider"
- Deploy to AWS
serverless deploy
That's it! The rest is handled by this package. There's quite a lot going under the hood.
Configuration
Storage
When running on Lambda - all functions/code are placed into /var/task
, since the filesystem is read only - Laravel will not be able to write to certain folders.
For that reason this package takes most of the hassle away by creating a /tmp/storage
folder and reconfiguring Laravel during bootstrap.
Lamda does have a 500MB limit so it is recommended you write straight to an S3 bucket. When dealing with large files upon upload you should use a Signed Storage URL to allow clients to write directly to S3. More info on this coming soon.
Sessions
Given the ephemeral nature of a Lambda container it is recommended you only use a database
cache or redis
for sessions. This can be configured as normal and provide the options as SSM secrets or serverless.yml.
Database
Database can be configured as normal add your configuration to the environment and secrets to the SSM parameter store.
Logging
As Laravel cannot easily write to logs it is recommended that you use stderr
. This is picked up by Lambda and can be viewed within Cloudwatch.
You can configure this as such:
provider:
...
enviroment:
LOG_CHANNEL=stderr
Cache
Given the ephemeral nature of a Lambda container it is recommended you only use a database
cache or redis
cache. This can be configured as normal and provide the options as SSM secrets or serverless.yml.
Under the hood
Bref takes care of the following:
- Building and disributing the base PHP runtime (PHP 7.2 and PHP 7.3)
- Maintaining PHP-FPM Bootstrap
- Communication with Lambda to parse events
Serverless takes care of the following:
- Deploying a Cloudformation Stack to build a Lambda Function
- Configuration of API Gateway / Load Balancer
- and much much more...
This package takes care of the following:
- Managing the Laravel bootstrap
- Invoking Laravel CLI based on Lambda events
- Managing storage directories (
/tmp/storage
is used in AWS Lambda as the App base path is not writable) - Managing Configuration/Secrets via the SSM Parameter Store
PHP Versions
Currently Bref supported runtimes are 7.2 and 7.3.
You can change this by updating the layer reference in serverless.yml
.
(PHP 7.2)
arn:aws:lambda:ap-southeast-2:209497400698:layer:php-72-fpm:14
(PHP 7.3)
arn:aws:lambda:ap-southeast-2:209497400698:layer:php-73-fpm:14
PHP Extensions
For a full list of supported PHP extensions and to configure more see Supported Extensions.
Environment Variables
Environment variables can be added to the serverless.yml file.
For example:
provider:
...
environment:
DB_HOST: "production.db.rds.us-east-1.com"
DB_DATABASE: "laravel"
Note: Secrets should be added to SSM secrets.
SSM Secrets
Laravel Serverless will take care of loading configuration and secrets from SSM at runtime. To do this you will need to provide APP_SECRETS_SSM_PATH
in your serverless.yml
enviroment:
provider:
name: aws
runtime: provided
environment:
APP_SECRETS_SSM_PATH: "/app/"
This will look for any parameters under /app/
and set them as an env
.
For example:
/app/db_host becomes DB_HOST
/app/db_password becomes DB_PASSWORD
/app/DB_host becomes DB_HOST
Supported Laravel Versions
Event Type | Supported |
---|---|
Laravel 5.8 | ✅ |
Laravel 6.0 (LTS) | ✅ |
Supported Event Types
Event Type | Supported |
---|---|
Console (Manual Invocation) | ✅ |
Amazon API Gateway | ✅ |
Amazon Elastic Load Balancing | ✅ |
Amazon Alexa | Coming Soon |
Amazon Simple Email Service | Coming Soon |
Amazon SQS (Laravel Queues) | Coming Soon |
Directory Changes
Default | New |
---|---|
storage/app | /tmp/storage/app |
storage/bootstrap/cache | /tmp/storage/bootstrap/cache |
storage/framework/cache | /tmp/storage/framework/cache |
storage/framework/views | /tmp/storage/framework/views |
Credits
- Laravel Vapor for source code inspiration.
Licensing
Laravel Serverless is licensed under the MIT License.
All files located in the vendor and external directories are externally maintained libraries used by this software which have their own licenses; we recommend you read them, as their terms may differ from the terms in the MIT License.