Download the PHP package karim-ashraf/lara-architect without Composer

Lara Architect

Architecture Memory and Improvement Platform for Laravel

The Composer package karim-ashraf/lara-architect is the entry point. The product vision is a platform (core + UI + future integrations) — see docs/architecture/platform.md.

Lara Architect helps you generate solid structure, catch layer violations early, remember what worked, and continuously improve how your app is built — so architecture stays intentional as the codebase grows.

Lara Architect Platform — package is the entry; platform is the vision (VISION.md).

Lifecycle:

Under the hood sits a framework-agnostic ArchitectureEngine — Artisan commands are thin adapters. You can analyze a codebase with no Laravel bootstrap:

Requirements

LaraArchitect supports Laravel 11, 12 and 13 and follows the framework's own PHP requirements:

The package itself requires PHP ^8.2; when you install it into a Laravel 13 application, Composer will already enforce PHP 8.3+ through the framework. The test suite runs against all three Laravel versions in CI.

Installation

The service provider is auto-discovered. Publish the config to customize presets, namespaces and behavior:

Optionally publish the stubs to customize every generated file:

Published stubs live in stubs/lara-architect/ and always win over the package defaults.

Update the core package

Prefer --prefer-dist so Composer installs the zipball instead of cloning tags via git.

If update fails with would clobber existing tag (stale Composer VCS cache after a tag/history refresh):

You can also answer yes when Composer asks to reinstall the package.

After upgrading, skim CHANGELOG.md. Published config is deep-merged with package defaults (since 1.4.2), so newer generators keep working without a full re-publish.

Architecture Workspace UI (optional)

Install beside core for the Workspace at /architect/workspace.

Update UI later with composer update karim-ashraf/lara-architect-ui, rebuild assets, and re-publish --tag=lara-architect-ui-assets. Step-by-step: UI README.

Quick start: your first CRUD in five steps

The full walkthrough with explanations lives in docs/getting-started.md.

1. See the available presets and patterns:

2. Generate a module (add --dry-run first to preview without writing). Default is API (JsonResource + Http\Controllers\Api). Use --ui=web for Blade. Not sure which flags you want? Run the interactive wizard instead:

This creates the model (with soft deletes, UUID and filtering), migration, factory, enum (+ lang/*/enums.php translations), repository, service, query filter, store/update form requests, and either an API resource + Api controller or Blade views + web controller — all wired together and consistent with your --fields.

Int-backed enums: status:enum:int → enum ProductStatus: int with Inactive=0 / Active=1. String enums: status:enum (default).

3. Run the migration:

4. Register the routes in routes/api.php (API) or routes/web.php (web) — the command prints the exact line:

5. Use the API:

Validation, filtering, resources and the JSON envelope all work out of the box. To use a different design pattern, pass --architecture=actions (action classes + DTO instead of service + repository), set a project-wide default in the config, or hand-pick patterns with --patterns=... — details below.

The module generator

Architecture presets

A preset is just a named list of patterns in config/lara-architect.php. Built-in presets:

GoF patterns (add with --patterns=…, not Eloquent factory):

Usage examples (Strategy, State, Singleton, Abstract Factory, DDD, CQRS, Pipeline): docs/examples/design-patterns.md.

Pick one per module:

architect:feature accepts the same flags as make:module and appends the patterns listed in generation.feature_extras (policy, seeder, test by default), so one command ships a model with a passing test, a seeder wired to the factory, and a policy ready to register.

Other useful flags:

Discover what is available at any time:

Field definitions

--fields drives the migration, validation rules, casts, factory definitions, DTO properties and API resource in one go:

Supported types: string, text, integer (alias int), biginteger (alias bigint), boolean (alias bool), decimal, float, date, datetime, json, uuid, foreignid, enum. Modifiers: nullable, unique. For enums, add a backing type: status:enum (string) or status:enum:int (integer).

A unique field automatically gets Rule::unique(...) in the store request and Rule::unique(...)->ignore($this->route(...)) in the update request.

Enum fields

Declare a field as enum (e.g. status:enum) or int-backed status:enum:int. With the enum pattern enabled, the generator produces a backed enum (App\Enums\ProductStatus) that uses EnumHelpers — values(), options(), translated label(), is() / isNot(), and magic isActive()-style helpers. It also writes lang/{locale}/enums.php maps (default locales en and ar, configurable via LARA_ARCHITECT_ENUM_LOCALES). Override any helper by redeclaring it on the enum. The enum is wired through the whole module:

• the model casts the attribute to the enum ('status' => ProductStatus::class)
• the form requests validate it with Rule::enum(ProductStatus::class)
• the factory uses fake()->randomElement(ProductStatus::cases())
• the DTO property is typed with the enum, and ArchitectData hydrates it from strings

Query filters

Every preset includes the filter pattern: a ProductFilter class (extending ArchitectQueryFilter) is generated with a search() method across text fields, exact matches for booleans/integers/enums, and _min/_max (numeric) or _from/_to (date) range methods. The generated model gets the Filterable trait and the controller's index() injects the filter:

The generated controller adapts to the module

• With the service pattern, the controller injects the generated service.
• With the actions pattern, it dispatches CreateProduct::run(...) / UpdateProduct::run(...) / DeleteProduct::run(...) (with a typed DTO if the dto pattern is included).
• With neither, it uses plain Eloquent.

Extending the generator

Every pattern is a class implementing KarimAshraf\LaraArchitect\Contracts\Generator. Register your own and use it immediately:

Team conventions with architect.json

Commit an architect.json at your project root to version your team's conventions without publishing the package config. Anything under it deep-merges over config/lara-architect.php when the generator runs:

Domain / modular layouts

Namespace values support a {module} placeholder that is replaced with the model name, so you can generate into a domain-oriented structure:

Architecture lint & analysis

Generating a clean structure is half the job — keeping it clean is the other half. The engine builds a dependency graph, evaluates declarative layer rules, and reports hotspots — all through one AnalysisResult rendered as console or JSON.

The Workspace command builds a WorkspaceSnapshot read model from the engine (spec). React / Debugbar / VS Code will share that payload later.

Existing apps often have hundreds of violations. Freeze them so only new ones fail CI:

Declarative layer rules

The built-in Laravel rule pack encodes service-repository conventions (controllers must not depend on models/repositories/DB/inline validation; models must not depend on the HTTP/service layer). Override for any architecture via config or architect.json:

Rules never inspect PHP source — only the graph (nodes, edges, layers). That keeps them independent of whether extraction is regex today or AST tomorrow.

Runtime building blocks

Repository

You get all(), paginate(), find(), findOrFail(), findBy(), getBy(), create(), update(), delete(), filter() and scoped(fn ($query) => ...) for ad-hoc queries — fully generic-annotated for PHPStan/Larastan.

Soft deletes are first-class citizens:

Restore operations throw a descriptive SoftDeletesNotEnabledException when the model doesn't use the SoftDeletes trait, instead of failing silently.

Service

Write operations run inside a database transaction (disable via lara-architect.services.transactions). The service mirrors the full repository surface — including deleteMany(), deleteAll(), restore(), restoreAll(), forceDelete(), trashed() and filter() — with restored() and forceDeleted() hooks alongside created(), updated() and deleted().

Actions

Query filters

Each public method is a filter; query string parameters map onto them automatically (?price_min=100 calls priceMin('100')). Empty values and unknown parameters are ignored, and base-class methods can never be invoked from the outside. Apply a filter anywhere:

Data transfer objects

Snake_case input keys map to camelCase constructor parameters automatically, nested ArchitectData types are hydrated recursively, and backed enums are hydrated from their raw values ('status' => 'active' becomes ProductStatus::Active).

Form requests and JSON responses

JSON validation failures return a consistent envelope (status / message / errors — key names configurable). In controllers, the RespondsWithJson trait gives you respondSuccess(), respondCreated(), respondDeleted() and respondError() with the same envelope.

Configuration reference

Development

Changelog

See CHANGELOG.md for a list of notable changes in each release.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for the development setup, coding standards and pull request checklist.

License

MIT. See LICENSE.md.