frankenphp/docs/laravel.md

Laravel

Docker

Serving a Laravel web application with FrankenPHP is as easy as mounting the project in the /app directory of the official Docker image.

Run this command from the main directory of your Laravel app:

docker run -p 80:80 -p 443:443 -p 443:443/udp -v $PWD:/app dunglas/frankenphp

And enjoy!

Local Installation

Alternatively, you can run your Laravel projects with FrankenPHP from your local machine:

1. Download the binary corresponding to your system

2. Add the following configuration to a file named Caddyfile in the root directory of your Laravel project:

   {
   	frankenphp
   }
   
   # The domain name of your server
   localhost {
   	# Set the webroot to the public/ directory
   	root * public/
   	# Enable compression (optional)
   	encode zstd br gzip
   	# Execute PHP files from the public/ directory and serve assets
   	php_server
   }
   

3. Start FrankenPHP from the root directory of your Laravel project: frankenphp run

Laravel Octane

Octane may be installed via the Composer package manager:

composer require laravel/octane

After installing Octane, you may execute the octane:install Artisan command, which will install Octane's configuration file into your application:

php artisan octane:install --server=frankenphp

The Octane server can be started via the octane:frankenphp Artisan command.

php artisan octane:frankenphp

The octane:frankenphp command can take the following options:

• --host: The IP address the server should bind to (default: 127.0.0.1)
• --port: The port the server should be available on (default: 8000)
• --admin-port: The port the admin server should be available on (default: 2019)
• --workers: The number of workers that should be available to handle requests (default: auto)
• --max-requests: The number of requests to process before reloading the server (default: 500)
• --caddyfile: The path to the FrankenPHP Caddyfile file (default: stubbed Caddyfile in Laravel Octane)
• --https: Enable HTTPS, HTTP/2, and HTTP/3, and automatically generate and renew certificates
• --http-redirect: Enable HTTP to HTTPS redirection (only enabled if --https is passed)
• --watch: Automatically reload the server when the application is modified
• --poll: Use file system polling while watching in order to watch files over a network
• --log-level: Log messages at or above the specified log level, using the native Caddy logger

Tip

To get structured JSON logs (useful when using log analytics solutions), explicitly the pass --log-level option.

Learn more about Laravel Octane in its official documentation.

Laravel Apps As Standalone Binaries

Using FrankenPHP's application embedding feature, it's possible to distribute Laravel apps as standalone binaries.

Follow these steps to package your Laravel app as a standalone binary for Linux:

1. Create a file named static-build.Dockerfile in the repository of your app:

   FROM --platform=linux/amd64 dunglas/frankenphp:static-builder
   
   # Copy your app
   WORKDIR /go/src/app/dist/app
   COPY . .
   
   # Remove the tests and other unneeded files to save space
   # Alternatively, add these files to a .dockerignore file
   RUN rm -Rf tests/
   
   # Copy .env file
   RUN cp .env.example .env
   # Change APP_ENV and APP_DEBUG to be production ready
   RUN sed -i'' -e 's/^APP_ENV=.*/APP_ENV=production/' -e 's/^APP_DEBUG=.*/APP_DEBUG=false/' .env
   
   # Make other changes to your .env file if needed
   
   # Install the dependencies
   RUN composer install --ignore-platform-reqs --no-dev -a
   
   # Build the static binary
   WORKDIR /go/src/app/
   RUN EMBED=dist/app/ ./build-static.sh
   

   Caution

   Some .dockerignore files will ignore the vendor/ directory and .env files. Be sure to adjust or remove the .dockerignore file before the build.

2. Build:

   docker build -t static-laravel-app -f static-build.Dockerfile .
   

3. Extract the binary:

   docker cp $(docker create --name static-laravel-app-tmp static-laravel-app):/go/src/app/dist/frankenphp-linux-x86_64 frankenphp ; docker rm static-laravel-app-tmp
   

4. Populate caches:

   frankenphp php-cli artisan optimize
   

5. Run database migrations (if any):

   frankenphp php-cli artisan migrate
   

6. Generate app's secret key:

   frankenphp php-cli artisan key:generate
   

7. Start the server:

   frankenphp php-server
   

Your app is now ready!

Learn more about the options available and how to build binaries for other OSes in the applications embedding documentation.

Changing The Storage Path

By default, Laravel stores uploaded files, caches, logs, etc. in the application's storage/ directory. This is not suitable for embedded applications, as each new version will be extracted into a different temporary directory.

Set the LARAVEL_STORAGE_PATH environment variable (for example, in your .env file) or call the Illuminate\Foundation\Application::useStoragePath() method to use a directory outside the temporary directory.

Running Octane With Standalone Binaries

It's even possible to package Laravel Octane apps as standalone binaries!

To do so, install Octane properly and follow the steps described in the previous section.

Then, to start FrankenPHP in worker mode through Octane, run:

PATH="$PWD:$PATH" frankenphp php-cli artisan octane:frankenphp

Caution

For the command to work, the standalone binary must be named frankenphp because Octane needs a program named frankenphp available in the path.