🏆 Gold Standard Module¶

The definitive reference implementation showcasing XOOPS 2026 architecture and PHP best practices.

This module serves as a living example of how to build modern XOOPS modules. Every pattern, every structure, and every code decision follows the guidelines established in the XOOPS 2026 vision.

Overview¶

The Gold Standard Module is a fully functional "Article Management" system that demonstrates:

mindmap
  root((Gold Standard))
    Architecture
      PSR-15 Middleware
      PSR-11 DI Container
      PSR-7 HTTP Messages
      Clean Architecture
    Patterns
      Repository Pattern
      Service Layer
      DTO/Value Objects
      CQRS-lite
    Quality
      100% Type Coverage
      PHPStan Level 9
      Full Test Suite
      Documentation
    Modern PHP
      PHP 8.2+
      Attributes
      Readonly Properties
      Enums

Quick Start¶

Installation¶

# Clone to modules directory
cd htdocs/modules
git clone https://github.com/xoops/goldstandard.git

# Install via Composer
cd goldstandard
composer install

# Run database migrations
php xoops_cli.php module:install goldstandard

First Steps¶

1. Navigate to Admin → Modules → Gold Standard
2. Configure basic settings
3. Create your first article
4. View on the frontend

Documentation Structure¶

📚 User Guide¶

👨‍💻 Developer Guide¶

🎨 Templates¶

📖 API Reference¶

Architecture Overview¶

flowchart TB
    subgraph Presentation["🖥️ Presentation Layer"]
        direction LR
        WEB[Web Controllers]
        API[API Controllers]
        CLI[CLI Commands]
    end

    subgraph Application["⚙️ Application Layer"]
        direction LR
        CMD[Command Handlers]
        QRY[Query Handlers]
        SVC[Application Services]
    end

    subgraph Domain["🎯 Domain Layer"]
        direction LR
        ENT[Entities]
        VO[Value Objects]
        DOM[Domain Services]
        EVT[Domain Events]
    end

    subgraph Infrastructure["🏗️ Infrastructure Layer"]
        direction LR
        REPO[Repositories]
        PERS[Persistence]
        EXT[External Services]
    end

    Presentation --> Application
    Application --> Domain
    Application --> Infrastructure
    Infrastructure --> Domain

Directory Structure¶

goldstandard/
├── src/
│   ├── Application/          # Use cases and app services
│   │   ├── Command/          # Write operations
│   │   ├── Query/            # Read operations
│   │   └── Service/          # Application services
│   ├── Domain/               # Business logic (framework-agnostic)
│   │   ├── Entity/           # Domain entities
│   │   ├── ValueObject/      # Immutable value objects
│   │   ├── Repository/       # Repository interfaces
│   │   ├── Service/          # Domain services
│   │   └── Event/            # Domain events
│   ├── Infrastructure/       # External concerns
│   │   ├── Persistence/      # Database implementations
│   │   ├── Http/             # HTTP client adapters
│   │   └── Event/            # Event dispatcher
│   └── Presentation/         # User interface
│       ├── Controller/       # Web controllers
│       ├── Api/              # REST API controllers
│       └── Cli/              # Console commands
├── config/
│   ├── module.json           # Module manifest
│   ├── services.php          # DI container config
│   ├── routes.php            # Route definitions
│   └── middleware.php        # Middleware stack
├── templates/
│   ├── frontend/             # User templates
│   ├── admin/                # Admin templates
│   └── email/                # Email templates
├── tests/
│   ├── Unit/                 # Unit tests
│   ├── Integration/          # Integration tests
│   └── Functional/           # End-to-end tests
├── migrations/               # Database migrations
└── docs/                     # Additional documentation

Key Features¶

1. Clean Architecture¶

The module implements Clean Architecture with clear separation between:

• Domain Layer - Pure business logic, no framework dependencies
• Application Layer - Use cases orchestrating domain logic
• Infrastructure Layer - Concrete implementations
• Presentation Layer - Controllers and views

2. Modern PHP 8.2+¶

<?php

declare(strict_types=1);

namespace Xoops\GoldStandard\Domain\Entity;

use Xoops\GoldStandard\Domain\ValueObject\ArticleId;
use Xoops\GoldStandard\Domain\ValueObject\ArticleTitle;
use Xoops\GoldStandard\Domain\ValueObject\ArticleContent;
use Xoops\GoldStandard\Domain\Event\ArticleCreated;

final class Article
{
    /** @var list<DomainEvent> */
    private array $domainEvents = [];

    private function __construct(
        public readonly ArticleId $id,
        private ArticleTitle $title,
        private ArticleContent $content,
        private ArticleStatus $status,
        private readonly \DateTimeImmutable $createdAt,
        private ?\DateTimeImmutable $publishedAt = null,
    ) {}

    public static function create(
        ArticleId $id,
        ArticleTitle $title,
        ArticleContent $content,
    ): self {
        $article = new self(
            id: $id,
            title: $title,
            content: $content,
            status: ArticleStatus::Draft,
            createdAt: new \DateTimeImmutable(),
        );

        $article->recordEvent(new ArticleCreated($id));

        return $article;
    }

    public function publish(): void
    {
        if ($this->status !== ArticleStatus::Draft) {
            throw new \DomainException('Only draft articles can be published');
        }

        $this->status = ArticleStatus::Published;
        $this->publishedAt = new \DateTimeImmutable();
        $this->recordEvent(new ArticlePublished($this->id));
    }

    private function recordEvent(DomainEvent $event): void
    {
        $this->domainEvents[] = $event;
    }

    /** @return list<DomainEvent> */
    public function pullDomainEvents(): array
    {
        $events = $this->domainEvents;
        $this->domainEvents = [];
        return $events;
    }
}

3. Repository Pattern¶

<?php

declare(strict_types=1);

namespace Xoops\GoldStandard\Domain\Repository;

use Xoops\GoldStandard\Domain\Entity\Article;
use Xoops\GoldStandard\Domain\ValueObject\ArticleId;

interface ArticleRepository
{
    public function nextIdentity(): ArticleId;

    public function find(ArticleId $id): ?Article;

    public function findOrFail(ArticleId $id): Article;

    /** @return list<Article> */
    public function findByStatus(ArticleStatus $status): array;

    public function save(Article $article): void;

    public function remove(Article $article): void;
}

4. Command/Query Separation¶

sequenceDiagram
    participant C as Controller
    participant CB as Command Bus
    participant CH as Command Handler
    participant R as Repository
    participant DB as Database

    C->>CB: dispatch(CreateArticleCommand)
    CB->>CH: handle(command)
    CH->>R: nextIdentity()
    R-->>CH: ArticleId
    CH->>CH: Article::create()
    CH->>R: save(article)
    R->>DB: INSERT
    CH-->>CB: ArticleId
    CB-->>C: ArticleId

Code Quality Standards¶

Testing Strategy¶

pie title Test Distribution
    "Unit Tests" : 60
    "Integration Tests" : 25
    "Functional Tests" : 10
    "E2E Tests" : 5

# Run all tests
composer test

# Run with coverage
composer test:coverage

# Run mutation testing
composer test:mutation

# Run static analysis
composer analyse

🔗 Related Documentation¶

• XOOPS Architecture
• XOOPS 2026 Architecture Vision
• Repository Pattern
• XMF Framework

Version History¶

xoops #module #goldstandard #reference #best-practices #php8 #architecture¶