Como crear una libreria externa e independiente en PHP que pueda ser importada desde composer usando packagist

Mientras inicio el desarrollo de una librería en PHP que sirva de cliente para el API de Twitter, únicamente como pasatiempo, y sirviéndome de la excelente librería de Abraham  llamada abraham/twitteroauth, he pensado en documentar todos los pasos que hago.

En esta primera entrega explicaré que pasos he seguido para crear una librería externa e independiente en PHP, y que sea usada libremente por la comunidad, gracias a composer, github y packagist.

Como prerequisitos tendremos el conoceer mínimamente y tener cuenta operativa en github y packagist. Así como un conocimiento también en git y composer.

Lo primero será crear un nuevo directorio en nuestro directorio principal del servidor web (normalmente /var/www/html).


mkdir twitterclient

Crearemos un fichero composer.json con este contenido mínimo:

{  
   "name":"cybtow/twitterclient",
   "type":"library",
   "description":"A client for API Twitter, based on abraham/twitteroauth",
   "keywords":[  
      "twitter",
      "api",
      "client"
   ],
   "license":"MIT",
   "authors":[  
      {  
         "name":"cybtow",
         "role":"Developer"
      }
   ],
   "support":{  
      "source":"https://github.com/cybtow/twitterclient",
      "issues":"https://github.com/cybtow/twitterclient/issues"
   },
   "require":{  
      "php":"^5.6 || ^7.0",
      "abraham/twitteroauth":"^0.7.4"
   },
   "autoload":{  
      "psr-4":{  
         "Cybtow\\TwitterClient\\":"src"
      }
   }
}

Los elementos principales son:

  • name: El nombre de la librería. Se compone de un prefijo, normalmente el autor (cybtow), y el nombre del proyecto (twitterclient).
  • type: En nuestro caso “library“, que indica que el proyecto será una librería independiente.
  • require: Las dependencias de nuestra librería, en este caso se especifica la versión mínima de PHP y la dependencia que tenemos con la librería que vamos a usar “abraham/twitteroauth“.
  • autoload: Indicamos que desde cualquier proyecto que incluya nuestra librería, nuestras clases situadas en el directorio “src” estarán disponibles en el namespace “Cybtow\TwitterClient“.

Podéis encontrar más información sobre la estructura del fichero composer.json en:

Ahora, desde nuestro directorio “twitterclient“, vamos a crear el directorio “src“, donde situaremos nuestro código fuente.


mkdir twitterclient/src

A continuación vamos a ejecutar composer, para asegurarnos que por el momento vamos bien, y prepare nuestro proyecto con las dependencias que hemos especificado.

Desde twitterclient ejecutamos


composer update

Un nuevo directorio “vendor” se ha creado, en él podremos encontrar las librerías externas con las que tenemos dependencias, en este caso únicamente la librería “abraham/twitteroauth“.

Una vez hecho esto, desarrollaremos nuestra librería.

En nuestro caso, y a modo de prueba, he creado un fichero en src, llamado TwitterClient.php.

Una vez tengamos nuestro código fuente creado (y probado), el siguiente paso será subir la librería al repositorio GitHub.

Respecto a GitHub deberemos tener una cuenta creada y correctamente configurada (incluyendo las claves SSH: https://help.github.com/articles/connecting-to-github-with-ssh/)

Dentro de nuestra cuenta en GitHub, crearemos un nuevo repositorio.

Una vez tengamos el repositorio creado, tendremos que crear un fichero .gitignore en el directorio principal de nuestra librería, con el fin de excluir la carpeta “vendor” (y en mi caso la carpeta que se auto-crea “nbproject” por ser Netbeans el IDE que uso) del repositorio Git.

El fichero tendrá este contenido:

/nbproject/
/vendor/

Bien, ahora estamos en disposición de subir el código al repositorio GitHub, creando una primera versión 0.1 para nuestra librería.

En consola, y desde nuestro directorio “twitterclient” haremos:


git init
git remote add github git@github.com:cybtow/twitterclient.git
git add .
git commit -m "First commit"
git tag -a 0.1 -m "version 0.1"
git push -u --tags github master

Una vez hecho esto, ya tendremos nuestro código fuente en GitHub, en nuestro caso concreto en https://github.com/cybtow/twitterclient, y ya estará disponible para que otros usuarios puedan usarlo.

Pero nosotros queremos ir un paso más alla, y queremos que nuestra librería pueda usarse como una dependencia más en un proyecto PHP usando composer (igual que hicimos nosotros con nuestra librería importando la librería externa “abraham/twitteroauth“).

Ahora, desde packagist, y teniendo una cuenta creada y activa, subiremos nuestra librería o paquete (package en inglés, este término es el usual en packagist).

En “Repository URL (Git/SVN/Hg)” pegaremos la URL de nuestro repositorio en GitHub, en este caso es: https://github.com/cybtow/twitterclient

Y pulsaremos el botón “Check“.

Una vez chequeado, pulsaremos el botón “Submit“.

¡Bravo! Desde este momento cualquier programador podrá incluir nuestra librería (o paquete o package) en sus proyectos. En este caso, la librería “cybtow/twitterclient” ya está disponible para que desde cualquier proyecto PHP, y usando composer, pueda ser incluida, simplemente haciendo desde dicho proyecto:


composer require cybtow/twitterclient

 

Si miramos el fichero composer.json del proyecto que está haciendo uso de nuestra nueva librería, veremos que se ha incluido la dependencia en la zona “require”.


"require": {
"php": ">=5.5.9",
"cybtow/twitterclient": "^0.1.0",

...

Modificaremos manualmente en el fichero composer.json el valor “^0.1.0” a “0.*“, para cuando en el futuro actualicemos nuestra librería (más adelante en este artículo lo hago), se actualice automáticamente desde composer update.

Pero aún no hemos terminado, porque también queremos que cada vez que subamos una nueva versión de nuestro proyecto a GitHub, se genere una nueva versión en Packagist, y así los usuarios puedan actualizarse automáticamente con su “composer update“.

Para ello haremos click en “GitHub Service Hook” de la página justamente anterior.

En la página que se abre nos dan las instrucciones de como configurar GitHub para que “avise” automáticamente a Packagist cuando haya cambios. Para ello haremos:

Desde nuestro proyecto “cybtow/twitterclient” en GitHub, seleccionamos “Settings“.

En el menú de la izquierda seleccionamos “Integrations & services

Pulsamos el botón “Add service” de la derecha, y seleccionamos “Packagist

Volvemos a la página principal de “Packagist” para ver cual es nuestro token secreto.

Rellenamos los datos de “user” y “token“.  Pero “domain” lo dejamos vacío.

Pulsamos el botón “Add service“.

Abrimos el servicio que se acaba de crear.

Y pulsamos en “Test service” para comprobar que todo ha ido bien.

Una vez hecho esto, nos volvemos a la web de Packagist, en concreto a nuestro proyecto recién creado, en nuestro caso “cybtow/twitterclient“: https://packagist.org/packages/cybtow/twitterclient

Y pulsamos el botón verde “Update“.

Tras pulsar “Update“, veremos como el mensaje “This package is not auto-updated. Please set up the GitHub Service Hook for Packagist” so that it gets updated whenever you push!” desaparece. Eso significa que cada vez que hagamos push a nuestro repositorio GitHub con una nueva versión de nuestra librería, Packagist será automáticamente actualizado.

Para comprobar que todo haya ido bien realizaremos un cambio en nuestra librería, por ejemplo añadir un comentario en algún fichero de código fuente, etiquetaremos una nueva versión (0.2), haremos push, y desde otro proyecto que incluya una dependencia a nuestra librería (cybtow/twitterclient) veremos como se actualiza automáticamente desde la versión 0.1 a la versión 0.2.

Actualizamos y publicamos nueva versión (después de realizar algún cambio en código fuente):


git add src/TwitterClient.php

git commit -m "Adding comment in header"

git tag -a 0.2 -m "version 0.2"

git push --tags github master

Si ahora recargamos la página de Packagist veremos que ya tenemos disponible la nueva versión 0.2.

Finalmente, desde otro proyecto que esté usando nuestra librería, actualizamos las dependencias y veremos como nuestra librería es actualizada:


composer update

Con esto concluyo este artículo, espero lo hayas disfrutado igual que yo escribiéndolo. Si te ha resultado útil, por favor ¡compártelo!

Anuncios

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s