Download the PHP package hussiensulyman/modulate without Composer

Why Modulate?

Every Laravel project eventually faces the same crossroads:

• Stay monolithic → controllers call models call models, no boundaries, refactoring becomes archaeology
• Go microservices → Kubernetes, Docker, service meshes, distributed tracing — for an app with 200 users

Modulate is the third option. Your app stays a single deployable unit, but internally it's divided into strict, self-contained modules that can be extracted into real microservices later — without rewriting everything.

Each module owns its routes, models, migrations, services, events, and tests. Modules talk to each other only through published contracts and events. When a module needs to become its own service, you move the folder and swap the bindings. That's it.

Requirements

• PHP 8.2+
• Laravel 10 or 11

Installation

New project

Run modulate:init immediately after creating a fresh Laravel project. It cleans up the default boilerplate and sets up the modular structure:

This will:

• Generate a Shared/ module with base classes (DTOs, Exceptions, Traits, Enums, Http, Support)
• Generate an Auth/ module with User model already inside
• Move app/Models/User.php to Auth module + keep a compatibility alias in app/Models/
• Update config/auth.php to reflect the new User location (with --strict)
• Replace root routes/web.php and routes/api.php with thin comment stubs
• Delete the now-empty app/Http/Controllers/ folder
• Keep app/Http/Middleware/ with a README explaining it is for global middleware only
• Add .gitkeep + README in any emptied folders

Options:

Existing project

See docs/migration-guide.md for a step-by-step incremental adoption guide.

Quickstart

Create a module

Generated structure:

Plus a root-level tests/E2E/ folder for cross-module journey tests (generated once on first modulate:make).

Flags

Preset flags

Granular control

--add available values

--skip available values

events, listeners, resources, requests, migrations, tests, e2e

All Commands

Setup

Scaffolding

Module management

Health & integrity

CI with GitHub Actions

The reusable action works the same whether hussiensulyman/modulate is installed from Packagist or via a Composer path repository, as long as dependencies are installed before running the action.

Microservices

Use php artisan modulate:doctor to scan installed packages against known compatibility notes.

The Three Rules

1. Modules never touch each other's internals

2. Queries use contracts. Side effects use events.

3. Each module is self-contained

A module registers its own routes, migrations, and bindings through its ServiceProvider. No central wiring required.

The Shared Module

modulate:init generates a Shared/ module that provides base infrastructure for all other modules:

Rule: Shared contains no business logic, no routes, and no module-specific code — only infrastructure primitives.

Coupling Violation Detection

Detects:

• Direct Model imports across module boundaries
• Direct Service class imports not going through a contract
• Cross-module DB queries hitting another module's tables
• Missing contract bindings in a module's ServiceProvider
• Facade usage bypassing contracts (e.g. Auth::user() in a non-Auth module)
• Direct access to another module's config keys

Runs automatically on php artisan optimize when enabled. Detection combines fast regex rules and AST analysis via nikic/php-parser.

Third-Party Package Compatibility

Most Laravel packages work with Modulate without issues. The ones that generate code (Breeze, Jetstream, Filament) will place files in default Laravel locations — move them into the correct module afterward.

Packages that extend the User model (Sanctum, Spatie Permission, JWT) work fine as long as they reference the correct User class location. See docs/compatibility.md for a curated list of popular packages and their setup notes.

modulate:doctor is available and can be used in CI or locally to flag compatibility risks before deployment.

Versioning

Modulate follows Semantic Versioning. Breaking changes are always a major version bump and always come with an upgrade guide in UPGRADING.md.

Further Reading

• docs/architecture.md — philosophy, Ports & Adapters, bounded contexts
• docs/commands.md — full command reference
• docs/migration-guide.md — adopting Modulate in an existing project
• docs/microservices-extraction.md — extracting a module into a standalone service
• docs/compatibility.md — third-party package compatibility notes
• docs/github-action.md — reusable modulate:lint GitHub Action and manual CI validation
• UPGRADING.md — upgrade guides between major versions

Contributing

See CONTRIBUTING.md. Package compatibility entries in docs/compatibility.md are especially welcome as community contributions.

License

Modulate is open-sourced software licensed under the MIT license.