PHPackages                             sbasu/laravel-actuator - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. sbasu/laravel-actuator

ActiveLibrary[Logging & Monitoring](/categories/logging)

sbasu/laravel-actuator
======================

Spring Boot Actuator-like monitoring and management for Laravel applications

v1.0.4(today)01↑2900%MITPHPPHP ^8.1

Since Jun 27Pushed today1 watchersCompare

[ Source](https://github.com/sbasu/laravel-actuator)[ Packagist](https://packagist.org/packages/sbasu/laravel-actuator)[ Docs](https://github.com/sbasu/laravel-actuator)[ RSS](/packages/sbasu-laravel-actuator/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (3)Versions (6)Used By (0)

Laravel Actuator
================

[](#laravel-actuator)

Spring Boot Actuator-like monitoring endpoints for Laravel applications.

[![Latest Version on Packagist](https://camo.githubusercontent.com/44d05775484008ceb547157ff6a7d5091fd4b681598aaf1d5b7a36ba2121b304/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73626173752f6c61726176656c2d6163747561746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/sbasu/laravel-actuator)[![License](https://camo.githubusercontent.com/81c6bef30664de8226d9e7ac626b23f142ba49a43d5c6db9b3aa7efdaaa3b76f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f73626173752f6c61726176656c2d6163747561746f722e7376673f7374796c653d666c61742d737175617265)](https://github.com/sbasu/laravel-actuator/blob/main/LICENSE)[![PHP Version](https://camo.githubusercontent.com/c3d372b55ac2d4fcf386a178e11d9788310097b35f3893cf3daae574b6b4cd3e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d626c75652e7376673f7374796c653d666c61742d737175617265)](https://www.php.net/)[![Laravel Version](https://camo.githubusercontent.com/061cda43f6498b46f13861246063c80a5b8c2e0702fa147ea322880a8e4a66d6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d25354531302e302d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://laravel.com)

Overview
--------

[](#overview)

Laravel Actuator provides production-ready HTTP endpoints to monitor and manage your Laravel application. Inspired by [Spring Boot Actuator](https://spring.io/guides/gs/actuator-service/), it brings enterprise-grade monitoring to Laravel.

Get instant visibility into your app's health, performance metrics, and configuration.

Why Laravel Actuator?
---------------------

[](#why-laravel-actuator)

- **Production Ready** — Know your app's health in real-time
- **Kubernetes Compatible** — Built for container orchestration (liveness/readiness probes)
- **Zero Configuration** — Works out of the box with sensible defaults
- **Comprehensive Health Checks** — Database, cache, queue, disk space
- **Live Metrics** — Memory usage, request timing, database statistics
- **DevOps Friendly** — Standard endpoints for monitoring systems and dashboards
- **Spring Boot Compatible** — Familiar if you know Spring Boot Actuator

Requirements
------------

[](#requirements)

- **PHP:** 8.1 or higher
- **Laravel:** 10, 11, 12, or 13+
- **Composer:** For package installation

Installation
------------

[](#installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require sbasu/laravel-actuator
```

### Step 2: Publish Configuration (Required)

[](#step-2-publish-configuration-required)

```
php artisan vendor:publish --tag=actuator-config
```

This creates `config/actuator.php` in your application where you can customize behavior.

### Step 3: Verify Installation

[](#step-3-verify-installation)

Start your Laravel server:

```
php artisan serve
```

Test the health endpoint:

```
curl http://localhost:8000/actuator/health
```

You should see a JSON response with status `"UP"`.

Usage
-----

[](#usage)

Once installed and configured, your Laravel app automatically has monitoring endpoints available.

### 1. Health Check Endpoint

[](#1-health-check-endpoint)

Check if your application and all dependencies are healthy.

**Request:**

```
curl http://localhost:8000/actuator/health
```

**Response:**

```
{
  "status": "UP",
  "components": {
    "database": {
      "status": "UP",
      "timestamp": "2026-06-27T10:34:14Z",
      "details": {
        "database": "mysql",
        "driver": "sqlite",
        "host": "localhost",
        "connection": "connected"
      }
    },
    "disk_space": {
      "status": "UP",
      "timestamp": "2026-06-27T10:34:14Z",
      "details": {
        "free_bytes": 84775305216,
        "total_bytes": 881433005216,
        "used_bytes": 2659151872,
        "percentage_used": 3.04,
        "free": "78.95 GB",
        "total": "881.43 GB",
        "path": "/"
      }
    },
    "cache": {
      "status": "UP",
      "timestamp": "2026-06-27T10:34:14Z",
      "details": {
        "driver": "database",
        "accessible": true
      }
    },
    "queue": {
      "status": "UP",
      "timestamp": "2026-06-27T10:34:14Z",
      "details": {
        "driver": "database",
        "connected": true
      }
    }
  },
  "timestamp": "2026-06-27T10:34:14Z"
}
```

**Use Cases:**

- Kubernetes liveness probes (restart unhealthy pods)
- Kubernetes readiness probes (route traffic only to ready pods)
- Load balancer health checks
- Monitoring dashboards
- CI/CD deployment verification

---

### 2. Metrics Endpoint

[](#2-metrics-endpoint)

List available performance metrics and monitoring data.

**Request:**

```
curl http://localhost:8000/actuator/metrics
```

**Response:**

```
{
  "names": [
    "actuator.memory",
    "actuator.request",
    "actuator.database"
  ]
}
```

**Use Cases:**

- Integration with Prometheus/Grafana
- Performance monitoring
- Identifying bottlenecks
- Tracking resource usage

---

### 3. Application Info Endpoint

[](#3-application-info-endpoint)

Get metadata about your application.

**Request:**

```
curl http://localhost:8000/actuator/info
```

**Response:**

```
{
  "app": {
    "name": "Laravel",
    "version": "1.0.0",
    "description": "",
    "environment": "local",
    "debug": true
  },
  "actuator": {
    "version": "1.0.0",
    "package": "sbasu/laravel-actuator"
  }
}
```

**Use Cases:**

- Verify deployment version
- Check environment configuration
- CI/CD pipeline information
- Application identification

---

### 4. Environment Variables Endpoint

[](#4-environment-variables-endpoint)

View environment configuration. **Disabled by default for security.**

#### Enabling the Endpoint

[](#enabling-the-endpoint)

Follow these steps to enable (development environments only):

**Step 1:** Open your `.env` file

```
# macOS/Linux
nano .env

# Windows
notepad .env
```

**Step 2:** Add this line

ACTUATOR\_SHOW\_ENV=true

**Step 3:** Restart your server

```
php artisan serve
```

**Step 4:** Test the endpoint

```
curl http://localhost:8000/actuator/env
```

#### Example Response

[](#example-response)

```
{
  "APP_NAME": "Laravel",
  "APP_ENV": "local",
  "APP_DEBUG": "true",
  "APP_URL": "http://localhost:8000",
  "DB_CONNECTION": "sqlite",
  "DB_DATABASE": "/full/path/to/database.sqlite",
  ...
}
```

#### ⚠️ Security Warning

[](#️-security-warning)

**NEVER enable this endpoint in production!**

Environment variables may contain:

- Database passwords
- API keys
- Encryption keys
- OAuth tokens
- Third-party service credentials

**Only enable in development environments.**

---

Configuration
-------------

[](#configuration)

Edit `config/actuator.php` to customize the package behavior:

```
return [
    // URI prefix for all endpoints
    'path' => env('ACTUATOR_PATH', 'actuator'),

    // Middleware applied to actuator endpoints
    'middleware' => ['api'],

    // Enable/disable individual health indicators
    'indicators' => [
        'database' => true,
        'disk_space' => true,
        'cache' => true,
        'queue' => true,
    ],

    // Metrics collection settings
    'metrics' => [
        'enabled' => true,
        'sample_rate' => 1.0,
    ],

    // Show detailed health information in responses
    'show_details' => true,

    // Show environment variables (disabled by default for security)
    'show_env' => env('ACTUATOR_SHOW_ENV', false),

    // Log all actuator requests
    'log_access' => false,
];
```

### Configuration Options

[](#configuration-options)

OptionDefaultPurpose`path``actuator`URI prefix for endpoints`middleware``['api']`Middleware to apply`indicators.database``true`Enable database health check`indicators.disk_space``true`Enable disk space check`indicators.cache``true`Enable cache health check`indicators.queue``true`Enable queue health check`show_details``true`Show detailed health info`show_env``false`Enable environment endpoint`log_access``false`Log endpoint requests---

Real-World Examples
-------------------

[](#real-world-examples)

### Kubernetes Deployment

[](#kubernetes-deployment)

```
apiVersion: apps/v1
kind: Deployment
metadata:
  name: laravel-app
spec:
  template:
    spec:
      containers:
      - name: app
        image: laravel-app:latest
        ports:
        - containerPort: 8000

        # Check if pod is alive
        livenessProbe:
          httpGet:
            path: /actuator/health
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 10
          timeoutSeconds: 5
          failureThreshold: 3

        # Check if pod is ready for traffic
        readinessProbe:
          httpGet:
            path: /actuator/health
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 5
          timeoutSeconds: 3
          failureThreshold: 3
```

### Docker Health Check

[](#docker-health-check)

```
FROM php:8.3-cli

COPY . /app
WORKDIR /app

RUN composer install

# Health check every 30s
HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 \
  CMD curl -f http://localhost:8000/actuator/health || exit 1

CMD ["php", "artisan", "serve", "--host=0.0.0.0"]
```

### Prometheus Monitoring

[](#prometheus-monitoring)

```
# prometheus.yml
scrape_configs:
  - job_name: 'laravel-app'
    metrics_path: '/actuator/metrics'
    static_configs:
      - targets: ['localhost:8000']
    scrape_interval: 30s
```

### Load Balancer Health Check (Nginx)

[](#load-balancer-health-check-nginx)

```
upstream laravel {
    server laravel-app-1:8000;
    server laravel-app-2:8000;
    server laravel-app-3:8000;

    # Check health regularly
    check interval=3000 rise=2 fall=5 timeout=1000 type=http;
    check_http_send "GET /actuator/health HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx;
}

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://laravel;
    }
}
```

---

Endpoints Reference
-------------------

[](#endpoints-reference)

EndpointMethodPurposeReturnsStatus`/actuator/health`GETApplication healthJSON with status200/503`/actuator/metrics`GETAvailable metricsJSON array200`/actuator/info`GETApp informationJSON metadata200`/actuator/env`GETEnvironment variablesJSON config200/403---

Security Best Practices
-----------------------

[](#security-best-practices)

### Health Endpoints

[](#health-endpoints)

- ✅ Public by default (no authentication required)
- ✅ No sensitive data exposed
- ✅ Safe to expose to monitoring systems
- ✅ Include in Kubernetes probes

### Environment Endpoint

[](#environment-endpoint)

- ⚠️ **Disabled by default** for security
- ⚠️ Only enable in development environments
- ⚠️ Never enable in production
- ⚠️ Can expose sensitive configuration

### Protecting Endpoints

[](#protecting-endpoints)

If you want authentication on actuator endpoints, edit `config/actuator.php`:

**Option 1: Require API Authentication**

```
'middleware' => ['api', 'auth:api'],
```

**Option 2: Rate Limiting**

```
'middleware' => ['api', 'throttle:60,1'],
```

**Option 3: Custom Middleware**

```
'middleware' => ['api', App\Http\Middleware\ActuatorAuth::class],
```

---

Troubleshooting
---------------

[](#troubleshooting)

### Endpoints Return 404

[](#endpoints-return-404)

**Problem:** Getting "Route not found" when accessing endpoints

**Solution:** You must publish the configuration first

```
php artisan vendor:publish --tag=actuator-config
```

Then restart your server.

---

### Config File Not Found

[](#config-file-not-found)

**Problem:** `config/actuator.php` doesn't exist

**Solution:** Run the publish command

```
php artisan vendor:publish --tag=actuator-config
```

---

### Database Shows DOWN

[](#database-shows-down)

**Problem:** Health check returns database status as DOWN

**Solution:** Check your database connection

```
# Check .env file
cat .env | grep DB_

# Test database connection
php artisan tinker
>>> DB::connection()->getPdo();
```

---

### Cannot Enable /env Endpoint

[](#cannot-enable-env-endpoint)

**Problem:** Still get 403 when `ACTUATOR_SHOW_ENV=true`

**Solution:** Restart your server after editing `.env`

```
# Stop and restart
php artisan serve
```

```
## Reporting Issues

Found a bug or have a suggestion?

- **🐛 Report Bugs:** [GitHub Issues](https://github.com/sbasu/laravel-actuator/issues/new?template=bug_report.md)
- **✨ Request Features:** [GitHub Issues](https://github.com/sbasu/laravel-actuator/issues/new?template=feature_request.md)
- **💬 Ask Questions:** [GitHub Discussions](https://github.com/sbasu/laravel-actuator/discussions)

Please include details like:
- Laravel and PHP version
- Steps to reproduce
- Expected vs actual behavior
- Error messages or logs

The more information you provide, the faster we can help!

```

---

Roadmap
-------

[](#roadmap)

This is the first in a series of Spring Boot → Laravel packages bringing enterprise patterns to Laravel:

- ✅ **Laravel Actuator** v1.0 — Health checks & monitoring
- 🔄 **Laravel Profiles** — Environment-specific configuration
- 🔄 **Laravel Repository** — Data access abstraction layer
- 🔄 **Laravel Events** — Advanced event bus
- 🔄 **Laravel Scheduler** — Improved task scheduling

Follow [@sbasu](https://github.com/sbasu) on GitHub for updates.

---

Support
-------

[](#support)

- **Issues:** [github.com/sbasu/laravel-actuator/issues](https://github.com/sbasu/laravel-actuator/issues)
- **Discussions:** [github.com/sbasu/laravel-actuator/discussions](https://github.com/sbasu/laravel-actuator/discussions)
- **GitHub:** [github.com/sbasu/laravel-actuator](https://github.com/sbasu/laravel-actuator)

---

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

---

License
-------

[](#license)

The MIT License (MIT). Please see [LICENSE](LICENSE) file for more information.

---

About
-----

[](#about)

Built by [Shantanu Basu](https://github.com/sbasu).

Inspired by [Spring Boot Actuator](https://spring.io/guides/gs/actuator-service/).

Made with ❤️ for the Laravel community.

###  Health Score

40

—

FairBetter than 86% of packages

Maintenance100

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

5

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1073727?v=4)[Shantanu Basu](/maintainers/sbasu)[@sbasu](https://github.com/sbasu)

---

Top Contributors

[![sbasu](https://avatars.githubusercontent.com/u/1073727?v=4)](https://github.com/sbasu "sbasu (9 commits)")

---

Tags

laravelmonitoringMetricsdevopshealth checkactuatorspring-boot

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/sbasu-laravel-actuator/health.svg)

```
[![Health](https://phpackages.com/badges/sbasu-laravel-actuator/health.svg)](https://phpackages.com/packages/sbasu-laravel-actuator)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)