claude-plugins/dev-tools/skills/php-dev/SKILL.md

---
name: php-dev
description: Desenvolvimento PHP moderno com Laravel, Symfony e APIs RESTful — autenticação (JWT, OAuth, Sanctum), service classes e refactorização de código legacy seguindo padrões PSR.
allowed-tools: Read, Write, Edit, Bash, mcp__mem_search_memories, mcp__context7__get-library-docs, mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments
layer: wiki
---

# PHP Fullstack Engineer

Skill para desenvolvimento PHP moderno seguindo padrões Descomplicar®.

## Contexto NotebookLM

ANTES de executar, consultar notebooks para contexto especializado:

| Notebook | ID | Consultar quando |
|----------|-----|-----------------|
| Programação | 24947ffa-0019-448a-a340-2f4a275d2eb1 | Para padrões gerais |
| Dev PerfexCRM | 80606de8-2783-4d36-b08d-5825e6f9a8da | Para contexto Perfex/CodeIgniter |

```
mcp__notebooklm__notebook_query({
  notebook_id: "24947ffa-0019-448a-a340-2f4a275d2eb1",
  query: "<adaptar ao contexto do pedido do utilizador>"
})
```

```
mcp__notebooklm__notebook_query({
  notebook_id: "80606de8-2783-4d36-b08d-5825e6f9a8da",
  query: "<adaptar ao contexto Perfex/CodeIgniter>"
})
```

Integrar insights do NotebookLM nas recomendações e decisões.

> **Regra #48:** Projectos PHP/Laravel/Symfony devem ser desenvolvidos no **container dev** (`server:"dev"`, path `/root/Dev/<projecto>`). Sincroniza automaticamente com o PC local via Syncthing.

## Quando Usar

- Criar APIs RESTful
- Implementar autenticação (JWT, OAuth, Sanctum)
- Desenvolver service classes
- Refactorizar código legacy
- Integrar com APIs externas

## Protocolo Obrigatório

### 1. Pesquisa Inicial
```
mcp__mem_search_memories "[keywords php/laravel]"
mcp__wikijs__search_pages "[framework] best practices"
mcp__context7__get-library-docs para documentação actualizada
```

### 2. Quality Gate 70+
- Funções < 50 linhas
- Classes < 500 linhas
- Cyclomatic complexity < 10
- PHPDoc em todas as funções públicas
- Type hints em parâmetros e retornos

### 3. Assinatura Obrigatória
```php
<?php
/**
 * [Nome do Ficheiro/Classe]
 *
 * @author Descomplicar® Crescimento Digital
 * @link https://descomplicar.pt
 * @copyright 2025 Descomplicar®
 */
```

## Padrões de Código

### PHP 8.1+ Features
```php
// Typed properties
private readonly string $name;

// Constructor promotion
public function __construct(
    private readonly ProductService $service
) {}

// Enums
enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

// Match expression
$result = match($status) {
    Status::Active => 'Activo',
    Status::Inactive => 'Inactivo',
};

// Named arguments
$this->service->create(
    name: $name,
    price: $price
);
```

### PSR Standards
- **PSR-1**: Basic Coding Standard
- **PSR-4**: Autoloading
- **PSR-12**: Extended Coding Style
- **PSR-7**: HTTP Message Interface
- **PSR-15**: HTTP Handlers

## Segurança (OBRIGATÓRIO)

```php
// SQL - SEMPRE prepared statements
$stmt = $pdo->prepare("SELECT * FROM users WHERE id = ?");
$stmt->execute([$id]);

// Input validation
$email = filter_var($input, FILTER_VALIDATE_EMAIL);

// Output escaping
echo htmlspecialchars($output, ENT_QUOTES, 'UTF-8');

// Password hashing
$hash = password_hash($password, PASSWORD_ARGON2ID);

// CSRF em forms
<input type="hidden" name="_token" value="<?= csrf_token() ?>">
```

## Padrão Laravel

### Controller
```php
<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Http\Requests\StoreProductRequest;
use App\Http\Resources\ProductResource;
use App\Services\ProductService;
use Illuminate\Http\JsonResponse;

/**
 * ProductController - API de Produtos
 *
 * @author Descomplicar® Crescimento Digital
 * @link https://descomplicar.pt
 * @copyright 2025 Descomplicar®
 */
class ProductController extends Controller
{
    public function __construct(
        private readonly ProductService $productService
    ) {}

    public function index(): JsonResponse
    {
        $products = $this->productService->paginate();
        return ProductResource::collection($products)->response();
    }

    public function store(StoreProductRequest $request): JsonResponse
    {
        $product = $this->productService->create($request->validated());
        return (new ProductResource($product))
            ->response()
            ->setStatusCode(201);
    }
}
```

### Service
```php
<?php

namespace App\Services;

use App\Models\Product;
use App\Repositories\ProductRepository;
use Illuminate\Pagination\LengthAwarePaginator;

/**
 * ProductService - Lógica de negócio Produtos
 *
 * @author Descomplicar® Crescimento Digital
 * @link https://descomplicar.pt
 * @copyright 2025 Descomplicar®
 */
class ProductService
{
    public function __construct(
        private readonly ProductRepository $repository
    ) {}

    public function paginate(array $filters = []): LengthAwarePaginator
    {
        return $this->repository->paginate($filters);
    }

    public function create(array $data): Product