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

name, description, allowed-tools, layer

name	description	allowed-tools	layer
php-dev	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.	Read, Write, Edit, Bash, mcp__mem_search_memories, mcp__context7__get-library-docs, mcp__notebooklm__notebook_query, mcp__dify-kb__dify_kb_retrieve_segments	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
/**
 * [Nome do Ficheiro/Classe]
 *
 * @author Descomplicar® Crescimento Digital
 * @link https://descomplicar.pt
 * @copyright 2025 Descomplicar®
 */

Padrões de Código

PHP 8.1+ Features

// 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)

// 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

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

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