README

DDD and Hexagonal (Clean) Architecture building blocks (aggregates, entities, value objects, command/query handlers, etc).

Goal

Unify patterns: All domain and application code extends or implements SeedWork abstractions, keeping the codebase consistent and predictable.
Keep the domain pure: Domain types depend only on SeedWork domain types; no framework or infrastructure in the domain layer.
Clear boundaries: Application use cases are expressed as command handlers (writes) and query handlers (reads), with primitives-only DTOs at the port boundary.

See the docs for architecture and usage details.

Architecture role

SeedWork sits between project conventions and application/domain code.

Layers

Domain layer: Extends SeedWork domain bases (AggregateRoot, Entity, ValueObject), raises DomainEvent, throws \DomainException (PHP stdlib) for domain failures, and defines repository interfaces extending Repository.
Application layer: Use case interfaces extend CommandHandler or QueryHandler and implement handle(). Handlers implement those interfaces and depend on domain repository interfaces.
Infrastructure layer: Implements Repository and optionally DomainEventBus (e.g. DeferredDomainEventBus). Controllers dispatch to use cases; middleware or similar calls DomainEventBus::publish() after handling a request.

Requirements

PHP 8.4 or later
Composer 2.x
Docker and Dev Container for development

Installation

Install the package with Composer:

composer require aseguragonzalez/php-seedwork

How to use

After installation, the library is available under the SeedWork\ namespace.

Component reference — All interfaces, base classes, and infrastructure components.
Coding standards — Conventions and do/don't guidelines.
docs/examples/BankAccount/ — Full working example (including query handlers and query repository for projections) about how to use the package.

Source and issue tracker: php-seedwork.

Built with

PHP 8.4
Composer for dependency management
PHPUnit for tests
PHPStan level max for static analysis
PHP-CS-Fixer for code style (@PhpCsFixer ruleset)

Development

If you plan to contribute, please read CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Dev container

All tooling (PHP, Composer, PHPStan, PHP-CS-Fixer, pre-commit) runs inside the dev container. Start it once from the project root:

devcontainer up --workspace-folder .

Then run any make target with:

devcontainer exec --workspace-folder . make <target>

Debugging: Xdebug listens on the default port 9003. Configure your IDE or Xdebug client accordingly.

Make targets

All targets must be run inside the dev container via devcontainer exec --workspace-folder . make <target>. Running them directly on the host will fail because the required tools (PHP, Composer, etc.) are only available inside the container.

make all — Install deps, fix code style, and run the full check pipeline.
make check — Layer boundary check + code style + static analysis + tests (no coverage). Run before every commit.
make install — Install Composer dependencies.
make cs — Check code style with PHP-CS-Fixer (dry-run).
make cs-fix — Fix code style with PHP-CS-Fixer.
make stan — Run PHPStan (level max).
make test — Run PHPUnit with coverage report in coverage/html/.
make test-no-coverage — Run PHPUnit without coverage (faster).
make test-examples — Run the BankAccount example test suite.
make clean — Remove vendor, coverage, and caches.
make create-package — Build a zip archive in dist/.
make docs-serve — Serve the documentation site locally on port 8001.

Documentation site

The documentation portal uses MkDocs Material. Dependencies are installed automatically when the dev container is created.

Serve locally:

devcontainer exec --workspace-folder . make docs-serve

Then open http://localhost:8001/php-seedwork/ in your browser. The dev container forwards port 8001 automatically; if you use VS Code with the Dev Containers extension the browser opens on its own.

The server watches for file changes and reloads the browser automatically. Press Ctrl+C to stop it.

Releasing

Releases are fully automated via semantic-release. No manual version bumps or CHANGELOG edits are needed.

Automatic: Merging to main triggers the publish.yml workflow. semantic-release analyses the commits since the last release, computes the next version following Conventional Commits, updates CHANGELOG.md, creates a git tag, and publishes a GitHub Release.
Pre-release: Trigger the prerelease.yml workflow manually (workflow dispatch) with a preid like pr-42 or beta. This creates a tagged pre-release without touching main.

Commit message convention

Prefix	Effect
`fix:`	Patch release (0.0.x)
`feat:`	Minor release (0.x.0)
`feat!:` or `BREAKING CHANGE:`	Major release (x.0.0)
`chore:`, `docs:`, `test:`	No release

The PR title is also validated against Conventional Commits in CI.

References

This package draws on the following literature and on the experience of building solid, scalable, and maintainable systems in different stacks (PHP, C#, Python, TypeScript).

Eric Evans, Domain-Driven Design: Tackling Complexity in the Heart of Software 1
Vaughn Vernon, Implementing Domain-Driven Design 2
Robert C. Martin, Clean Architecture: A Craftsman's Guide to Software Structure and Design 3
.NET Microservices: Architecture for Containerized .NET Applications 4
Architecture Patterns with Python by Harry Percival 5

aseguragonzalez / php-seedwork

Maintainers

Package info

Statistics

Security