Portfolio Técnico

DDD es una aproximación al desarrollo de software que coloca el dominio de negocio en el centro de todas las decisiones técnicas. El modelo de dominio expresa las reglas y procesos del negocio en código, con un lenguaje ubicuo compartido entre desarrolladores y expertos de dominio.

El dominio completo de este portfolio

Tres bounded contexts completamente separados, cada uno con sus entidades, Value Objects y puertos:

src/Domain/
│
├── Portfolio/                              ← Bounded Context 1
│   │
│   ├── Portfolio.php                       ← Aggregate Root
│   │     Agrupa: PersonalInfo, ContactInfo,
│   │             Skill[], SocialNetwork[]
│   │
│   ├── PersonalInfo.php                    ← Value Object (readonly)
│   │     Campos: name, title, tagline, bio, location
│   │     Invariante: ningún campo obligatorio vacío
│   │     → InvalidArgumentException en constructor
│   │
│   ├── ContactInfo.php                     ← Value Object (readonly)
│   │     Campos: email, phone, github, linkedin
│   │     Invariante: email con formato válido
│   │
│   └── PortfolioRepository.php             ← Puerto
│         Contrato: find(): Portfolio
│
├── Article/                                ← Bounded Context 2
│   │
│   ├── Article.php                         ← Aggregate Root
│   │     Campos: id, title, slug, excerpt,
│   │             content, publishedAt, updatedAt
│   │
│   ├── Tag.php                             ← Value Object
│   │     name normalizado a minúsculas en constructor
│   │
│   └── ArticleRepository.php               ← Puerto
│         findAll(): Article[]
│         findBySlug(string $slug): ?Article
│
└── ExpertiseArea/                          ← Bounded Context 3
    │
    ├── ExpertiseArea.php                   ← Aggregate Root
    │     Campos: id, label, fullTitle,
    │             iconType, iconValue, category, description
    │     Factory: ExpertiseArea::fromArray(array): self
    │
    ├── ExpertiseCategory.php               ← Value Object (backed enum)
    │     arquitectura | testing | backend | tooling
    │
    ├── IconType.php                        ← Value Object (backed enum)
    │     monogram | simpleicons | url
    │
    ├── ExpertiseAreas.php                  ← Colección tipada
    │     count(): int
    │     toArray(): array  ← compatible con Twig
    │
    └── ExpertiseAreaRepository.php         ← Puerto
          Contrato: findAll(): ExpertiseAreas

Lenguaje ubicuo en la práctica

El código usa los mismos términos que usaría alguien describiendo un portfolio:

• PersonalInfo (no UserData ni ProfileRecord)
• Skill con level (no CompetencyEntity con score)
• Article con publishedAt (no Post con createdAt)
• ExpertiseArea con category (no Keyword ni Tag)

Conceptos aplicados

• Value Objects inmutables: PersonalInfo, ExpertiseCategory e IconType validan sus invariantes en el constructor. Si el id está vacío → InvalidArgumentException antes de que el objeto exista.
• Aggregate Root: ExpertiseArea es la puerta de entrada a sus Value Objects. ExpertiseAreas agrupa los 16 ExpertiseArea sin exponerlos individualmente.
• Repository interfaces en Domain: PortfolioRepository, ArticleRepository y ExpertiseAreaRepository viven en src/Domain/, nunca en Infrastructure/.
• Sin dependencias de framework: ningún archivo de src/Domain/ tiene use Symfony\... ni use Doctrine\....

Puedes explorar la estructura completa en el repositorio público en GitHub

También conocida como Ports & Adapters, separa el núcleo de aplicación de los detalles de infraestructura mediante interfaces (ports) e implementaciones concretas (adapters).

Los puertos y adaptadores de este portfolio

Este proyecto tiene 3 puertos (contratos del dominio) y 5 adaptadores (implementaciones concretas):

DOMINIO — Puertos (contratos puros, sin implementación)
──────────────────────────────────────────────────────

Domain/Portfolio/PortfolioRepository.php
  └── find(): Portfolio

Domain/Article/ArticleRepository.php
  ├── findAll(): Article[]
  ├── findBySlug(string $slug): ?Article
  ├── findById(string $id): ?Article
  └── findByTags(string[] $tags): Article[]

Domain/ExpertiseArea/ExpertiseAreaRepository.php
  └── findAll(): ExpertiseAreas

INFRAESTRUCTURA — Adaptadores de persistencia
──────────────────────────────────────────────

Infrastructure/Persistence/Json/
  │
  ├── JsonPortfolioRepository.php
  │     implementa: PortfolioRepository
  │     Lee: data/portfolio.json
  │
  ├── JsonArticleRepository.php
  │     implementa: ArticleRepository
  │     Lee: data/articles.json
  │     Cachea en memoria: múltiples llamadas = una sola lectura
  │
  └── JsonExpertiseAreaRepository.php
        implementa: ExpertiseAreaRepository
        Lee: data/expertise-areas.json
        Construye: ExpertiseAreas

INFRAESTRUCTURA — Adaptadores de presentación
──────────────────────────────────────────────

Infrastructure/Twig/
  │
  ├── MarkdownExtension.php
  │     Expone: filtro |markdown a las plantillas Twig
  │     Usa internamente: league/commonmark
  │
  └── VersionExtension.php
        Expone: función version() en Twig
        Lee: fichero VERSION del sistema de archivos

ENTRY POINTS — Controladores (solo conocen Application Services)
──────────────────────────────────────────────────────────────

Controllers/
  │
  ├── PortfolioController.php
  │     Inyecta: PortfolioService ✅
  │               ExpertiseAreaService ✅
  │     /           → portfolioService->getPortfolio() → $portfolio
  │     /contacto   → portfolioService->getPortfolio() → $portfolio
  │     /portfolio  → expertiseAreaService->getAllAsArray() → $keywords
  │     /cv         → portfolioService->getPortfolio() + cv.json directo
  │     /proyectos  → array hardcodeado (sin repositorio)
  │     /ppia       → sin dominio, solo render
  │
  └── ArticleController.php
        Inyecta: ArticleService ✅
        /code-ai          → articleService->findAll() → $articles
        /code-ai/{slug}   → articleService->findBySlug($slug) → $article

La regla clave: el controlador solo conoce el puerto

Los controllers no conocen repositorios: solo inyectan Application Services.

// ✅ PortfolioController — inyecta servicios de aplicación
public function __construct(
    private readonly PortfolioService $portfolioService,
    private readonly ExpertiseAreaService $expertiseAreaService
) {}

// ✅ ArticleController — inyecta servicio de aplicación
public function __construct(
    private readonly ArticleService $articleService
) {}

Los servicios son los que conocen los repositorios (los puertos). Los repositorios son los que conocen la infraestructura. Los controllers solo orquestan la respuesta HTTP.

Por qué JSON en lugar de base de datos

Un portfolio personal podría ser un script PHP que carga un JSON. Elegí Hexagonal deliberadamente para mostrar cómo estructuro el código en proyectos reales, pero elegí JSON como persistencia por una razón concreta: no me interesa demostrar aquí mis capacidades con SQL. Los JSON son una base de datos fácilmente consultable y editable, perfecta para este contexto: puedo leer la estructura de datos de un vistazo, editarla directamente y mantenerla sin infraestructura adicional.

Lo que sí quiero demostrar es la capacidad de adaptación de la arquitectura. Si en un proyecto real necesitara cambiar de JSON a MySQL, el proceso sería: crear DoctrineExpertiseAreaRepository, registrarlo en services.yaml, y el controlador no cambiaría una sola línea. El dominio tampoco. Eso es lo que importa.

Ver código fuente completo

Cinco principios de diseño orientado a objetos que producen código mantenible, flexible y testeable. Aquí van aplicados concretamente a este proyecto.

S — Single Responsibility

Una clase, una razón para cambiar.

• JsonPortfolioRepository → solo sabe cargar el portfolio desde JSON
• MarkdownExtension → solo convierte Markdown a HTML para Twig
• VersionExtension → solo lee el fichero VERSION del filesystem
• PersonalInfo → solo representa y valida la información personal
• ArticleController → solo resuelve las rutas de artículos y delega al servicio de aplicación

Ninguno de estos tiene dos responsabilidades mezcladas.

O — Open/Closed

Abierto a extensión, cerrado a modificación.

ExpertiseAreaRepository está cerrada a modificación pero abierta a extensión: puedo crear DoctrineExpertiseAreaRepository o CachedExpertiseAreaRepository sin modificar ninguna clase existente. El controlador tampoco cambia.

L — Liskov Substitution

JsonExpertiseAreaRepository puede sustituir a ExpertiseAreaRepository en cualquier punto de uso sin que el comportamiento esperado cambie. Los tests de integración verifican esto directamente: testean la implementación concreta contra el contrato de la interfaz.

I — Interface Segregation

Interfaces pequeñas y específicas mejor que una grande.

// Solo un método: solo lo que el consumer necesita
interface PortfolioRepository {
    public function find(): Portfolio;
}

// Solo un método: lo mismo para ExpertiseArea
interface ExpertiseAreaRepository {
    public function findAll(): ExpertiseAreas;
}

// Cuatro métodos: cada uno cubre un caso de uso real
interface ArticleRepository {
    public function findAll(): array;
    public function findBySlug(string $slug): ?Article;
    public function findById(string $id): ?Article;
    public function findByTags(array $tags): array;
}

D — Dependency Inversion

Depender de abstracciones, nunca de concreciones.

// Los Application Services dependen de abstracciones (interfaces de dominio):
final class ArticleService
{
    public function __construct(
        private readonly ArticleRepository $articleRepository
    ) {}
}

// Los controladores dependen de Application Services, no de repositorios:
final class PortfolioController extends AbstractController
{
    public function __construct(
        private readonly PortfolioService $portfolioService,
        private readonly ExpertiseAreaService $expertiseAreaService
    ) {}
}

// Symfony resuelve la cadena completa (autowire automático):
// PortfolioService   → PortfolioRepository   → JsonPortfolioRepository
// ArticleService     → ArticleRepository     → JsonArticleRepository

Ningún controlador importa JsonPortfolioRepository. La decisión de qué implementación usar vive en la configuración, no en el código.

Propuesta por Robert C. Martin, establece que las dependencias siempre deben apuntar hacia el interior: el dominio no conoce la aplicación, la aplicación no conoce la infraestructura.

Las capas de este portfolio

┌─────────────────────────────────────────────────────┐
│  INFRAESTRUCTURA                                     │
│                                                      │
│  Entry Points              Adaptadores               │
│  ────────────              ──────────────────────    │
│  PortfolioController       JsonPortfolioRepository   │
│  ArticleController         JsonArticleRepository     │
│                            JsonExpertiseAreaRepo     │
│                            MarkdownExtension         │
│                            VersionExtension          │
│                                                      │
│  ┌───────────────────────────────────────────────┐  │
│  │  APLICACIÓN                                    │  │
│  │                                                │  │
│  │  PortfolioService · ArticleService             │  │
│  │  ExpertiseAreaService                          │  │
│  │                                                │  │
│  │  ┌─────────────────────────────────────────┐  │  │
│  │  │  DOMINIO                                 │  │  │
│  │  │                                          │  │  │
│  │  │  Portfolio · Article · ExpertiseArea     │  │  │
│  │  │  (Aggregates, Value Objects, ports)      │  │  │
│  │  │                                          │  │  │
│  │  │  Sin Symfony. Sin Doctrine. Sin JSON.    │  │  │
│  │  └─────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

Las flechas apuntan siempre hacia adentro.
Infrastructure conoce Application y Domain. Application conoce Domain. Domain no conoce a nadie.

Flujo de una petición

Cada capa solo habla con la inmediatamente interior:

GET /portfolio
  → PortfolioController              (Infrastructure — Entry Point)
  → PortfolioService.getPortfolio()  (Application — Use Case)
  → PortfolioRepository.find()       (Domain Port — interfaz pura)
  → JsonPortfolioRepository          (Infrastructure — Adapter)
  → Portfolio                        (Domain — Value Object)

El controlador no sabe que los datos vienen de JSON. El servicio no sabe que existe Symfony. El dominio no sabe que existe nada externo.

Por qué importa

Permite reemplazar cualquier detalle externo (base de datos, framework, API) sin afectar la lógica de negocio. Es la base sobre la que construyo sistemas que duran años sin deteriorarse.

TDD es una técnica de diseño donde los tests se escriben antes que el código de producción, siguiendo el ciclo Red → Green → Refactor.

El ciclo aplicado en este mismo portfolio

El bounded context Domain/ExpertiseArea/ (el que alimenta esta página) fue construido con TDD desde el primer test. Así fue el ciclo para ExpertiseCategory:

Red: El test falla porque la clase no existe aún:

// tests/Domain/ExpertiseArea/ExpertiseCategoryTest.php

/** @covers \App\Domain\ExpertiseArea\ExpertiseCategory */
final class ExpertiseCategoryTest extends TestCase
{
    /**
     * @test
     * @dataProvider \...DataProvider\ExpertiseCategoryDataProvider::getValidFromStringData()
     */
    public function fromStringShouldReturnExpectedCategory(
        string $value,
        ExpertiseCategory $expected
    ): void {
        static::assertSame($expected, ExpertiseCategory::fromString($value));
        // ↑ Error: Class 'ExpertiseCategory' not found
    }

    /**
     * @test
     */
    public function fromStringWithUnknownValueShouldThrowInvalidArgumentException(): void
    {
        $this->expectException(\InvalidArgumentException::class);
        $this->expectExceptionMessage("Unknown category: 'unknown'");

        ExpertiseCategory::fromString('unknown');
    }
}

Green: Implemento el mínimo para que pase:

// src/Domain/ExpertiseArea/ExpertiseCategory.php
enum ExpertiseCategory: string
{
    case Arquitectura = 'arquitectura';
    case Testing      = 'testing';
    case Backend      = 'backend';
    case Tooling      = 'tooling';

    public static function fromString(string $value): self
    {
        $category = self::tryFrom($value);

        if (null === $category) {
            throw new \InvalidArgumentException("Unknown category: '{$value}'");
        }

        return $category;
    }
}

Refactor: En este caso el diseño ya es limpio, no hay nada que mejorar.

El mismo ciclo se repitió para IconType, ExpertiseArea, ExpertiseAreas y JsonExpertiseAreaRepository. 208 tests son el resultado.

Green → Refactor → Green: un ejemplo real con CSS

El ciclo no se limita al código de producción. En refactors grandes de CSS, los tests de visual regression de Playwright actúan como red de seguridad. Un ejemplo aplicado en este mismo portfolio:

El objetivo: extraer todos los estilos inline y bloques <style> de las plantillas Twig a ficheros CSS dedicados, garantizando cero cambio visual en ninguna página ni viewport.

El enfoque:

1. Green primero: antes de tocar una sola línea de CSS, se generaron snapshots de todas las páginas en todos los viewports (desktop, mobile, tablet). Son la referencia absoluta de "así debe quedar".

2. Refactor: extracción progresiva del CSS. El reto no era solo mover reglas, sino entender la cascada original: había reglas en <body> que nunca se aplicaban porque una regla con mayor especificidad en <head> siempre ganaba. Copiar el valor del <body> habría introducido un bug silencioso. El análisis de especificidad identificó los valores que realmente se renderizaban.

3. Green de verificación: tras la extracción, los E2E detectaron dos casos donde los inlines estaban suprimiendo media queries móviles. No eran regresiones: eran bugs latentes que el refactor corrigió. Los snapshots permitieron tomar esa decisión conscientemente — aceptar el cambio, no revertirlo.

La diferencia con un refactor a ciegas: si algo cambia visualmente, el test falla y hay que decidir conscientemente si aceptar el cambio o revertirlo. Nunca se rompen estilos sin darse cuenta.

Por qué uso TDD

Los tests escritos primero actúan como especificación ejecutable. Si el código es difícil de testear, el diseño está mal. Nunca escribo tests post-hoc para "completar coverage".

Todas estas prácticas están aplicadas en el directorio de tests de este portfolio: ver tests/ en GitHub

Los tests E2E verifican el sistema completo desde la perspectiva del usuario: desde el navegador hasta la base de datos y de vuelta.

72 tests en 4 proyectos Playwright

Estructura Gherkin en este portfolio

Los tests usan test.step() siguiendo la convención Given/When/Then:

test("Modal DDD se puede abrir y cerrar con ESC", {
    tag: ["@test", "@portfolio", "@modal"]
}, async ({ page }) => {
    await test.step("Given: el usuario está en /portfolio", async () => {
        await navigateToPortfolio(page);
    });

    await test.step("When: abre el modal DDD", async () => {
        await openModal(page, "ddd");
    });

    await test.step("Then: el modal es visible", async () => {
        await expect(page.locator("#modal-ddd")).toBeVisible();
    });

    await test.step("When: pulsa Escape", async () => {
        await page.keyboard.press("Escape");
    });

    await test.step("Then: el modal se cierra", async () => {
        await expect(page.locator("#modal-ddd")).not.toBeVisible();
    });
});

Mi rol como Tech Lead de E2E

En El Confidencial lidero el equipo de testing E2E. En ese contexto construí PPIA (Playwright Page Inspector with AI): herramienta que genera tests E2E completos a partir de especificaciones Gherkin usando mcp-playwright y ChatGPT mini 4.1 entre otros sistemas de análisis. El objetivo es que los nuevos tests de El Confidencial se generen con PPIA.

Framework de testing E2E de Microsoft. Es mi herramienta principal para automatización de navegadores tanto en este portfolio como en producción en El Confidencial.

Elegí Playwright frente a Selenium porque, desde mi experiencia como automatizador, considero que Selenium ha quedado obsoleto: su arquitectura WebDriver no está diseñada para el ecosistema actual, y su integración con herramientas de IA es muy inferior. Playwright ofrece auto-waiting nativo, selectores más robustos y una API que encaja de forma natural con los flujos de generación de tests con IA.

POM estricto — los tests no contienen selectores ni expects

El patrón que aplico va más allá del POM estándar: los archivos de spec no contienen ni un solo selector CSS ni ninguna llamada a expect(). Toda la lógica de interacción y aserción vive en los componentes del POM.

Ejemplo real con el componente header:

// playwright/components/header/selectors.ts
export const container         = '.header';
export const logo              = '.logo';
export const navigation        = 'nav[role="navigation"]';
export const navLinksContainer = '.nav-links';
export const navLinks          = '.nav-links .nav-link';
export const activeNavLink     = '.nav-link.active';
export const themeToggle       = '#theme-toggle';
export const mobileMenuToggle  = '.mobile-menu-toggle';
export const mobileOverlay     = '.mobile-overlay';

// playwright/components/header/index.ts
import { Page, expect } from '@playwright/test';
import * as selectors from './selectors';

export async function toggleTheme(page: Page): Promise<void> {
    await page.locator(selectors.themeToggle).click();
    await page.waitForTimeout(400); // espera transición CSS
}
export async function openMobileMenu(page: Page): Promise<void> {
    await page.locator(selectors.mobileMenuToggle).click();
    await page.locator(selectors.navLinksContainer).waitFor({ state: 'visible' });
}
export async function themeIsDark(page: Page): Promise<void> {
    expect(await page.locator('html').getAttribute('data-theme')).toBe('dark');
}
export async function hasNavLinksCount(page: Page, count: number): Promise<void> {
    await expect(page.locator(selectors.navLinks)).toHaveCount(count);
}

Los tests solo llaman a estas funciones, nunca a selectores ni expect() directamente.

Ver documentación completa del Header POM — incluye todas las acciones, assertions y selectores del componente.

Estructura de specs y componentes POM

playwright/
├── components/
│   ├── index.ts                → Barrel export de todos los componentes
│   ├── home/                   → navigateHome, heroMatchesSnapshot,
│   │   ├── index.ts               skillsGridMatchesSnapshot, expandSkillAtPosition...
│   │   └── selectors.ts
│   ├── header/                 → toggleTheme, openMobileMenu, themeIsDark,
│   │   ├── index.ts               hasNavLinksCount, headerMatchesSnapshot...
│   │   └── selectors.ts
│   ├── footer/                 → scrollToFooter, yearIsCurrentYear,
│   │   ├── index.ts               versionMatchesSemver, footerMatchesSnapshot...
│   │   └── selectors.ts
│   ├── cv/                     → navigateToCv, pdfLinkIsVisible,
│   │   ├── index.ts               skillsCarouselHasTitle, cvHeaderMatchesSnapshot...
│   │   └── selectors.ts
│   ├── contact/                → navigateToContact, emailLinkIsValid,
│   │   ├── index.ts               externalLinksAreSecure, contactCardMatchesSnapshot...
│   │   └── selectors.ts
│   ├── projects/               → navigateToProjects, hasProjectCount,
│   │   ├── index.ts               projectGithubLinkIs, ppiaProjectIsPrivate...
│   │   └── selectors.ts
│   ├── code-ai/                → navigateToCodeAi, articleHasParagraphs,
│   │   ├── index.ts               articlesGridMatchesSnapshot...
│   │   └── selectors.ts
│   ├── ppia/                   → navigateToPpia, titleIsCorrect,
│   │   ├── index.ts               ppiaHeaderMatchesSnapshot
│   │   └── selectors.ts
│   └── portfolio/              → openModal, closeModalByEsc, modalHasTitle,
│       ├── index.ts               keywordsSectionMatchesSnapshot...
│       └── selectors.ts
└── tests/
    ├── home/           → home.desktop.spec.ts, home.mobile.spec.ts,
    │                      home.skills.desktop.spec.ts, home.skills.mobile.spec.ts
    ├── header/         → header.desktop.spec.ts, header.mobile.spec.ts,
    │                      header.dark-mode.tablet-small.spec.ts,
    │                      header.dark-mode.tablet-large.spec.ts
    ├── footer/         → footer.desktop.spec.ts, footer.mobile.spec.ts
    ├── cv/             → cv.desktop.spec.ts, cv.mobile.spec.ts
    ├── contact/        → contact.desktop.spec.ts, contact.mobile.spec.ts
    ├── projects/       → projects.desktop.spec.ts, projects.mobile.spec.ts
    ├── code-ai/        → code-ai.desktop.spec.ts, code-ai.mobile.spec.ts
    ├── ppia/           → ppia.desktop.spec.ts, ppia.mobile.spec.ts
    └── portfolio/      → portfolio.desktop.spec.ts, portfolio.mobile.spec.ts

Ver POM.md completo con todas las funciones documentadas

72 tests en 4 proyectos Playwright

Ver TEST.md con los 72 tests completos y sus pasos Gherkin

Sistema de tags

Cada test lleva tags multidimensionales que permiten ejecutar subsets precisos:

test("header dark mode: en desktop el tema es light por defecto", {
    tag: ["@test", "@header", "@dark_mode"]
}, async ({ page }) => { ... });

npx playwright test --grep "@header"     # todos los tests del header
npx playwright test --grep "@dark_mode"  # solo dark mode (todos los componentes)
npx playwright test --grep "@visual"     # solo regresión visual
npx playwright test --grep "@modal"      # solo tests de modales

PPIA y la automatización de tests con IA

Tener el POM documentado con .md y los specs organizados por tags hace que la generación de tests con IA sea extraordinariamente efectiva.

PPIA (Playwright Page Inspector with AI) es la herramienta que construí para El Confidencial: toma una especificación Gherkin, inspecciona el DOM de la página con mcp-playwright y ChatGPT mini 4.1 entre otros sistemas de análisis, y genera automáticamente el test Playwright completo. Actualmente estoy migrando la implementación a Python, que publicaré próximamente en GitHub.

POM-PPIA es la pieza siguiente a PPIA en el ecosistema: toma los tests generados por PPIA (funcionales pero crudos) y los transforma en Page Objects correctos, Gherkin limpio y estructura BDD completa: el resultado es exactamente el patrón POM estricto que ves en este portfolio. Está totalmente funcional y publicado: ver repositorio POM-PPIA en GitHub

Tengo pendiente para los próximos sprints instalar el ecosistema PPIA completo en este portfolio: tanto para los tests nuevos que se añadan como para transformar los existentes a formato Cucumber, y medir los tiempos de generación de tests. Seguimos trabajando en ello. 💪

Con más de 8 años de experiencia en PHP, he visto la evolución del lenguaje desde arrays asociativos sueltos hasta tipos de intersección y backed enums. PHP moderno es un lenguaje serio y potente.

Features modernas que uso en este proyecto

• declare(strict_types=1) en todos los archivos, sin coerciones de tipo silenciosas
• Readonly properties: PersonalInfo, ContactInfo y ExpertiseArea son Value Objects inmutables
• Backed enums: ExpertiseCategory e IconType como Value Objects con fromString() tipado
• Named arguments: new ExpertiseArea(id: 'ddd', label: 'DDD', ...) en los tests
• Match expressions: en la extensión de Markdown para evaluar el modo safe/unsafe
• Constructor promotion: reducción de boilerplate en entidades de dominio

PHPStan level 9

Todos los archivos PHP de este proyecto pasan PHPStan level 9. El análisis estático corre en cada PR como check requerido — no se puede mergear código con errores de tipo.

Ver src/ completo →

Los últimos 4 años ha sido mi framework de trabajo principal en El Confidencial. Lo conozco en profundidad: desde el ciclo de vida del kernel hasta la compilación del contenedor de servicios.

Lo que Symfony aporta en este proyecto

• DependencyInjection: JsonPortfolioRepository y JsonExpertiseAreaRepository se inyectan por constructor a través de sus interfaces, sin tocar los controladores
• Twig: motor de plantillas con filtros personalizados (|markdown, version())
• Routing: atributos PHP #[Route] en los controladores
• Cache: php bin/console cache:clear en cada deploy garantiza código fresco en producción

Autowiring en acción

Con una sola implementación por interfaz, Symfony resuelve la inyección automáticamente:

# services.yaml — configuración mínima
App\:
    resource: '../src/'
    autowire: true
    autoconfigure: true
# Symfony detecta:
# ExpertiseAreaRepository → JsonExpertiseAreaRepository (única implementación)
# PortfolioRepository     → JsonPortfolioRepository     (única implementación)

Componentes que domino en profundidad

• EventDispatcher: arquitecturas event-driven sin acoplamiento
• Console: CLIs con progress bars, tablas y comandos interactivos
• Security: Voters, firewalls, JWT y autenticación personalizada
• Messenger: procesamiento asíncrono con múltiples transportes

Framework de testing estándar del ecosistema PHP. Lo uso para tests unitarios de dominio (sin I/O) y tests de integración de infraestructura (con ficheros JSON reales).

208 tests en dos niveles

DataProvider classes separadas

// tests/Domain/ExpertiseArea/DataProvider/ExpertiseCategoryDataProvider.php

final class ExpertiseCategoryDataProvider
{
    /** @return array<string, array{string, ExpertiseCategory}> */
    public static function getValidFromStringData(): array
    {
        return [
            'arquitectura' => ['arquitectura', ExpertiseCategory::Arquitectura],
            'testing'      => ['testing',      ExpertiseCategory::Testing],
            'backend'      => ['backend',      ExpertiseCategory::Backend],
            'tooling'      => ['tooling',      ExpertiseCategory::Tooling],
        ];
    }
}

setUp y tearDown en integración

final class JsonExpertiseAreaRepositoryTest extends TestCase
{
    private JsonExpertiseAreaRepository $repository;
    private string $tmpPath = '';

    protected function setUp(): void
    {
        $this->repository = new JsonExpertiseAreaRepository(self::FIXTURE_PATH);
    }

    protected function tearDown(): void
    {
        if ('' !== $this->tmpPath && file_exists($this->tmpPath)) {
            unlink($this->tmpPath);
        }
    }

    /** @test */
    public function findAllShouldReturnExpertiseAreasCollection(): void
    {
        static::assertInstanceOf(ExpertiseAreas::class, $this->repository->findAll());
    }
}

Todas estas prácticas están aplicadas en el directorio de tests de este portfolio: ver tests/ en GitHub

Analizador estático de PHP que detecta errores sin ejecutar el código. Trabajo siempre a nivel 9, el máximo.

Por qué nivel 9

El nivel 9 requiere que todo esté completamente tipado: parámetros, retornos, propiedades, genéricos. El resultado es código donde los errores de tipo se detectan en CI, no en producción.

Lo que PHPStan detecta en mis proyectos

• Llamadas a métodos en valores posiblemente null
• Arrays sin tipo genérico (array vs array<string, int>)
• Condiciones siempre verdaderas o falsas
• Dead code
• Violaciones de contratos de interfaces

Integrado en el pipeline de CI: un PR no se puede mergear si PHPStan reporta errores.

Uso Docker para garantizar que el entorno de desarrollo es idéntico al de CI y producción. Sin "en mi máquina funciona".

La imagen de este portfolio

Una sola imagen que incluye:

• PHP 8.1 + Symfony + PHPUnit + PHPStan + CS Fixer
• Node.js 20 + TypeScript + ESLint
• Playwright con Chromium bakeado: los tests E2E no necesitan instalar navegadores

Las dependencias (vendor/, node_modules/, Chromium) están en la imagen. El código fuente se monta como volumen en desarrollo, para editar sin reconstruir.

Workflow diario

make up                      # levanta el servidor en localhost:8080
make qa-full                 # PHPUnit + PHPStan + CS Fixer + ESLint + E2E
make e2e                     # solo E2E contra localhost:8080
make e2e-update-snapshots    # regenerar baselines de visual regression

Por qué una sola imagen

Simplicidad: un solo make build y tienes el entorno completo. CI usa la misma imagen. Sin matrices de versiones, sin sorpresas de "funciona en CI pero no en local".

Más allá de los comandos básicos, domino los flujos de trabajo Git para equipos.

Gitflow real de este portfolio

master (producción)
  ↑  ← Pull Request + QA obligatorio
develop (integración)
  ↑  ← Pull Request desde feature/*
feature/t{num}_{desc}   ← una por tarea/issue
hotfix/t{num}_{desc}    ← urgentes desde master

Cada feature nace de una issue de GitHub, vive en su rama, pasa QA en PR y se mergea a develop. Cuando hay suficientes features listas, se abre una release PR develop → master. El merge a master dispara automáticamente el pipeline de deploy.

Para hotfixes urgentes la rama sale directamente desde master, pasa QA (incluido E2E contra localhost) y se mergea a master. El back-merge a develop es automático tras el deploy.

Convenciones que aplico en este repo

• Conventional Commits: feat:, fix:, chore:, refactor:, test:, docs:
• Nomenclatura de ramas: feature/t{num}_{descripcion_snake_case}
• Branch protection: master y develop no admiten push directo
• No fast-forward merges: historial explícito de cuándo entró cada feature
• Back-merge automático: tras cada deploy, master → develop con [skip ci]

Automatización post-deploy

Automáticamente tras cada merge a master:

1. Bump de versión semántica
2. rsync al VPS de producción (OVH)
3. E2E contra producción
4. Back-merge a develop
5. Sync al repositorio público

Estrategia dual-repo

Este portfolio se gestiona con dos repositorios GitHub:

• Repo privado: contiene todo — workflows de deploy, scripts de infraestructura, secrets SSH, configuración de servidores. Es el repositorio operativo real.
• Repo público: showcase profesional que recibe automáticamente el código fuente, tests, configuración Docker y un workflow de QA funcional.

La separación es deliberada: el código y los tests son públicos porque demuestran arquitectura y buenas prácticas. La infraestructura de deploy es privada porque contiene credenciales y configuración de servidores.

El sync es selectivo y automático: cada deploy a producción copia src/, tests/, playwright/, Dockerfile, docker-compose.yml, Makefile y configs de QA al repo público. El repo público ejecuta su propia QA con los mismos tests y la misma imagen Docker, verificando que todo funciona de forma independiente.

Claude AI (de Anthropic) es la herramienta de IA que he integrado en mi flujo de trabajo de desarrollo. No como atajo, sino como par de programación que ayuda a razonar sobre diseño y arquitectura.

Claude Desktop — Diseño de dominio

La primera versión de este portfolio empezó en Claude Desktop: conversaciones largas sobre cómo modelar el dominio, qué debería ser un Value Object, cómo separar infraestructura de dominio. El modelo me ayudó a formalizar lo que tenía en la cabeza en una estructura DDD coherente antes de escribir una sola línea de código.

Ese proceso de "hablar sobre arquitectura" definió la estructura que ves en src/Domain/ y la separación de capas que mantiene este portfolio.

Claude Code — Implementación con buenas prácticas

La implementación posterior usó Claude Code para asegurar que las buenas prácticas se aplicaban consistentemente: PHPStan level 9, CS Fixer, arquitectura hexagonal sin concesiones, tests bien estructurados con POM estricto.

Claude Code actúa como senior engineer que revisa cada cambio, propone mejoras y ejecuta el ciclo completo: rama → PR → QA → merge → deploy.

Para que todo esto funcione exactamente como quiero en cada proyecto, desarrollé TLOTP: un super-prompt que auto-configura Claude Code al arrancar una sesión. Detecta el stack, carga mis reglas de arquitectura, gitflow, testing y CI/CD, y convierte a Claude en un senior engineer especializado en ese proyecto concreto. El resultado: Claude conoce mis convenciones desde el primer mensaje, sin tener que explicarle el contexto cada vez.

Ver el proyecto TLOTP que hace posible copilotar con Claude

Diseño y mantengo pipelines de integración y despliegue continuo que garantizan calidad sin fricción para el desarrollador.

QA en Pull Requests

Corre en cada PR contra develop o master. Jobs en paralelo:

Los tres son requeridos para mergear. El E2E contra localhost solo se ejecuta en PRs a master (releases y hotfixes) porque valida que la build completa funciona antes de tocar producción.

Pipeline de deploy

Se dispara automáticamente al mergear a master. Principio "test once, promote": la QA ya se ejecutó en la PR, por lo que el pipeline de deploy no repite PHPUnit, PHPStan ni ESLint.

1. Bump versión semántica  (feat: → MINOR · fix:/chore: → PATCH)
2. rsync al VPS de producción (OVH) + composer install + cache warmup
3. Health check → https://josemoreupeso.es
4. E2E Playwright contra producción (target distinto: verifica el deploy real)
5. Back-merge automático master → develop  [skip ci]
6. Sync al repositorio público (QA en 3 jobs paralelos independientes)

Estrategia dual-repo

Este portfolio tiene dos repositorios con roles distintos:

• Repo privado — CI/CD completo: deploy a producción, secrets SSH, scripts de infraestructura, back-merge automático. Todo lo que hace falta para operar el sistema real.
• Repo público — Showcase profesional: recibe automáticamente el código fuente, tests, configuración Docker y un workflow de QA propio. Demuestra arquitectura, testing y CI/CD funcional sin exponer infraestructura sensible.

El sync es selectivo: copia src/, tests/, playwright/, Dockerfile, docker-compose.yml, Makefile y configs de QA. No copia workflows de deploy, secrets ni scripts de infraestructura.

Repo privado (push a master)
│
├─ Deploy a producción (rsync + SSH)
├─ E2E contra producción
├─ Back-merge master → develop
└─ Sync selectivo → Repo público
                      │
                      └─ QA independiente (3 jobs paralelos)
                         ├─ PHPUnit + PHPStan + CS Fixer
                         ├─ ESLint
                         └─ E2E con Docker contra producción

Repositorio público — QA independiente

El repositorio público ejecuta su propia QA en 3 jobs paralelos al recibir cada sync:

El E2E usa Docker deliberadamente: los snapshots de visual regression se generan con una versión específica de Chromium dentro del contenedor. Si el CI usara el Chromium nativo de GitHub Actions, las diferencias de rendering provocarían falsos positivos. Misma imagen = mismo pixel.

Versionado semántico automático

El primer paso del pipeline de deploy es calcular la nueva versión leyendo los commits desde el último bump y aplicando Conventional Commits:

La versión vive en .env como APP_VERSION y el bump se commitea automáticamente con [skip ci] para no disparar un bucle. El footer del portfolio la lee en tiempo real.

Principios de diseño

• Rápido: PHP Backend + ESLint en paralelo, QA completo en < 2 minutos
• Ruidoso: cualquier fallo bloquea el merge
• Sin QA redundante: pipeline siempre activo, sin variables CISKIP*
• Sin downtime: rsync incremental + cache warmup antes de recargar PHP-FPM
• Rollback: backup automático antes de cada deploy, restaurable en un comando

Herramienta de formateo automático de código PHP. Garantiza consistencia de estilo en todo el proyecto sin debates sobre tabs vs espacios.

Mi configuración

PSR-12 como base, con reglas adicionales: imports ordenados, trailing commas en listas multilínea, casting limpio.

En el pipeline

• Local: make cs-fix antes de commitear
• CI: make cs-check (dry-run) es required en PRs
• No mergeable: si alguien olvida formatear, el PR no se mergea

El resultado es un historial de git donde los diffs muestran solo cambios semánticos, nunca cambios de formato.

Analizador estático de JavaScript y TypeScript. En este proyecto lo uso para garantizar la calidad del código de los tests E2E escritos con Playwright.

Mi configuración

Reglas adaptadas a TypeScript estricto: tipos explícitos de retorno, sin any implícito, imports ordenados y sin usar. La base es el plugin oficial de TypeScript con las reglas recomendadas más las específicas del proyecto.

En el pipeline

• Local: make lint antes de commitear
• CI: requerido en PRs — si hay warnings, el PR no puede mergearse
• Auto-fix: make lint-fix corrige automáticamente lo que puede resolver solo

Lo que ESLint detecta

• Variables y imports declarados pero no usados
• Tipos any implícitos o explícitos
• Funciones sin tipo de retorno explícito
• Violaciones de las reglas del proyecto

Al igual que PHPStan para PHP, ESLint actúa como primera barrera de calidad antes de ejecutar los tests E2E.

Twig es el motor de plantillas de Symfony y CSS es la capa de presentación visual. En este portfolio los combino para construir una UI completa sin frameworks frontend, con componentes reutilizables y un sistema de diseño basado en variables CSS.

46 plantillas Twig componentizadas

La arquitectura de templates sigue un patrón de componentes reutilizables sin necesidad de React ni Vue:

templates/
├── base.html.twig                    ← Layout principal con bloques
├── components/
│   ├── content/                      ← 7 componentes de contenido
│   │   ├── article-card.html.twig    ← Tarjeta de artículo
│   │   ├── article-content.html.twig ← Cuerpo Markdown → HTML
│   │   ├── article-header.html.twig  ← Cabecera de artículo
│   │   ├── portfolio-intro.html.twig ← Intro de portfolio
│   │   └── ...                       ← contact-header, ppia-header
│   └── ui/                           ← 13 componentes UI
│       ├── hero.html.twig            ← Hero section
│       ├── skills-grid.html.twig     ← Grid expandible de skills
│       ├── info-card.html.twig       ← Tarjeta informativa
│       ├── contact-card.html.twig    ← Tarjeta de contacto
│       └── ...                       ← cv-note, pdf-card, wip-card
├── pages/                            ← 8 páginas (extends base)
└── styles/                           ← 11 archivos CSS-in-Twig

Cada componente recibe parámetros via {% include %} con with {}, y se documenta con un bloque de comentario Twig al inicio del archivo indicando los parámetros aceptados.

Arquitectura CSS modular

20 archivos CSS organizados en tres capas:

public/css/
├── core/           ← Fundamentos del sistema
│   ├── variables.css    ← 30+ CSS custom properties
│   ├── reset.css        ← Normalización global
│   ├── animations.css   ← @keyframes compartidos
│   └── layout.css       ← Header, footer, main
├── components/     ← Componentes reutilizables
│   ├── hero.css, buttons.css, cards.css
│   ├── skills-grid.css, article-cards.css
│   └── article-content.css
├── pages/          ← Estilos específicos por ruta
│   ├── home.css, cv.css, contact.css
│   └── code-ai.css, portfolio.css
└── main.css        ← Entry point con @import ordenados

Sistema de variables CSS con dark mode

Un sistema completo de design tokens en CSS custom properties:

:root {
  --bg-primary: #0a0a1a;
  --accent-primary: #00d9ff;
  --font-mono: 'Fira Code', monospace;
  --spacing-md: 2rem;
  --radius-lg: 1.5rem;
  --transition-base: 0.3s ease;
  --z-modal: 1000;
}
[data-theme="dark"] { /* Override completo */ }

Dark mode con toggle en desktop (persistido en localStorage) y forzado automáticamente en mobile (< 850px).

Critical CSS con CSS-in-Twig

11 archivos .css.twig que se renderizan inline en el <head>, eliminando el flash of unstyled content (FOUC) y mejorando el First Contentful Paint. Cada página carga solo los estilos que necesita.

Responsive design sin frameworks

Diseño responsive puro con CSS moderno: clamp() para tipografía fluida, media queries focalizados y componentes que se adaptan sin breakpoints artificiales.