softpyramid/forge-status

Real-time Laravel Forge deployment status indicator via webhooks

Maintainers

Details

github.com/softpyramid/forge-status

Source

Issues

Installs: 50

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

pkg:composer/softpyramid/forge-status

1.0.0 2025-10-23 22:53 UTC

Requires

Requires (Dev)

MIT 12259999dd2cff05f09cc95512ef1512dc47ebb2

real-timelaraveldeploymentwebhookstatusforgeindicator

This package is auto-updated.

Last update: 2025-10-23 23:12:41 UTC

README

Latest Version on Packagist Total Downloads Laravel Version PHP Version

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

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

Testing

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.

Test with your data

# Test with the provided data
php artisan forge-status:test --status=success

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 - SoftPyramid

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