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

Curso gratis de Vue.js 2 en español

He encontrado un curso gratuito para Vue.js en su versión 2 muy completo y detallado, haciendo uso también de vídeo tutoriales.

El curso empieza por lo más básico, pasando por la potencia de Vue.js de creación y reutilización de componentes, el uso de vue-cli con webpack, así como la creación de una página SPA (single page application), y mucho más.

En el siguiente enlace podrás acceder a dicho curso: Curso gratuito de Vue 2, y también ponen a nuestra disposición el curso para la versión 1 de Vue.js.

Averiguar la velocidad de escritura de un directorio en Linux

El comando dd (dataset definition) nos permite, entre otras muchas cosas, poder conocer la velocidad real de escritura de un directorio (o partición ) en Linux.

La orden es sencilla:

dd if=/dev/zero of=/tmp/output bs=8k count=10k; rm -f /tmp/output

Donde /tmp, en este caso, se refiere al directorio que estamos comprobando. Si queremos comprobar otro, será tan sencillo como cambiarlo en las dos apariciones.

En este artículo podemos encontrar más información y usos del comando:
Uso del comando dd

Symfony2, instalando la extensión Text de Twig en Symfony 2.7

Sigo estudiando y haciendo pruebas con Symfony2 (2.7), ahora he querido usar el filtro truncate de la extensión Text del motor de plantillas Twig.

En todas las webs que he consultado dice que es muy simple, que simplemente añadiendo al fichero app/config/config.yml (o app/config/services.yml) lo siguiente, es más que suficiente:

services:
twig.extension.text:
class: Twig_Extensions_Extension_Text
tags:
– { name: twig.extension }

En mi caso no ha funcionado, siempre me salía este error cargando cualquier página de mi proyecto:

[SymfonyComponentDebugExceptionClassNotFoundException] Attempted to load class “Twig_Extensions_Extension_Text” from the global namespace. Did you forget a “use” statement?

Googleando veo que es necesario instalar dichas extensiones antes con la ayuda del composer:

composer require twig/extensions

Pero al ejecutarse me informa que Twig va por la versión 1.3, y que no puede instalar la extensión en el Twig de mi Symfony 2.7, que es la versión 1.18.2, que como mínimo necesita la 1.20.

Total, finalmente me decido por desinstalar el Twig, instalarlo de nuevo, y luego instalar las extensiones.

composer remove twig/twig

composer require twig/twig

composer require twig/extensions

Con esto lo que he hecho es quitar la versión Twig (1.18.2) que traía mi Symfony2 (2.7), instalar el Twig (me ha instalado el 1.21), y luego instalar las extensiones.

Por lo que ahora lo único que hay que hacer es activar dichas extensiones en el servicio Twig (fichero app/config/config.yml o app/config/services.yml):

services:
twig.extension.text:
class: Twig_Extensions_Extension_Text
tags:
– { name: twig.extension }

Y ya podemos usar la extensión Text en nuestro proyecto, por ejemplo, podemos usar los filtros truncate y wordwrap.