Estándares de programación

Esta página describe las convenciones que debe seguir cualquier contribución al plugin, a un nivel que sea seguro publicar. Los nombres de clases internas, las constantes internas, los identificadores de capacidades (capabilities) y las convenciones de claves de opciones son detalles de implementación y no se publican aquí.

Cuándo usar este documento

Utilice este documento cuando:

• Vaya a añadir PHP, JavaScript, CSS, plantillas o cadenas traducibles a una contribución.
• Esté revisando una pull request y necesite una referencia de lo que significa "coherente con la base de código".
• Esté extendiendo el plugin desde un plugin independiente o un tema y quiera que su propio código se sienta nativo.

PHP

• Nivel de lenguaje. Apunte a la versión de PHP declarada en la cabecera del plugin como mínima. Evite características que no estén disponibles en ella.
• Declaraciones de tipo. Utilice declaraciones de tipo escalar y de retorno en los nuevos métodos, en consonancia con el código circundante.
• Estilo WordPress. Siga los estándares de programación de PHP de WordPress (pestañas para la sangría, espacios dentro de los paréntesis, condiciones Yoda donde la base de código ya las use, snakecase para funciones y métodos, TitleCaseWithUnderscores para nombres de clases).
• Una sola clase por archivo. Cada archivo PHP contiene una clase. Los nombres de archivo coinciden con los nombres de clase en formato minúscula y separados por guiones, de acuerdo con las convenciones ya presentes en la base de código.
• Sin nuevos globales. Prefiera las constantes de clase y la inyección de dependencias en lugar de variables globales dispersas.

Integración con WordPress

• Comprobaciones de capacidades primero. Cada acción privilegiada debe verificar la capacidad (capability) adecuada antes de realizar cualquier trabajo.
• Comprobaciones de nonce para formularios y AJAX de administración. Utilice las API de nonce estándar de WordPress (check_admin_referer, check_ajax_referer, wp_verify_nonce) para cualquier endpoint que cambie el estado.
• Sanitización y escapado. Sanitice en la entrada y escape en la salida utilizando las API de WordPress adecuadas para el tipo y el contexto de salida. Consulte Sanitización y escapado.
• i18n. Envuelva las cadenas orientadas al usuario con el dominio de texto (text domain) del plugin. Consulte Internacionalización para desarrolladores.
• Registro de logs. Utilice el registrador compartido del plugin en lugar de llamar a error_log de PHP directamente desde el código de la nueva característica.

JavaScript y CSS

• El plugin no utiliza un pipeline de compilación de JavaScript; los recursos se distribuyen como archivos planos.
• Mantenga el JavaScript del front-end libre de dependencias y progresivo; el plugin debe seguir funcionando en navegadores que bloqueen scripts de terceros.
• Prefije las nuevas clases CSS de forma coherente con las convenciones existentes del front-end y de la administración para evitar colisiones con los temas.

Pruebas

• Los nuevos cambios de comportamiento deben estar cubiertos por pruebas siempre que puedan ser ejercitados razonablemente por pruebas unitarias.
• Nombre las nuevas clases de prueba según la clase o el comportamiento bajo prueba con un sufijo Test, en consonancia con las pruebas existentes.
• Consulte la Guía de pruebas para conocer el flujo de trabajo de pruebas de alto nivel.

Documentación

• Actualice las páginas relevantes bajo docs/en/ cada vez que una contribución cambie el comportamiento observable públicamente.
• Mantenga la documentación segura para el público; no añada nombres de clases internas, claves de opciones, nombres de rutas REST/AJAX o identificadores de capacidades/nonces al conjunto de documentación pública.

Aviso de documentación pública. Esta página proporciona únicamente una descripción general de integración de alto nivel. Los detalles de implementación interna, las API privadas, los aspectos internos del almacenamiento y la infraestructura de lanzamiento sensible a la seguridad se mantienen por separado y no forman parte de la documentación pública.