20.5. Publicando tu plugin

20.5.1. Creando el paquete del plugin

Si quieres crear el paquete del plugin, debes añadir algunos archivos obligatorios a la estructura de directorios del plugin. En primer lugar, crea un archivo llamado README en el directorio raíz del plugin que contenga las intrucciones de instalación del plugin y que explique lo que proporciona y lo que no. Este archivo README debe estar escrito en el formato Markdown. Además, este archivo es el que utiliza el sitio web de Symfony para mostrar la información y documentación del plugin. Si quieres probar cómo se transforma tu archivo README al formato HTML, puedes utilizar la herramienta Symfony plugin dingus.

Además del archivo README, también debes crear un archivo llamado LICENSE. Elegir la licencia adecuada para tu plugin no es algo sencillo, pero la sección de plugins del sitio web de Symfony sólo muestra los plugins que se publican con una licencia similar a la del propio framework (MIT, BSD, LGPL y PHP). El contenido del archivo LICENSE se muestra en la pestaña "license" de la página del plugin.

El último archivo obligatorio se llama package.xml y debe estar en el directorio raíz del plugin. Este archivo package.xml se debe crear siguiendo la sintaxis de los paquetes PEAR.

La siguiente plantilla de ejemplo muestra las diferentes partes que componen el archivo package.xml:

<!-- plugins/sfJobeetPlugin/package.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<package packagerversion="1.4.1" version="2.0"
   xmlns="http://pear.php.net/dtd/package-2.0"
   xmlns:tasks="http://pear.php.net/dtd/tasks-1.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0
   http://pear.php.net/dtd/tasks-1.0.xsd http://pear.php.net/dtd/package-2.0
   http://pear.php.net/dtd/package-2.0.xsd"
>
  <name>sfJobeetPlugin</name>
  <channel>plugins.symfony-project.org</channel>
  <summary>A job board plugin.</summary>
  <description>A job board plugin.</description>
  <lead>
    <name>Fabien POTENCIER</name>
    <user>fabpot</user>
    <email>[email protected]</email>
    <active>yes</active>
  </lead>
  <date>2008-12-20</date>
  <version>
    <release>1.0.0</release>
    <api>1.0.0</api>
  </version>
  <stability>
    <release>stable</release>
    <api>stable</api>
  </stability>
  <license uri="http://www.symfony-project.com/license">
    MIT license
  </license>
  <notes />

  <contents>
    <!-- CONTENT -->
  </contents>

  <dependencies>
   <!-- DEPENDENCIES -->
  </dependencies>

  <phprelease>
</phprelease>

<changelog>
  <!-- CHANGELOG -->
</changelog>
</package>

La etiqueta <contents> especifica los archivos que contiene el paquete:

<contents>
  <dir name="/">
    <file role="data" name="README" />
    <file role="data" name="LICENSE" />

    <dir name="config">
      <file role="data" name="config.php" />
      <file role="data" name="schema.yml" />
    </dir>

    <!-- ... -->
  </dir>
</contents>

La etiqueta <dependencies> define todas las dependencias que tiene el plugin respecto a PHP, Symfony y/o el resto de plugins. Esta información es la que utiliza la tarea plugin:install para instalar la versión del plugin que mejor se adapta al entorno de trabajo y también para instalar todas las dependencias existentes con otros plugins.

<dependencies>
  <required>
    <php>
      <min>5.0.0</min>
    </php>
    <pearinstaller>
      <min>1.4.1</min>
    </pearinstaller>
    <package>
      <name>symfony</name>
      <channel>pear.symfony-project.com</channel>
      <min>1.2.0</min>
      <max>1.3.0</max>
      <exclude>1.3.0</exclude>
    </package>
  </required>
</dependencies>

Como se muestra en el ejemplo anterior, siempre deberías establecer la dependencia de tu plugin con Symfony. Al declarar la versión mínima y máxima de Symfony con las que el plugin es compatible, la tarea plugin:install puede determinar la versión de Symfony necesaria, ya que cada versión de Symfony contiene diferencias en su API.

También puedes declarar dependencias con otros plugins:

<package>
  <name>sfFooPlugin</name>
  <channel>plugins.symfony-project.org</channel>
  <min>1.0.0</min>
  <max>1.2.0</max>
  <exclude>1.2.0</exclude>
</package>

La etiqueta <changelog> es opcional, pero proporciona información útil sobre los cambios realizados por cada versión del plugin. Esta información se muestra en la pestaña "changelog" del plugin y también está disponible en el canal RSS de los plugins de Symmfony.

<changelog>
  <release>
    <version>
      <release>1.0.0</release>
      <api>1.0.0</api>
    </version>
    <stability>
      <release>stable</release>
      <api>stable</api>
    </stability>
    <license uri="http://www.symfony-project.com/license">
      MIT license
    </license>
    <date>2008-12-20</date>
    <license>MIT</license>
    <notes>
       * fabien: First release of the plugin
    </notes>
  </release>
</changelog>

20.5.2. Publicar un plugin en el sitio web de Symfony

Si has creado un plugin útil y quieres compartirlo con la comunidad de usuarios de Symfony, puedes crear una cuenta de usuario en el sitio web de Symfony y después crear tu plugin.

Una vez creado, te conviertes automáticamente en el administrador del plugin y por tanto, verás una pestaña llamada "admin" en la página del plugin. Desde esta pestaña puedes gestionar toda la información del plugin y puedes subir los paquetes de las nuevas versiones.