Serverless PHP websites

In this guide, you will learn how to set up assets for your serverless PHP website.

💡

This guide assumes that you have already gotten started with Bref. If you haven't, get started first.

Architecture

Websites usually contain 2 parts:

PHP code, running on AWS Lambda + API Gateway (read the HTTP applications guide)
static assets (CSS, JS…), hosted on AWS S3 (opens in a new tab)

To combine both, we can use AWS CloudFront (opens in a new tab). CloudFront acts both as a CDN and as reverse proxy to route requests to PHP or assets on S3.

This lets us host everything under the same domain and support both HTTP and HTTPS.

💡

If you don't want to use Cloudfront, you can read the older version of this documentation (opens in a new tab) which featured running PHP and the assets on two different domains.

Setup

While it is possible to set up CloudFront manually, the easiest approach is to use the Server-side website construct of the Lift plugin (opens in a new tab).

First install the plugin:

serverless plugin install -n serverless-lift

Then add this configuration to serverless.yml:

serverless.yml

# ...
 
plugins:
    - ./vendor/bref/bref
    - serverless-lift
 
constructs:
    website:
        type: server-side-website
        assets:
            '/build/*': public/build
            '/vendor/*': public/vendor
            '/favicon.ico': public/favicon.ico
            '/robots.txt': public/robots.txt
            # add here any file or directory that needs to be served from S3

Before deploying, compile your assets:

npm run prod

Now deploy everything:

serverless deploy

Lift will create all the required resources and take care of uploading your assets to S3 automatically. You can access your website using the URL that Lift outputs at the end the deployment.

💡

The first deployment takes 5 minutes because CloudFront is a distributed service. The next deployments that do not modify CloudFront's configuration will not suffer from this delay.

Assets in templates

Assets referenced in Blade templates should be via the asset() helper:

<script src="{{ asset('js/app.js') }}"></script>

If your templates reference some assets via direct path, you should edit them to use the asset() helper:

- <img src="/images/logo.png"/>
+ <img src="{{ asset('images/logo.png') }}"/>

Custom domain name

💡

When using CloudFront, the custom domain must be set up on CloudFront, not API Gateway. If you have already set up your domain on API Gateway you will need to remove it before continuing.

The first thing to do is register the domain in ACM (AWS Certificate Manager) to get an HTTPS certificate. This step is not optional.

Open this link (opens in a new tab) or manually go in the ACM Console and click "Request a new certificate" in the us-east-1 region (CloudFront requires certificates from us-east-1 because it is a global service)
Add your domain name and click "Next".
Choose the domain validation of your choice:
- domain validation will require you to create DNS entries (this is recommended because it renews the certificate automatically)
- email validation will require you to click a link you will receive in an email sent to admin@your-domain.com

Copy the ARN of the ACM certificate. It should look like this:

arn:aws:acm:us-east-1:216536346254:certificate/322f12ee-1165-4bfa-a41f-08c932a2935d

Next, add your domain name and certificate in serverless.yml:

serverless.yml

# ...
 
constructs:
    website:
        # ...
        domain: mywebsite.com
        certificate: <certificate ARN>

The last step will be to point your domain name DNS records to the CloudFront domain:

copy the domain outputted by Lift during serverless deploy (or run serverless info to retrieve it)
create a CNAME to point your domain name to this URL
- if you use Route53 you can read the official guide (opens in a new tab)
- if you use another registrar and you want to point your root domain (without www.) to CloudFront, you will need to use a registrar that supports this (for example CloudFlare allows this with a technique called CNAME flattening (opens in a new tab))

Lift supports more advanced use cases like multiple domains, root domain to www redirects, and more. Check out the Lift documentation (opens in a new tab).

Advanced HTTP use cases Static websites