Download the PHP package yntech/domain-forge without Composer

Domain Forge

Domain Forge is a powerful Laravel package that streamlines the creation of domain modules following Hexagonal Architecture (Ports & Adapters) and Domain-Driven Design (DDD) principles. Generate complete, production-ready domain structures with a single command.

🌟 Features

• ✅ Complete DDD Structure - Automatically generates Application, Domain, and Infrastructure layers
• ✅ Value Objects - Rich domain models with validation and type safety
• ✅ Native PHP Enums - First-class support for PHP 8.1+ enums with helper methods
• ✅ Auto-generated IDs - Smart UUID/ULID generation for entity identifiers
• ✅ Type Safety - Nullable types, primitives, and enum support
• ✅ Customizable Stubs - Publish and modify templates to fit your needs
• ✅ Automatic Mappers - Eloquent ↔ Domain entity mappers
• ✅ Smart Validation - Password hashing, timestamp handling, and more
• ✅ Rollback Support - Automatic cleanup on errors
• ✅ Permission Checks - Validates write permissions before generation

📋 Requirements

• PHP 8.1 or higher
• Laravel 10.x or 11.x or higher
• Composer

🚀 Installation

Install the package via Composer:

⚙️ Configuration

1. Configure Base Structure

Run the installation command to set up the base structure:

2. Update Composer Autoload

Add the following to your composer.json in the autoload.psr-4 section:

3. Refresh Autoload

📚 Usage

Basic Domain Generation

Create a simple domain module:

This generates:

Domain with Properties

Generate a domain with value objects:

Generated Value Objects:

• ProductName (string)
• ProductPrice (float)
• ProductStock (int)
• ProductDescription (nullable string)

Entity Structure:

🎯 Property Types

Supported Types

Nullable Types

Add ? prefix for nullable properties:

Generated Value Object:

🔢 Enum Support

Creating Enums

Use the enum[value1|value2|value3] syntax:

Generated Enum Structure

File: src/Contexts/Order/Domain/Enums/OrderStatus.php

Using Enums in Your Code

Enum Examples

🆔 Auto-Generated IDs

String IDs (UUID)

When you define an id:string property, Domain Forge automatically generates UUID methods:

Generated UserId Value Object:

Entity create() method excludes ID:

Integer IDs (Auto-increment)

For database auto-increment IDs:

Generated ProductId Value Object:

🔐 Special Property Types

Password Fields

Properties containing "password" get special hashing methods:

Generated UserPassword Value Object:

Usage:

Timestamp Fields

Properties ending with _at are treated as timestamps:

These use fromString() or fromNullableString() methods automatically in fromPrimitives().

🎛️ Command Flags

--props

Define entity properties with their types:

--skip-model

Skip Laravel Eloquent model and migration generation:

Use case: When you don't need database persistence or already have the model.

🎨 Customization with Stubs

Publishing Stubs

Publish stub templates to your project:

This creates:

Customizing Stubs

Edit any stub file to change the generated code structure. For example, add timestamps to all entities:

Edit: stubs/domain-forge/entity.stub

Available Stub Variables

Each stub supports different replacement variables:

entity.stub:

• {{ namespace }} - Full namespace
• {{ className }} - Class name
• {{ imports }} - Value Object/Enum imports
• {{ constructorParams }} - Constructor parameters
• {{ getters }} - Getter methods
• {{ createParams }} - create() parameters
• {{ createArgs }} - create() arguments
• {{ fromPrimitivesParams }} - fromPrimitives() parameters
• {{ fromPrimitivesArgs }} - fromPrimitives() arguments

value-object.stub:

• {{ namespace }}
• {{ className }}
• {{ type }} - Property type
• {{ additionalMethods }} - Generated methods

enum.stub:

• {{ namespace }}
• {{ className }}
• {{ cases }} - Enum cases
• {{ allMethod }} - all() method
• {{ fromStringMethod }} - Conversion methods

Force Overwrite Stubs

🗺️ Generated Mappers

When generating a domain with properties (and without --skip-model), Domain Forge creates a mapper:

File: src/Contexts/User/Infrastructure/Persistence/Mappers/UserMapper.php

Usage in Repository:

📖 Real-World Examples

E-Commerce Product

User Management System

Blog Post

Support Ticket System

Invoice System

🛡️ Error Handling & Rollback

Domain Forge includes automatic rollback on errors:

Output:

Permission Validation

Before generating, Domain Forge checks:

• Write permissions on src/Contexts/
• Write permissions on bootstrap/providers.php
• Directory creation capabilities

Example error:

📊 Generation Summary

After successful generation, you'll see a detailed summary:

🔧 Advanced Usage

Foreign Keys

Use *_id properties for foreign keys (they won't auto-generate):

• author_id:string → Uses fromString() (no generate())
• category_id:int → Uses fromInt() (no generate())

Combining Features

This creates:

• ✅ Auto-generated id
• ✅ Foreign key customer_id (no generation)
• ✅ Enum status
• ✅ Nullable notes and paid_at
• ✅ Timestamp created_at
• ❌ No Eloquent model

📝 Best Practices

1. Property Naming

2. Enum Values

3. Nullable Usage

Use nullable only when truly optional:

4. ID Strategy

Choose consistent ID strategy per project:

🎯 Domain-Driven Design Tips

Aggregates

Create separate domains for aggregates:

Value Objects

Rich domain models emerge from proper value objects:

Domain Events

Add events to your domain entities (manual step):

🐛 Troubleshooting

Error: "No write permissions"

Error: "Class not found"

Enum ValueError

Property validation errors

Ensure property names follow rules:

• Start with lowercase letter
• Only alphanumeric and underscores
• No spaces or special characters

🚧 Roadmap

v3.1 (Planned)

• [ ] --dry-run flag for preview
• [ ] Duplicate module detection
• [ ] Controller generation
• [ ] DTO generation
• [ ] Smart validations in ValueObjects

v3.2 (Planned)

• [ ] Test generation
• [ ] Event generation
• [ ] Command/Query handlers
• [ ] GraphQL support

Future

• [ ] Multi-language support
• [ ] Custom templates per project
• [ ] Migration generator from props
• [ ] Interactive mode

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

Running Tests

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Credits

Created and maintained by Allmacht.

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

⭐ Show Your Support

If you find this package helpful, please consider giving it a ⭐ on GitHub!

Made with ❤️ by Allmacht