Reglas de estabilidad de la SPI

En resumen

La interfaz de proveedor de servicios de NextPDF sigue Semantic Versioning. Cada contrato público lleva una etiqueta @stability y una promesa de compatibilidad hacia atrás. Esta página establece las reglas para decidir con claridad de qué depender.

Instalación

composer require nextpdf/core:^3

Panorama conceptual

La interfaz de proveedor de servicios es el conjunto de contratos públicos de los espacios de nombres NextPDF\Contracts y NextPDF\Event. Un tipo solo forma parte de la interfaz cuando su PHPDoc de origen lleva una etiqueta @stability. La etiqueta marca el límite. Un tipo sin esa etiqueta es interno, aunque técnicamente sea public en PHP.

NextPDF sigue Semantic Versioning 2.0.0. Un cambio incompatible en un contrato stable incrementa la versión mayor. Un contrato nuevo o una adición no incompatible incrementa la versión menor. Una corrección de errores incrementa la versión de parche.

La etiqueta @stability

Cada contrato declara uno de tres valores de estabilidad:

Etiqueta	Significado	Regla de cambio
stable	Listo para producción. Seguro para depender de él.	Sin cambios incompatibles en una versión menor o de parche. Solo se añaden métodos nuevos con un comportamiento predeterminado o en un contrato nuevo.
experimental	Utilizable pero todavía no congelado.	La interfaz puede cambiar en una versión menor, con un aviso de obsolescencia previo.
deprecated	Programado para su eliminación.	El contrato indica el reemplazo y la versión de eliminación.

La promesa por contrato se registra en el mapa de contratos generado y se regenera a partir del código fuente en cada versión. El texto de la promesa indica la regla exacta para ese contrato. Consultar el PHPDoc de origen del contrato como única fuente de verdad.

Clases de promesa de compatibilidad hacia atrás

El mapa de contratos registra la promesa. Las promesas se dividen en cuatro clases:

1. Promesa de interfaz. «Sin cambios incompatibles en una versión menor o de parche. Métodos nuevos solo con una implementación predeterminada.» Se aplica a la mayoría de las interfaces stable, incluidas FontRegistryInterface, SignerInterface, HsmSignerInterface y HtmlSecurityPolicyInterface.
2. Promesa de enum. «Sin eliminación de casos. Pueden añadirse casos nuevos en una versión menor.» Se aplica a enums stable como Alignment, Orientation y OutputDestination.
3. Promesa de objeto de valor congelado. «La firma del constructor y las propiedades públicas están congeladas. Pueden añadirse métodos nuevos.» Se aplica a objetos de valor como TextPreprocessResult, TextSegment y las cargas útiles de eventos asociadas a él.
4. Promesa experimental. «La interfaz puede cambiar en una versión menor con un aviso de obsolescencia.» Se aplica a contratos experimental como DeferredSignerInterface, TimestampProviderInterface, CursorInterface y StreamingWriterInterface.

Una clase final como EventDispatcher o ListenerProvider congela las firmas de sus métodos públicos. Para extender el comportamiento de una clase final, usar composición. No crear subclases de ella.

Contratos de streaming experimentales

CursorInterface y StreamingWriterInterface son experimental (desde 3.1.0). NextPDF incluye una implementación final y probada del motor para ambos contratos; las clases de implementación son internas y no forman parte de la superficie pública. El comportamiento de streaming se consume a través del contrato público experimental. En el caso común, no se implementa el contrato directamente.

Como el contrato es experimental, su firma puede cambiar en una versión menor, con un aviso de obsolescencia previo (la promesa experimental). Fijar con precisión la dependencia o envolverlo detrás de un adaptador propio antes de depender de él en producción. Tratar el contrato de streaming como un punto de extensión en estabilización, no como uno congelado.

Superficie de la API

Esta página no define ninguna API de tiempo de ejecución. La superficie relevante es la etiqueta PHPDoc @stability en cada contrato público y el mapa de contratos regenerado que recopila la promesa por contrato.

Ejemplo de código — Inicio rápido

Leer la estabilidad de un contrato desde su código fuente antes de depender de él.

<?php

declare(strict_types=1);

use ReflectionClass;

$doc = (new ReflectionClass(\NextPDF\Contracts\FontRegistryInterface::class))
    ->getDocComment();

// Look for the "@stability stable" line in the contract PHPDoc.
\assert(\is_string($doc) && \str_contains($doc, '@stability stable'));

Ejemplo de código — Producción

Una restricción de versión de Composer fija la versión mayor, que es la unidad de cambio incompatible para un contrato stable.

{
    "require": {
        "nextpdf/core": "^3.0"
    }
}

Usar ^3.0 para recibir versiones menores y de parche sin cambios incompatibles en ningún contrato stable. Fijar con más precisión cuando se dependa de un contrato experimental, porque un contrato experimental puede cambiar en una versión menor.

Casos límite y trampas

• Etiqueta, no visibilidad. Un método public de PHP no forma parte de la interfaz de proveedor de servicios a menos que su tipo declarante lleve una etiqueta @stability.
• Evolución experimental. Un contrato experimental puede cambiar en una versión menor. Fijar con precisión la dependencia o envolverlo detrás de un adaptador propio. Esto se aplica a los contratos de streaming aunque tengan implementaciones incluidas.
• Nuevos métodos predeterminados. Una interfaz stable puede incorporar un método que tenga un comportamiento predeterminado. Implementar el método nuevo al actualizar para mantener explícita la implementación propia.
• Paridad entre ediciones. NextPDF Pro y NextPDF Enterprise siguen las mismas reglas. Un contrato al que se apunte en Core sigue siendo válido frente a una implementación Premium del mismo contrato.

Ciclo de vida de obsolescencia

Un contrato avanza por un ciclo de vida definido:

1. Marcado. El responsable establece @stability deprecated en el PHPDoc de origen y registra el reemplazo y la versión de eliminación.
2. Aviso. La obsolescencia se anuncia en el registro de cambios en la versión que la marca.
3. Solapamiento. El contrato obsoleto y su reemplazo coexisten durante al menos una versión menor.
4. Eliminación. El contrato se elimina en la versión mayor indicada. La eliminación nunca ocurre en una versión menor o de parche.

Planificar una actualización tan pronto como un contrato se marque como deprecated. El reemplazo siempre se indica.

Rendimiento

Esta página define una política. No tiene costo en tiempo de ejecución.

Notas de seguridad

Los contratos de firma son stable y siguen la promesa de interfaz. Un método nuevo en un contrato de firma se introduce solo con un comportamiento predeterminado o en un contrato nuevo, de modo que una implementación respaldada por hardware no se rompe con una actualización menor. Revisar el registro de cambios antes de una actualización mayor, porque una versión mayor puede cambiar un contrato stable.

Conformidad

La regla de versionado cumple con Semantic Versioning 2.0.0. La generación del registro de cambios sigue Conventional Commits 1.0.0.

Contexto comercial

NextPDF Pro y NextPDF Enterprise siguen las mismas reglas de estabilidad de la interfaz de proveedor de servicios que Core. Un contrato al que se apunte en Core sigue siendo válido frente a la implementación Premium de ese contrato, de modo que el código de la extensión es portátil entre ediciones.

Véase también

• Visión general de la creación de extensiones
• Fuentes personalizadas
• Disparadores de acciones y escuchas de eventos
• Contrato del proveedor de KMS

Contratos y módulos relacionados

• Referencia del módulo de contratos — el mapa de contratos generado y el texto de la promesa por contrato.
• Referencia de los contratos de streaming — los contratos de streaming experimental y sus implementaciones incluidas.
• Referencia de los contratos de firma — contratos de firma stable y experimental bajo las mismas reglas.
• Visión general de la creación de extensiones — qué significa en la práctica cada etiqueta @stability.
• Disparadores de acciones y escuchas de eventos — el despachador final y las cargas útiles experimentales regidas por estas reglas.

El glosario define etiqueta de estabilidad y promesa de compatibilidad hacia atrás; consulta el glosario publicado para cada definición canónica.