Architecture Laravel Package

Getting Started

Read the compatibility matrix before you write any code. The last tagged release is from April 2018, which puts the package in the Laravel 5.5–5.8 / PHP 7.1–7.2 era. On Laravel 9+, PHP 8, or anything using the newer container and console APIs, assume breakage until proven otherwise. If you still want to evaluate it, do so in a throwaway Laravel 5.8 app first.

Minimal steps:

1. composer require phpno1/architecture in a scratch project pinned to a period-appropriate Laravel version.
2. If the package predates package auto-discovery, register its service provider manually in config/app.php under providers, and any facade aliases under aliases.
3. Publish its assets: php artisan vendor:publish --provider="Phpno1\Architecture\...ServiceProvider". This is where the package's opinions live — read every published config file before touching your app.
4. Run php artisan list and filter for the package's namespace. The generators are the real documentation here; the names tell you what layers the author expects (make:repository, make:service, make:criteria, make:module, or similar).
5. Generate one complete vertical slice — a single module or bounded context — and read every file it produces. That skeleton is the fastest possible explanation of the architecture.

First use case: scaffold one trivial CRUD feature (e.g. Post) end-to-end through the generated layers, then trace a single request from controller → service → repository → model. If that trace feels natural, the architecture fits your team; if it feels like ceremony, stop there.

Implementation Patterns

The package is a scaffolding and layering toolkit, not a runtime library. Expect it to provide base classes and generators around a Domain / Application / Infrastructure / Presentation split:

• Generators as the workflow. Every feature starts with a generator command rather than hand-created directories. Keep the generated structure consistent across modules — the value is uniformity, and hand-editing it away defeats the point.
• Repository + interface binding. Typical shape: a Repository contract in the domain layer, an Eloquent implementation in infrastructure, bound in a per-module service provider. Keep the binding in a dedicated provider per module so you can swap implementations in tests.
• Base service classes. Business logic sits in services that depend on repository interfaces, not on Eloquent. Controllers stay thin: validate → call service → transform response.
• Criteria / specification objects. Where the package offers query criteria, use them for filtered listing endpoints instead of bolting scopes onto models. This keeps query logic testable without a database.
• Transformers / presenters. API responses should pass through the package's transformer layer rather than returning models directly — this is usually where the package adds the most day-to-day value.
• Layer-aware exception handling. Map domain exceptions to HTTP responses in one place (usually an exception handler or a middleware the package registers). Don't let infrastructure exceptions leak into controllers.

Integration tips:

• Isolate framework code at the edges. Keep Illuminate\* imports out of your domain and application directories; do the mapping between Eloquent models and domain objects inside the repository implementation.
• Write one feature test per layer boundary. The layering means you can unit-test services with an in-memory repository and integration-test the repository against a real database.
• If the package's base classes are too opinionated, copy them into your app/ namespace and delete the dependency. You get the architecture without the version lock — for a 2018 package this is usually the better outcome.

Gotchas and Tips

• Maintenance risk is the headline. 63 stars, zero dependents, no release since April 2018. Treat it as an abandoned reference implementation. Budget for a fork or an in-house copy, not for upstream fixes.
• License is NOASSERTION. The repository has a license file Composer can't classify. Before commercial use, read it manually — if it's unclear or missing, get written clarification or don't ship it.
• Auto-discovery may be absent. Older packages often require manual provider registration; a silent Class not found after composer require almost always means this.
• Generators overwrite. Run them on a clean working tree. Commit before every generator invocation and diff the output — many scaffolds silently replace existing files.
• Config caching hides changes. After publishing or editing package config, run php artisan config:clear. Stale cached config is the most common "the package is ignoring my settings" cause.
• Debugging layer wiring: dump the container's resolved bindings (app()->getBindings() or php artisan tinker) to confirm your repository interface points at the implementation you expect. Provider registration order matters — a later provider can rebind and silently win.
• Extension points to look for first: config-driven class mappings (base repository/service/transformer overrides) and any bindings array in the published config. Overriding via config is far safer than editing vendor files.
• Don't fight the architecture. If you need plain CRUD and the package insists on aggregates, criteria, and four layers per table, the ceremony cost will exceed the benefit. Use it as a template, extract the good parts, and move on.

Verdict for day-to-day use: adopt the ideas (layered modules, repository contracts, generators for consistency) rather than the package. If you do install it, pin your PHP and Laravel versions, fork it into your VCS, and treat the source as your documentation.