Manual:Registro de extensiones
| Versión de MediaWiki: | ≥ 1.25 Gerrit change 166705 |
El registro de extensiones es el mecanismo que utiliza MediaWiki para cargar extensiones y apariencias.
Introduces datos de configuración en un archivo llamado extension.json o skin.json en el directorio raíz de tu extensión o apariencia, y MediaWiki utiliza esto para registrar las extensiones y apariencias.
Si estabas buscando más bien documentación sobre cómo instalar extensiones, consulta esta guía.
Funcionalidades
Atributos
Los «atributos» te permiten registrar algo, como un módulo, con otra extensión.
Por ejemplo, la extensión Editor Visual (VE) ofrece el gancho $wgVisualEditorPluginModules, que otras extensiones pueden utilizar para registrar un módulo con VE.
Si la extensión Math fuera a registrar un módulo con VE, tendría algo parecido a lo siguiente en su extension.json:
| manifest version 2 | manifest version 1 |
|---|---|
El nodo attributes debe ser un objeto con el nombre de la extensión como clave y un objeto de pares atributo/valor como valor. ¡Ten en cuenta que la clave del subobjeto no debe contener el nombre de la extensión!
{
"attributes": {
"VisualEditor": {
"PluginModules": [
"ext.math.visualEditor"
]
}
},
"manifest_version": 2
}
|
La versión 1 del manifiesto no tiene una sección separada para attributes:
{
"VisualEditorPluginModules": [
"ext.math.visualEditor"
]
}
|
Si el Editor Visual quisiera acceder a este atributo, tendría que utilizar:
ExtensionRegistry::getInstance()->getAttribute( 'VisualEditorPluginModules' );
Requisitos (dependencias)
El registro de extensiones tiene una sección requires, que funciona de forma similar a la sección require de Composer.
Permite a un desarrollador de extensiones especificar varios requisitos para la extensión, como una determinada versión de MediaWiki (o mayor/menor que) u otra extensión/apariencia.
Por ejemplo, para añadir una dependencia de una versión de MediaWiki igual o posterior a la 1.26.0, puedes añadir el siguiente código a extension.json: [1]
{
"requires": {
"MediaWiki": ">= 1.26.0"
}
}
La clave del objeto requires es el nombre de la dependencia (antes de MediaWiki 1.29.0 solo tenía soporte MediaWiki) y el valor es una restricción de versión válida (cuyo formato debe coincidir con el utilizado por Composer).
En MediaWiki 1.29.0 y posterior también puedes añadir dependencias de apariencias y otras extensiones así:
{
"requires": {
"MediaWiki": ">= 1.29.0",
"extensions": {
"ExampleExtension": "*"
},
"skins": {
"ExampleSkin": "*"
}
}
}
- Las extensiones y apariencias especificadas aquí también deben utilizar el sistema de registro de extensiones descrito en esta página para que esto funcione.
- La cadena que se añade para especificar la extensión o apariencia debe ser idéntica a la cadena especificada en el campo «name» del archivo «extension.json» o «skin.json», respectivamente.
- Para extensiones que utilicen la integración continua de Wikimedia, también se deben añadir las dependencias en zuul/parameter_functions.py.
En MediaWiki 1.33.0 (¿?) y posterior, también puedes añadir dependencias de PHP así:
{
"requires": {
"MediaWiki": ">= 1.33.0",
"platform": {
"php": ">= 7.0.3"
}
}
}
Comprueba si una extensión está cargada sin necesidad
Muchas extensiones proporcionan funcionalidades que solo funcionan si también está cargada otra extensión sin que realmente haga falta esta funcionalidad para que la función de extensión del núcleo funcione. Por ejemplo: si la extensión B está cargada, la extensión A puede proporcionar un verdadero editor WYSIWYG, en otro caso, utilizará una sencilla área de texto. La extensión A puede beneficiarse de la extensión B (si está cargada), pero no requiere que esté cargada para funcionar adecuadamente. Para esto, generalmente se comprueba si la extensión está cargada en lugar de añadirla como dependencia dura (estricta).
Para implementar una forma estandarizada de comprobar si una extensión está cargada o no (sin necesidad de trabajo extra en una extensión que es una dependencia suave en otra extensión), se puede utilizar el registro de extensiones.
Implementa el método isLoaded, que devuelve un simple booleano que indica si la extensión está cargada o no (la extensión debe estar cargada con registro de extensiones para que esto funcione).
Ejemplo:
if ( ExtensionRegistry::getInstance()->isLoaded( 'ExtensionB' ) ) {
// hace cosas solo si la extensión B está cargada
}
| Versión de MediaWiki: | ≥ 1.32 Gerrit change 455752 |
A partir de MediaWiki 1.32, también es posible comprobar si una extensión está cargada y satisface una determinada restricción de versión de Composer:
if ( ExtensionRegistry::getInstance()->isLoaded( 'ExtensionB', '>=1.2' ) ) {
// hace cosas solo si la extensión B está cargada y tiene una versión 1.2 o mayor
}
Si deseas comprobar si una determinada versión de una extensión está cargada en versiones anteriores de MediaWiki, se puede extraer este tipo de información mediante el método getAllThings, que devuelve información de atribución de todas las extensiones cargadas. Ejemplo:
$bVersion = ExtensionRegistry::getInstance()->getAllThings()['ExtensionB']['version'] ?? null;
if ( $bVersion !== null && version_compare( $bVersion, '2.1.0', '>=' ) ) {
// hace cosas solo si la extensión B está cargada y tiene una versión mayor o igual que 2.1.0
}
Alternativamente, si la extensión B define una constante especial destinada a este propósito durante la carga, se puede comprobar si está definida:
if ( defined( 'ExtensionBVersion' ) ) { // You could also check for a version if the constant holds the version
// hace cosas solo si la extensión B está cargada
}
Una alternativa más frágil que debe evitarse consiste en comprobar si una determinada clase de la extensión B existe o no, por ejemplo, utilizando este código:
if ( class_exists( 'ExtensionBHooks' ) ) {
// hace cosas solo si existen las clases de la extensión B
}
Esto puede fallar si la extensión existe en el sistema de archivos pero no está cargada, por ejemplo, si se utilizó Composer para la autocarga. Si la clase fue renombrada o dejó de existir (por ejemplo, porque no es un paquete público), también provocará un fallo.
En general, es mejor compartir código mediante componentes de Composer que mediante extensiones. Si solo se requiere que las clases de una extensión, y no hace falta que la extensión esté configurada o cargada para lo que deseas hacer, es un fuerte indicador de que ese código debería dividirse en un componente de Composer que es en lo que deberías depender en su lugar.
Configuraciones (tus preferencias de extensiones/apariencias)
Por defecto, extension.json asume que tus parámetros de configuración empiezan por un prefijo «wg».
Si no es el caso, puedes redefinir el prefijo mediante una clave especial:
{
"config": {
"_prefix": "eg",
"MyExtSetting": true
}
}
Esto utilizaría un prefijo «eg» y fijaría la variable global $egMyExtSetting a true.
A partir de la versión 2 del manifiesto, la sección de configuración del registro de extensiones proporciona muchas más características y te permite describir tus opciones de configuración de forma mucho más detallada. En lugar de contar con un solo almacén clave -> valor para tus opciones de configuración, también puedes añadir la siguiente información.
La estructura general de config cambia ligeramente a la siguiente versión, más orientada a objetos:
{
"config_prefix": "eg",
"config": {
"MyExtSetting": {
"value": true,
"path": false,
"description": "La descripción de la configuración",
"descriptionmsg": "myextension-config-myextsetting",
"public": true
}
},
"manifest_version": 2
}
value
Se trasladó aquí el valor de la configuración. Esta es la única clave obligatoria para un objeto de configuración.
path
El valor booleano de la clave path identifica si el valor de la opción de configuración se debería interpretar como una ruta del sistema de archivos relativa al directorio raíz de la extensión.
Por ejemplo, si el valor de la configuración es myFile.png y path es true, el valor real será /path/to/the/wiki/extensions/MyExtension/myFile.png.
description
La clave description de una opción de configuración puede contener una cadena no localizada que se puede utilizar para explicar la opción de configuración a otros desarrolladores o a los usuarios (administradores de sistemas) de tu extensión.
También se puede utilizar como texto emergente en la sección de parámetros de la ficha informativa de extensión en la página de descripción de la extensión MediaWiki.org.
El valor de la clave de descripción generalmente no está expuesto en el frontal del wiki; sin embargo, ¡echa un vistazo a la visión general para más información sobre cómo se podría utilizar esta funcionalidad en el futuro!
descriptionmsg
También existe la posibilidad de añadir, a modo de descripción (descriptionmsg), una clave de mensaje del sistema interno de localización de MediaWiki, que, en el futuro, se utilizará para exponer la descripción en el frontal de la instalación de MediaWiki.
public / private
Esta opción es un booleano cuyo valor predeterminado es false, lo que significa que la opción de configuración y el valor están marcados como "private".
De momento, este valor no se utiliza en ninguna parte. Echa un vistazo a la visión general para saber más sobre esta opción.
Visión general
Los cambios mencionados anteriormente son asimismo pasos preparatorios para una gestión mejorada de la configuración en MediaWiki. Estos cambios nos permiten, por ejemplo, exponer las opciones de configuración de las extensiones en la interfaz de usuario de MediaWiki. Para esto se necesita el mensaje de descripción localizado (descriptionmsg y description) y la indicación de si se debe exponer o no la opción de configuración.
Autodescubrimiento de pruebas unitarias
MediaWiki permite a cualquier extensión registrar pruebas phpunit. Sin el registro de extensiones, sería necesario registrar un manejador de ganchos para el gancho UnitTestsList, que tendría un aspecto similar a este:
public static function onUnitTestsList( array &$paths ) {
$paths[] = __DIR__ . '/tests/phpunit/';
}
(como se describe en la página del manual). Sin embargo, este código tiene el mismo aspecto para muchas extensiones, por lo que podría considerarse una duplicación innecesaria de código.
Si tu extensión utiliza el registro de extensiones y tus pruebas phpunit se encuentran en el subdirectorio tests/phpunit/ de tu extensión, el contenedor phpunit de MediaWiki autodescubrirá las pruebas unitarias con la ayuda del registro de extensiones.
Por lo tanto, ya no tienes que registrar el gancho ni especificar que tus pruebas unitarias están almacenadas en el directorio predeterminado.
Categorías de seguimiento
| Versión de MediaWiki: | ≥ 1.25 |
A partir de MediaWiki 1.25, cualquier categoría que una extensión desee incluir en Special:TrackingCategories se debe registrar en extension.json:
{
"TrackingCategories": [
"myextension-tracking-category"
]
}
myextension-tracking-category es un mensaje de sistema que contiene el nombre de la categoría. La extensión la añade a las páginas mediante una llamada a Parser::addTrackingCategory().
Personalizar el registro
Y además composer.json
Si una extensión o apariencia tiene dependencias de bibliotecas, puede tener asimismo un archivo composer.json, véase Manual:Composer.json best practices. Utiliza el campo load_composer_autoloader para hacer que MediaWiki utilice la autocarga cuando sea apropiado.
Algunos campos de metadatos se superponen entre extension.json y composer.json (comentado en T89456), como los siguientes:
- $3 y $4
- $5 y $6
urlyhomepagelicense-nameylicense
Gestión del código
- Maintained by Unknown or Unassigned[Maintainers page].
- Issue tracker: Phabricator MediaWiki-Configuration (Report an issue)
Véase también
Documentación
- Manual:Extension.json/Schema
docs/extension.schema.v2.jsones el esquema paraextension.json(y skin.json).
- Limitaciones conocidas
- Visión general de la arquitectura
- Guía de migración - algunas recomendaciones a la hora de actualizar extensiones anteriores
Feedback
- Informa de errores en el proyecto MediaWiki-Configuration.
- RfC sobre implementar el registro de extensiones