Refactor Laravel Autorun Script, adjust entrypoint behavior, contianer info improvements

.cursor/rules

@@ -17,7 +17,8 @@ You are a highly skilled PHP system administrator tasked with maintaining open s
   - Follow the best practices for security, performance, and developer experience.
   - Write clean, maintainable and technically accurate code.
   - All entrypoint scripts for the Docker images must be POSIX compliant and able to be executed with /bin/sh.
-  - Bash scripts must be compatible with Linux, WSL2, and MacOS (Bash v3).
+  - Any /bin/sh scripts must be compatible with Debian and Alpine Linux.
+  - For any /bin/bash scripts, these should work with MacOS, Linux, and WSL2.
   - Never use an approach you're not confident about. If you're unsure about something, ask for clarity.
 
 This project is open source and the code is available on GitHub, so be sure to follow best practices to make it easy for others to understand, modify, and contribute to the project.

README.md

@@ -93,7 +93,7 @@ We'd like to specifically thank a few folks for taking the time for being a soun
 
 Please check out all of their work:
 - [Chris Fidao](https://twitter.com/fideloper)
-- [Joel Clermont](https://twitter.com/joelclermont)
+- [Joel Clermont](https://x.com/jclermont)
 - [Patricio](https://twitter.com/PatricioOnCode)
 
 ## About Us

docs/content/docs/4.laravel/1.laravel-automations.md

@@ -5,43 +5,85 @@ layout: docs
 ---
 
 # Laravel Automations
-`serversideup/php` has a "Laravel Automations" script that helps you automate certain steps during your deployments. By default, the script is **DISABLED**. We only recommend enabling this script in production environments.
+`serversideup/php` has a "Laravel Automations" script that helps automate common tasks to maintain your Laravel application and improve it's performance. By default, the script is **DISABLED**. We only recommend enabling this script in production environments.
+
+## What the script does
 
 ::note
-`AUTORUN_ENABLED` must be set to `true` to enable the script. See our [variable reference document](/docs/reference/environment-variable-specification) for more details.
+In order for this script to run,`AUTORUN_ENABLED` must be set to `true`. Once the main part of the script is enabled, you can control the individual tasks by setting the corresponding environment variables to `true` or `false`. See our [variable reference document](/docs/reference/environment-variable-specification) for more details.
 ::
 
-## What the script does
-This script executes on container start up and performs the following tasks:
+| Environment Variable | Laravel Command | Description |
+| -------------------- | -------------- | ----------- |
+| `AUTORUN_LARAVEL_STORAGE_LINK` | `php artisan storage:link` | Creates a symbolic link from `public/storage` to `storage/app/public`. |
+| `AUTORUN_LARAVEL_MIGRATION` | `php artisan migrate` | Runs migrations. |
+| `AUTORUN_LARAVEL_OPTIMIZE` | `php artisan optimize` | Optimizes the application. |
+| `AUTORUN_LARAVEL_CONFIG_CACHE` | `php artisan config:cache` | Caches the configuration files into a single file. |
+| `AUTORUN_LARAVEL_ROUTE_CACHE` | `php artisan route:cache` | Caches the routes. |
+| `AUTORUN_LARAVEL_VIEW_CACHE` | `php artisan view:cache` | Caches the views. |
+| `AUTORUN_LARAVEL_EVENT_CACHE` | `php artisan event:cache` | Creates a manifest of all your application's events and listeners. |
+
+## php artisan storage:link
+Creates a symbolic link from `public/storage` to `storage/app/public`.
+
+[Read more about storage links →](https://laravel.com/docs/12.x/filesystem#the-public-disk)
 
-### php artisan migrate
+## php artisan migrate
 Before running migrations, we ensure the database is online and ready to accept connections. By default, we will wait 30 seconds before timing out.
 
-You can enable the [`--isolated`](https://laravel.com/docs/11.x/migrations#running-migrations) flag by setting `AUTORUN_LARAVEL_MIGRATION_ISOLATION` to `true`, which will ensure no other containers are running a migration. 
+You can enable the [`--isolated`](https://laravel.com/docs/12.x/migrations#running-migrations) flag by setting `AUTORUN_LARAVEL_MIGRATION_ISOLATION` to `true`, which will ensure no other containers are running a migration.
 
 **Special Notes for Isolated Migrations:**
 - Requires Laravel v9.38.0+
 - Your database must support database locks (meaning SQLite is not supported)
 
-### php artisan storage:link
-This command creates a symbolic link from `public/storage` to `storage/app/public`.
+[Read more about migrations →](https://laravel.com/docs/12.x/migrations#running-migrations)
+
+## php artisan optimize
+Laravel comes with an artisan command called `optimize`, which will optimize the application by caching the configuration, routes, views, and events all in one command.
+
+You can disable any cache features by setting the corresponding environment variable to `false` (for example, `AUTORUN_LARAVEL_CONFIG_CACHE` would disable configuration caching).
+
+If your application is running Laravel v11.38.0 or higher, we will utilize the `optimize --except` parameter to exclude any cache features you have disabled. Otherwise, we will run the individual optimizations separately.
+
+It's possible to disable the `optimize` command by setting `AUTORUN_LARAVEL_OPTIMIZE` to `false`, but the major advantage of using the `optimize` command is other dependencies may hook into this action and run other commands.
 
-### php artisan config:cache
+[Read more about optimizing Laravel →](https://laravel.com/docs/12.x/deployment#optimization)
+
+## php artisan config:cache
 This command caches all configuration files into a single file, which can then be quickly loaded by Laravel. Once the configuration is cache, the `.env` file will no longer be loaded.
 
-[Read more about configuration caching →](https://laravel.com/docs/11.x/configuration#configuration-caching)
+[Read more about configuration caching →](https://laravel.com/docs/12.x/configuration#configuration-caching)
 
-### php artisan route:cache
+## php artisan route:cache
 This command caches the routes, dramatically decrease the time it takes to register all of your application's routes. After running this command, your cached routes file will be loaded on every request.
 
-[Read more about route caching →](https://laravel.com/docs/11.x/routing#route-caching)
+[Read more about route caching →](https://laravel.com/docs/12.x/routing#route-caching)
 
-### php artisan view:cache
+## php artisan view:cache
 This command caches all of the views in your application, which can greatly decrease the time it takes to render your views.
 
-[Read more about view caching →](https://laravel.com/docs/11.x/views#optimizing-views)
+[Read more about view caching →](https://laravel.com/docs/12.x/views#optimizing-views)
 
-### php artisan event:cache
+## php artisan event:cache
 This command creates a manifest of all your application's events and listeners, which can greatly speed up the process of registering them with Laravel.
 
-[Read more about event caching →](https://laravel.com/docs/11.x/events#event-discovery-in-production)
+[Read more about event caching →](https://laravel.com/docs/12.x/events#event-discovery-in-production)
+
+## Debugging the AUTORUN script
+It's very important to understand the nature of how containerized environments work when debugging the AUTORUN script. In some cases, some users may become frustrated when they push an update but their changes are never deployed.
+
+In most cases, this is due to a bug in their application code that causes a migration or some other process to fail.
+
+::note
+If a failure occurs in the Laravel Automations script, it will exit with a non-zero exit code -- preventing the container from starting.
+::
+
+If you are experiencing issues, you can enable the `AUTORUN_DEBUG` environment variable to get more detailed ouput of what could be going wrong.
+
+If you need even more information, you can set `LOG_OUTPUT_LEVEL` to `debug` to get **A TON** of output of what's exactly happening.
+
+### Preventing issues with the AUTORUN script
+- Ensure you are running the latest version of `serversideup/php`
+- Ensure you have dependencies installed before calling this script
+- Use automated testing to catch issues before deploying

docs/content/docs/5.customizing-the-image/3.adding-your-own-start-up-scripts.md

@@ -37,11 +37,6 @@ Anything in the `/etc/entrypoint.d` directory are scripts that are intended to r
 
 Instead, learn about [using S6 overlay](/docs/guide/using-s6-overlay) so your services can be properly initialized and monitored. See the [S6 Overylay project](https://github.com/just-containers/s6-overlay) for more details on how to write your own S6 service.
 
-## Don't use `exit 0` in your script
-If you use `exit 0` in your script, it will stop the execution of the rest of the entrypoint scripts. We recommend using `return 0` instead. [See this discussion](https://github.com/serversideup/docker-php/issues/481#issuecomment-2463082306) for more details on why.
-
-Long story short, we don't use subshells to execute your scripts, so `exit 0` will not work as expected. We do this because we want to ensure your script has access to the environment variables that are set in the entrypoint scripts.
-
 ## Example: Create a custom entrypoint script
 In this example, let's create a `99-my-script.sh` so it executes after all the other default scripts.
 

docs/content/docs/7.reference/1.environment-variable-specification.md

@@ -20,7 +20,9 @@ We like to customize our images on a per app basis using environment variables.
 `APACHE_THREAD_LIMIT`<br />*Default: "64"*|Set the maximum configured value for ThreadsPerChild for the lifetime of the Apache httpd process. (<a target="_blank" href="https://httpd.apache.org/docs/2.4/mod/mpm_common.html#threadlimit">Official docs</a>)|fpm-apache
 `APACHE_THREADS_PER_CHILD`<br />*Default: "25"*|This directive sets the number of threads created by each child process. (<a target="_blank" href="https://httpd.apache.org/docs/2.4/mod/mpm_common.html#threadsperchild">Official docs</a>)|fpm-apache
 `APP_BASE_DIR`<br />*Default: "/var/www/html"*|Change this only if you mount your application to a different directory within the container. ℹ️ Be sure to change `NGINX_WEBROOT`, `APACHE_DOCUMENT_ROOT`, `UNIT_WEBROOT`, etc if it applies to your use case as well.|all
+`AUTORUN_DEBUG`<br />*Default: "false"*|Enable debug mode for the Laravel automations. | all
 `AUTORUN_ENABLED`<br />*Default: "false"*|Enable or disable all automations. It's advised to set this to `false` in certain CI environments (especially during a composer install). If this is set to `false`, all `AUTORUN_*` behaviors will also be disabled.| all
+`AUTORUN_LARAVEL_OPTIMIZE`<br />*Default: "false"*|Automatically run "php artisan optimize" on container, attempting to `--except` in Laravel > `v11.38.0` (<a target="_blank" href="https://laravel.com/docs/11.x/deployment#optimization">Official docs</a>) <br />ℹ️ Requires `AUTORUN_ENABLED = true` to run. | all
 `AUTORUN_LARAVEL_CONFIG_CACHE`<br />*Default: "true"*|Automatically run "php artisan config:cache" on container start. <br />ℹ️ Requires `AUTORUN_ENABLED = true` to run.| all
 `AUTORUN_LARAVEL_EVENT_CACHE`<br />*Default: "true"*|Automatically run "php artisan event:cache" on container start. <br />ℹ️ Requires `AUTORUN_ENABLED = true` to run.| all
 `AUTORUN_LARAVEL_MIGRATION`<br />*Default: "true"*|Automatically run `php artisan migrate --force` on container start.  <br />ℹ️ Requires `AUTORUN_ENABLED = true` to run.| all

src/common/etc/entrypoint.d/0-container-info.sh

@@ -4,9 +4,22 @@ if [ "$SHOW_WELCOME_MESSAGE" = "false" ] || [ "$LOG_OUTPUT_LEVEL" = "off" ] || [
         echo "👉 $0: Container info was display was skipped."
     fi
     # Skip the rest of the script
-    return 0
+    exit 0
 fi
 
+# Get OPcache status
+PHP_OPCACHE_STATUS=$(php -r 'echo ini_get("opcache.enable");')
+
+if [ "$PHP_OPCACHE_STATUS" = "1" ]; then
+    PHP_OPCACHE_MESSAGE="✅ Enabled"
+else
+    PHP_OPCACHE_MESSAGE="❌ Disabled"
+fi
+
+# Get memory limits
+MEMORY_LIMIT=$(php -r 'echo ini_get("memory_limit");')
+UPLOAD_LIMIT=$(php -r 'echo ini_get("upload_max_filesize");')
+
 echo '
 --------------------------------------------------------------------
  ____                             ____  _     _        _   _
@@ -17,32 +30,33 @@ echo '
                                                             |_|
 
 Brought to you by serversideup.net
---------------------------------------------------------------------'
-
-PHP_OPCACHE_STATUS=$(php -r 'echo ini_get("opcache.enable");')
-
-if [ "$PHP_OPCACHE_STATUS" = "1" ]; then
-    PHP_OPCACHE_MESSAGE="✅ Enabled"
-else
-    PHP_OPCACHE_MESSAGE="❌ Disabled"
-fi
+--------------------------------------------------------------------
 
-echo '
-🙌 To support Server Side Up projects visit:
-https://serversideup.net/sponsor
+📚 Documentation: https://serversideup.net/php/docs
+💬 Get Help: https://serversideup.net/php/community
+🙌 Sponsor: https://serversideup.net/sponsor
 
 -------------------------------------
 ℹ️ Container Information
--------------------------------------'
-echo "
-OS:            $(. /etc/os-release; echo "${PRETTY_NAME}")
-Docker user:   $(whoami)
-Docker uid:    $(id -u)
-Docker gid:    $(id -g)
-OPcache:       $PHP_OPCACHE_MESSAGE
-PHP Version:   $(php -r 'echo phpversion();')
-Image Version: $(cat /etc/serversideup-php-version)
-"
+-------------------------------------
+📦 Versions
+• Image:         '"$(cat /etc/serversideup-php-version)"'
+• PHP:           '"$(php -r 'echo phpversion();')"'
+• OS:            '"$(. /etc/os-release; echo "${PRETTY_NAME}")"'
+
+👤 Container User
+• User:          '"$(whoami)"'
+• UID:           '"$(id -u)"'
+• GID:           '"$(id -g)"'
+
+⚡ Performance
+• OPcache:       '"$PHP_OPCACHE_MESSAGE"'
+• Memory Limit:  '"$MEMORY_LIMIT"'
+• Upload Limit:  '"$UPLOAD_LIMIT"'
+
+🔄 Runtime
+• Docker CMD:     '"$DOCKER_CMD"'
+'
 
 if [ "$PHP_OPCACHE_STATUS" = "0" ]; then
     echo "👉 [NOTICE]: Improve PHP performance by setting PHP_OPCACHE_ENABLE=1 (recommended for production)."

src/common/etc/entrypoint.d/1-log-output-level.sh

@@ -5,7 +5,7 @@ if [ "$DISABLE_DEFAULT_CONFIG" = true ]; then
     if [ "$LOG_OUTPUT_LEVEL" = "debug" ]; then
         echo "👉 $script_name: DISABLE_DEFAULT_CONFIG does not equal \"false\", so debug mode will NOT be automatically set."
     fi
-    return 0 # Exit if DISABLE_DEFAULT_CONFIG is true
+    exit 0 # Exit if DISABLE_DEFAULT_CONFIG is true
 fi
 
 #######################################