README

Mod: Modular Development Toolkit for Laravel

Mod is a lightweight toolkit for modular development in Laravel, for you and your coding agents.

Laravel lets you organize your app however you like. Mod makes that easy without fighting the framework: start from Laravel's defaults, adopt patterns from modular or domain-driven designs where they help, and keep Laravel's own make:* commands and conventions throughout.

Created by Jasper Tey, building on the lessons from laravel-ddd and generalized for the many different ways developers and their agents organize growing Laravel applications.

A terminal watching a Laravel app grow from laravel new: an Actions folder, then modules, a versioned API in src, and a timelapse of ever more folders until it all collapses into a single index.php

Note

Mod is pre-1.0. Minor releases may change the API until 1.0.

Six built-in layouts, including modular monolith and DDD, or your own
Laravel's own generators for every file type, writing into your layout, with related files alongside
Templates and scaffolds: turn your own patterns into commands, then rename a whole cluster when the feature changes
Auto-discovery of providers, commands, listeners, migrations, factories and policies
Agent-friendly: your structure lives in code, so coding agents can look it up and preview every write. See Working with AI agents.

The full documentation is at mod.teylabs.com.

Installation

Mod requires PHP 8.3+ and Laravel 12 or 13.

composer require tey/mod
php artisan vendor:publish --tag=mod-config

Quick Start

Choose a layout in config/mod.php:

// config/mod.php
'layout' => 'modules',

Generate a model with its migration and factory, then migrate:

php artisan mod:model Knowledge:Document -mf
php artisan migrate
# -> runs 2026_10_08_120000_create_documents_table from app/Modules/Knowledge/Database/Migrations

What Mod Does

	Try it	Learn more
Layouts	`'layout' => 'modules'` in `config/mod.php`	Layouts
Generators	`mod:model Knowledge:Document --all`	Generating files
Auto-discovery	providers, commands, listeners, migrations, factories and policies, found wherever they live	Auto-discovery
Your own generators	`mod:template tool`, then `mod:tool Knowledge:Search`	Custom generators
Scaffolds	several related files from one recipe	Scaffolds
Module routes and views	`Mod::routes()`, `view('knowledge::documents.show')`	Routes
Renames	`mod:rename Knowledge:Document Knowledge:Article`	Renaming

Working with AI Agents

Conventions written in a prompt drift as an app grows. Mod keeps your structure in code, where coding agents can ask for it:

php artisan mod:list --json tells an agent where every kind of file goes.
Every command that writes files previews its plan with --dry-run --json.
Mod ships a Laravel Boost guideline, skill and read-only MCP tools. Run php artisan boost:install and choose tey/mod.

The tools are mod-inventory for configured placement, mod-plan for a command preview, and mod-survey for the app's actual structure. Call mod-survey with no arguments. It reports all classes by file type, folder and namespace, unplaced paths, class/page/route/policy references, recurring file sets, naming patterns, vendor-owned references and Git identity. It falls back to the laravel layout when none is configured.

For example, part of a survey can look like:

{
  "references": [{"from": "App\\Http\\Controllers\\WidgetController", "kind": "import", "to": "App\\Models\\Widget"}],
  "unplaced": {"count": 1, "paths": ["notes.txt"]}
}

The survey reads only base_path() and its local Git metadata. It rejects path arguments and skips discovered symlinks, .env*, storage/, keys, logs and databases, and uses vendor/ only to classify referenced classes. It returns structure, never file contents; it writes nothing and makes no network calls. See the survey contract and limits. Files larger than 1 MiB (1,048,576 bytes) are skipped before reading; skipped lists their relative paths with size-limit, and links with symlink. bootstrap/cache, public/build, public/hot and public/storage are excluded.

See Agents.

FAQ

Can I Add Mod to an Existing App?

Yes. Mod doesn't move existing files, and make:* keeps working. Start on the laravel layout and switch when you're ready.

When to Choose Mod over the Alternatives

There are several good ways to organize a Laravel app. Pick by what you need:

nwidart/laravel-modules: modules you can switch on and off, each with its own config and assets. The most established option.
InterNACHI/modular: each module as its own Composer package, close to plain Laravel, with Blade components and translations loaded per module.
laravel-ddd: mod's precursor, for domain-driven design with nothing else to learn. Mod's ddd layout keeps the same folders if you outgrow it.
Mod: your own structure, whether feature folders, vertical slices, DDD, a modular monolith or a mix, with Laravel's own make:*, generators for your team's patterns, and a structure your coding agents can read.

Mod isn't the right fit yet if you need a stable 1.0 API, per-module translations or assets, or modules you can switch on and off at runtime.

Documentation

Everything else, including configuration, production caching and the command reference, is at mod.teylabs.com.

Testing

composer test
composer analyse
composer lint

Changelog

See CHANGELOG for what has changed recently.

Contributing

See CONTRIBUTING. Questions and ideas go to Discussions.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

tey / mod

Package info

Security

Fund package maintenance!

Statistics