PHPWord: agregar marca de agua, TOC y gráficas a documento de Word con PHP

En este post vamos a ver cómo trabajar con documentos de Word usando el lenguaje de programación PHP y la librería PHPWord, parte de la familia de PHPOffice.

Lo que veremos será cómo:

  1. Agregar marca de agua a un documento
  2. Agregar un índice o tabla de contenido
  3. Trabajar con gráficas de barras, de pastel, de línea, etcétera

Este tutorial es la tercera parte de una serie de tutoriales sobre documentos de Word y PHP.

Recuerda ver la primera parte para ver cómo instalar la librería y su uso básico, así como la segunda parte para trabajar con listas, tablas e imágenes.

Marca de agua a documento de Word con PHP

Agregar una marca de agua es tan sencillo como agregar una imagen; solo que la misma se agrega a un encabezado o header, no a una sección.

Para agregar un encabezado se crea una sección, y después se llama al método addHeader.

Más tarde, se llama a $encabezado->addWatermark para poner una marca de agua; con dos argumentos: la ruta de la imagen y un arreglo con el estilo de la misma.

Después de haber agregado la marca de agua se puede agregar todo tipo de contenido a la sección: títulos, texto, más imágenes, etcétera.

Marca de agua a documento de Word con PHPWord

Nota: puedes ver el documento generado aquí.

Tabla de contenidos o índice

Para agregar un TOC o tabla de contenido addTOC de una sección.

Recuerda que existirá una tabla de contenido si hay títulos, así que debes separar el documento por título.

En el ejemplo le pasamos dos argumento a addTOC: en primer lugar un arreglo con la fuente y en segundo lugar un arreglo de opciones, el cual solo lleva la forma en la que separa el título del número de páginas, y lo hace a través de guiones bajos.

Estos separadores están definidos en la clase PhpOffice\PhpWord\Style\TOC.

Dentro del ejemplo se agrega un índice al inicio, y más adelante se agregan múltiples encabezados para que la tabla tenga contenido.

El resultado es el siguiente:

Tabla de contenido con PHPWord

Puedes ver el documento completo en este enlace.

Gráficas a documento de Word con PHP

Gracias a PHPWord podemos agregar múltiples gráficas y datos de una manera sencilla. Vamos a ver cómo trabajar con gráficas de dona (o como se diga en español), gráficas de pastel, de área (o como se diga en español), de barras y de líneas.

Gráfica de pastel con PHPWord

Las gráficas se agregan a una sección a través del método addChart, el cual recibe 3 argumentos:

  1. El tipo de gráfica que puede ser pie, doughnut, bar, column, line, area, scatter, radar, stacked_bar, percent_stacked_bar, stacked_column y percent_stacked_column.
  2. Las “categorías” o etiquetas, que son, si esto fuera un clave y valor, la clave. Aquí mostramos la etiqueta de cada valor, o su título. Va en forma de arreglo.
  3. Series o datos, que son los valores reales. Uno por cada etiqueta. Igualmente va en forma de arreglo
  4. Opciones de la gráfica como sus medidas o si son 3d. No todas las gráficas se pueden dibujar en 3d.

Adicionalmente hay algunas gráficas que soportan multiseries o múltiples datos, para agregar más datos a la gráfica debemos guardar lo que regresa addChart y luego llamar al método addSeries, con dos argumentos: las etiquetas y los valores que se agregan.

En el código usamos un conversor de medidas de la clase PhpOffice\PhpWord\Shared\Converter, llamando al método cmToEmu, centímetros a Emu (una unidad de medida especialmente para los estándares de estos documentos)

Gráfica con múltiples datos con PHPWord

Además de las gráficas podemos agregar títulos o texto como normalmente se hace.

Para indicar que una gráfica sea 3d ponemos la clave del arreglo “3d” en true.

Gráfica 3d a documento de Word con PHPWord

Mira todas las gráficas y el documento en este enlace.

Conclusión

Así concluyo esta serie de posts sobre PHPWord para la creación de documentos de Word usando PHP.

Por el momento no hay métodos documentados para leer un documento de Word, es decir, hacer el proceso inverso (al menos con esta librería)

Supongo que la complejidad es que a diferencia de las hojas de cálculo, un documento de Word no tiene una estructura definida (no solo tiene celdas).

Tal vez tiene secciones y las secciones tienen muchas cosas, pero será un lío hacer una manera fácil de leer los datos.

En fin, tal vez en un futuro se agreguen estas características para leer un documento de Word, aunque no lo veo tan necesario; pero tal vez a un cliente se le ocurra, uno nunca sabe.

La parte 1 de este tutorial está aquí, y la parte 2 aquí. El código con los ejemplos y archivos generados en mi GitHub, la librería también en GitHub y la documentación en readthedocs.