giuseppe-trisciuoglio/developer-kit

Comprehensive developer toolkit providing reusable skills for Java/Spring Boot, TypeScript/NestJS/React/Next.js, Python, PHP, AWS CloudFormation, AI/RAG, DevOps, and more.

Quality

90%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Risky

Do not use without reviewing

This version of the tile failed moderation

Moderation pipeline encountered an internal error

paths:: **/*.php

Rule: PHP Project Structure

Name: giuseppe-trisciuoglio/developer-kit
Rating: 90.85333333333334 (1 reviews)
Author: giuseppe-trisciuoglio

Context

Enforce a consistent, PSR-4 compliant project structure for PHP applications (Laravel, Symfony) to maintain separation of concerns and scalability.

Guidelines

Namespace and Directory Layout

Follow PSR-4 autoloading with domain-driven organization:

project-root/
├── composer.json
├── config/                      # Framework configuration
├── public/
│   └── index.php                # Application entry point
├── src/                         # Application source (PSR-4 root: App\)
│   ├── Common/                  # Shared utilities
│   │   ├── Exception/
│   │   │   ├── BusinessException.php
│   │   │   └── ExceptionHandler.php
│   │   └── Util/
│   ├── Order/                   # Domain module: Order
│   │   ├── Controller/
│   │   │   └── OrderController.php
│   │   ├── DTO/
│   │   │   ├── OrderRequest.php
│   │   │   └── OrderResponse.php
│   │   ├── Service/
│   │   │   └── OrderService.php
│   │   ├── Repository/
│   │   │   ├── OrderRepositoryInterface.php
│   │   │   └── EloquentOrderRepository.php
│   │   └── Entity/
│   │       ├── Order.php
│   │       └── OrderStatus.php
│   └── User/                    # Domain module: User
│       ├── Controller/
│       ├── Service/
│       ├── Repository/
│       └── Entity/
├── tests/
│   ├── Unit/
│   │   └── Order/
│   │       └── OrderServiceTest.php
│   └── Feature/
│       └── Order/
│           └── OrderControllerTest.php
├── database/
│   └── migrations/
└── resources/

Layer Responsibilities

Controller/: HTTP request handling, input validation, response formatting
DTO/: Data Transfer Objects for request/response shapes
Service/: Business logic, orchestration, transaction management
Repository/: Data access abstraction (interface + implementation)
Entity/: Domain models, Eloquent models, Doctrine entities
Exception/: Custom exception classes and exception handlers

File Organization Rules

One class per file, file name must match class name
Use declare(strict_types=1) in every PHP file
Repository pattern: define interfaces in domain, implement in infrastructure
Keep controllers thin — delegate all logic to services
Group related DTOs near their controller or service
Use Enums (PHP 8.1+) for status fields and fixed option sets

Test Structure

Mirror the source structure under tests/:

tests/
├── Unit/
│   └── Order/
│       ├── OrderServiceTest.php
│       └── OrderRepositoryTest.php
└── Feature/
    └── Order/
        └── OrderControllerTest.php

Examples

✅ Good

<?php
// src/Order/DTO/OrderResponse.php

declare(strict_types=1);

namespace App\Order\DTO;

final readonly class OrderResponse
{
    public function __construct(
        public int $id,
        public string $status,
        public float $total,
    ) {}
}

❌ Bad

<?php
// src/Order.php — mixing entity, DTO, and service logic in one file

class Order
{
    // ORM mapping AND business logic AND DTO conversion
    public function toArray() { ... }
    public function process() { ... }
}