softpyramid / forge-status

v1.0.1 2026-09-22 00:18 UTC

Requires

• php: ^8.2
• illuminate/cache: ^10.0|^11.0|^12.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/routing: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Fakhar Zaman Khan

• real-time
• laravel
• deployment
• webhook
• status
• forge
• indicator

Published on Packagist.org on 2026-09-22 00:18 UTC

README

Real-time deployment status indicator for Laravel Forge using webhooks. Get instant visual feedback when your deployments start, succeed, or fail.

Built by Soft Pyramid — Laravel agency (Frisco, TX).

Features

• 🚀 Real-time Updates - Simple polling-based live deployment status
• 🎯 No Database Required - Uses cache only for current status
• 🔗 Webhook-driven - Receives deployment events from Laravel Forge
• 🎨 Auto-injection - Automatically appears in your Laravel layouts
• ⚙️ Configurable - Customizable polling interval and authentication
• 🖥️ Full-Screen Overlay - Prominent modal-style deployment notifications
• 🎭 Modern UI - Beautiful Tailwind CSS styling
• 📱 Responsive - Works on all device sizes
• 🔧 Zero Dependencies - No broadcasting or WebSocket setup required

Requirements

• PHP 8.2 or higher
• Laravel 10, 11, or 12
• No additional dependencies required!

Installation

composer require softpyramid/forge-status

The package will automatically register its routes and service provider. No manual configuration needed!

Configuration

1. Publish config (optional):

php artisan vendor:publish --tag=forge-status-config

2. Add to .env (optional):

FORGE_WEBHOOK_TOKEN=your-secret-token
FORGE_POLL_INTERVAL=5
FORGE_AUTH_ONLY=true

3. Register Webhook in Laravel Forge

In your Forge site settings:

1. Go to "Webhooks"
2. Add new webhook URL: https://yourdomain.com/forge-webhook
3. Optionally add token parameter: https://yourdomain.com/forge-webhook?token=your-secret-token

Usage

Auto-inject into layouts

Add the component to your layout file (e.g., resources/views/layouts/app.blade.php):

<body>
    <!-- Your content -->
    
    <x-forge-deployment-indicator />
</body>

That's it! The indicator will automatically appear when deployments start and update in real-time.

How It Works

1. Forge sends webhook POST request when deployment starts/finishes
2. Package receives webhook and stores status in cache
3. Frontend polls the status endpoint every few seconds
4. Indicator updates automatically when status changes
5. No database storage - uses cache for current status only
6. Simple and reliable - no WebSocket complexity

Laravel Version Compatibility

Laravel Version	Package Version	PHP Version
Laravel 12.x	^1.0	^8.2
Laravel 11.x	^1.0	^8.2
Laravel 10.x	^1.0	^8.1

Testing

# Run tests
composer test

# Run tests with coverage
composer test-coverage

Test the package functionality

# Test with success status (default)
php artisan forge-status:test

# Test with different statuses
php artisan forge-status:test --status=deploying
php artisan forge-status:test --status=success
php artisan forge-status:test --status=failed

This command will test all package functionality including cache storage, webhook endpoint, and status endpoint.

Then open your Laravel app in the browser to see the overlay in action!

Debugging

Check if routes are registered

php artisan forge-status:routes

This command will show you all registered Forge Status routes and verify they're working correctly.

Manual route discovery

If routes aren't auto-registered, run:

php artisan package:discover

Troubleshooting

Laravel 12 Compatibility Issues

If you encounter issues with Laravel 12, ensure you have:

1. PHP 8.2+ installed
2. Updated dependencies - run composer update
3. Cleared caches - run php artisan config:clear && php artisan cache:clear

Polling Not Working

Make sure you have:

1. Polling interval configured in your .env:

   FORGE_POLL_INTERVAL=5

2. Status endpoint is accessible at /forge-status

3. Cache is working - check your cache configuration

Webhook Not Receiving Data

Verify:

1. Webhook URL is correctly registered in Laravel Forge
2. Token verification is properly configured (if using)
3. Route is accessible - check /forge-webhook endpoint

License

MIT License. See LICENSE file for details.

Author

Fakhar Zaman Khan — Soft Pyramid · GitHub

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request