README

Find service boundaries in Laravel monoliths using static analysis + runtime tracing.

CarvePHP is a Laravel-first toolkit that analyzes your existing monolith and produces actionable migration reports. It combines static code analysis with runtime tracing to identify service boundaries with evidence.

Status: v0.1.2-alpha — Preview release. Ready for experimentation and feedback. Not yet production-ready for automatic extraction.

Latest alpha: v0.1.2-alpha

Installation

composer require "carvephp/carve:>=0.1.0-alpha <0.2.0" --dev

After installing, publish the config and run the environment check:

php artisan carve:install
php artisan carve:doctor

Quickstart

# Static scan your codebase
php artisan carve:scan --pretty

# Build dependency graph (combines static + runtime traces)
php artisan carve:analyze

# Detect candidate service boundaries
php artisan carve:boundaries --report=carve-boundaries.md

# Generate full migration report
php artisan carve:report --output=carve-report.md

For better results, enable runtime tracing (optional):

php artisan carve:trace-install
# Follow the instructions, then:
echo "CARVE_TRACE_ENABLED=true" >> .env
php artisan migrate

Sample report snippet:

## Candidate 1: Billing
| Metric       | Value |
|--------------|-------|
| Confidence   | 85.3% |
| Cohesion     | 92.0% |
| Coupling     | 14.7% |
| Risk         | 22.1% |

**Tables:** `invoices`, `payments`, `customers`
**Controllers:** `InvoiceController`, `PaymentController`
**Why suggested:** invoices and payments co-occurred 4× in runtime traces and are both touched by billing routes.

What It Does Today

What It Does Not Do (Yet)

Requirements

• PHP 8.2+
• Laravel 11, 12, or 13
• Composer 2.x

Commands

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Static Scanner  │     │  Runtime Tracer  │     │  Command CLI    │
│  (routes, models,│     │  (middleware,    │     │  (doctor, scan, │
│   migrations,    │────▶│   listeners,     │────▶│   analyze,      │
│   db_usages)     │     │   stores)        │     │   boundaries,   │
└─────────────────┘     └─────────────────┘     │   report)       │
        │                       │                └────────┬────────┘
        ▼                       ▼                         │
┌─────────────────────────────────────────┐                │
│          Graph Builder                   │◀──────────────┘
│  (WeightedGraph + Nodes + Edges)        │
└────────────────┬────────────────────────┘
                 ▼
┌─────────────────────────────────────────┐
│        Boundary Detection                │
│  (TableAffinityClusterer + Scoring)     │
└────────────────┬────────────────────────┘
                 ▼
┌─────────────────────────────────────────┐
│           Report Writer                  │
│  (Markdown + JSON)                      │
└─────────────────────────────────────────┘

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT — see LICENSE for details.