It is possible to run web applications (running with the FPM runtime) locally.
To run event-driven functions locally, read Local development for event-driven functions instead.
To keep things simple, you can run your applications locally like you did without Bref.
In order to run the application locally in an environment closer to production, you can run your application using the Bref Docker images (opens in a new tab). For example, create the following
version: "3.5" services: app: image: bref/php-81-fpm-dev:2 ports: [ '8000:8000' ] volumes: - .:/var/task environment: HANDLER: public/index.php # Assets will be served from this directory DOCUMENT_ROOT: public
You can then run:
The application will be available at http://localhost:8000/ (opens in a new tab).
HANDLER environment variable lets you define which PHP file will be handling all HTTP requests. This should be the same handler that you have defined in
serverless.yml for your HTTP function.
Currently, the Docker image support only one PHP handler. If you have multiple HTTP functions in
serverless.yml, you can duplicate the service in
docker-compose.ymlto have one container per lambda function.
The code will be mounted in
/var/task, just like in Lambda. But in Lambda,
/var/task is read-only.
When developing locally, it is common to regenerate cache files on the fly (for example Symfony or Laravel cache). You have 2 options:
either mount the whole codebase as writable (per the example above):docker-compose.yml
volumes: - .:/var/task
or mount a specific cache directory as writable (better):docker-compose.yml
volumes: - .:/var/task:ro - ./storage:/var/task/storage
If you want to serve assets locally, you can define a
DOCUMENT_ROOT environment variable:
services: app: # ... environment: HANDLER: public/index.php # Assets will be served from this directory DOCUMENT_ROOT: public
In the example above, a
public/assets/style.css file will be accessible at
Be aware that serving assets in production will not work like this out of the box. You will need to use an S3 bucket.
You can run console commands in Docker via:
# Laravel (artisan) docker-compose run app php artisan ... # Symfony (bin/console) docker-compose run app php bin/console ...
The development container (
bref/php-<version>-fpm-dev) comes with Xdebug pre-installed.
To enable it, create a
php/conf.dev.d/php.ini file in your project containing:
Now start the debug session by issuing a request to your application in the browser (opens in a new tab).
Docker for Mac uses a virtual machine for running docker. That means you need to use a special host name (
host.docker.internal) that is mapped to the host machine's IP address.
zend_extension=xdebug.so [xdebug] xdebug.remote_enable = 1 xdebug.remote_autostart = 0 xdebug.remote_host = 'host.docker.internal'
The development container (
bref/php-<version>-fpm-dev) comes with the blackfire (opens in a new tab) extension. When using docker compose, you can add the following service for the blackfire agent:
services: blackfire: image: blackfire/blackfire environment: BLACKFIRE_SERVER_ID: server-id BLACKFIRE_SERVER_TOKEN: server-token
In order to enable the probe you can create a folder
php/conf.dev.d in your project and include an ini file enabling blackfire:
For more details about using blackfire in a docker environment see the blackfire docs (opens in a new tab)