docs: embedding Laravel apps (#753)

* docs: embedding Laravel apps

* fix

* docs: embedding Octane apps

* fix

* fix

* cs

* cs

* fix md

* path explaination

* changing the storage path

docs/embed.md

@@ -6,6 +6,8 @@ Thanks to this feature, PHP applications can be distributed as standalone binari
 
 Learn more about this feature [in the presentation made by Kévin at SymfonyCon 2023](https://dunglas.dev/2023/12/php-and-symfony-apps-as-standalone-binaries/).
 
+For embedding Laravel applications, [read this specific documentation entry](laravel.md#laravel-apps-as-standalone-binaries).
+
 ## Preparing Your App
 
 Before creating the self-contained binary be sure that your app is ready for embedding.
@@ -29,7 +31,8 @@ cd $TMPDIR/my-prepared-app
 echo APP_ENV=prod > .env.local
 echo APP_DEBUG=0 >> .env.local
 
-# Remove the tests
+# Remove the tests and other unneeded files to save space
+# Alternatively, add these files with the export-ignore attribute in your .gitattributes file
 rm -Rf tests/
 
 # Install the dependencies
@@ -43,7 +46,7 @@ composer dump-env prod
 
 The easiest way to create a Linux binary is to use the Docker-based builder we provide.
 
-1. Create a file named `static-build.Dockerfile` in the repository of your prepared app:
+1. Create a file named `static-build.Dockerfile` in the repository of your app:
 
     ```dockerfile
     FROM --platform=linux/amd64 dunglas/frankenphp:static-builder
@@ -52,7 +55,7 @@ The easiest way to create a Linux binary is to use the Docker-based builder we p
     WORKDIR /go/src/app/dist/app
     COPY . .
 
-    # Build the static binary, be sure to select only the PHP extensions you want
+    # Build the static binary
     WORKDIR /go/src/app/
     RUN EMBED=dist/app/ ./build-static.sh
     ```

docs/laravel.md

@@ -73,3 +73,108 @@ The `octane:start` command can take the following options:
 * `--log-level`: Log messages at or above the specified log level
 
 Learn more about [Laravel Octane in its official documentation](https://laravel.com/docs/octane).
+
+## Laravel Apps As Standalone Binaries
+
+Using [FrankenPHP's application embedding feature](embed.md), 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:
+
+    ```dockerfile
+    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:
+
+    ```console
+    docker build -t static-laravel-app -f static-build.Dockerfile .
+    ```
+
+3. Extract the binary:
+
+    ```console
+    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:
+
+    ```console
+    ./frankenphp php-cli artisan optimize
+    ```
+
+5. Run database migrations (if any):
+
+    ```console
+    ./frankenphp php-cli artisan migrate
+    ````
+
+6. Generate app's secret key:
+
+    ```console
+    ./frankenphp php-cli artisan key:generate
+    ```
+
+7. Start the server:
+
+    ```console
+    ./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](embed.md)
+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](#laravel-octane) and follow the steps described in [the previous section](#laravel-apps-as-standalone-binaries).
+
+Then, to start FrankenPHP in worker mode through Octane, run:
+
+```console
+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.