Fix PDF generation

[athos-ribeiro]

This is a first step into fixing the PDF generation.

This is done by substituting the now unmaintained libharu extension with a minimal FFI pakcage.

There are still a few nits that need fixing in the new implementation, but this first patch set is enough to revive the pdf docs generation.

I am aware there was a discussion regarding removing the pdf support from this repository. In case there is no interest in re-generating pdf docs, we can just close this PR :)

[kamil-tekiela]

Thank you. But do we really need this? What do we use PDF generation for?
Also, I belive FFI doesn't meet our minimum PHP requirement version.

[cmb69]

@athos-ribeiro, have you been able to generate the docs as PDF? If so, could you please upload this for inspection? I assume that a lot of "details" are not properly supported, and we should try to assess the required total cost of reviving PDF support.

[athos-ribeiro]

Thanks for the feedback, Kamil and Christoph.

Thank you. But do we really need this? What do we use PDF generation for?

This is a first step to fix unsupported/broken code. While the PHP doc group does not officially use the code for any documentation releasing purposes, a user could possibly come across these code snippets and try to build PDF docs for some reason, since the option is available.

I understand how adding a new package to handle that may be seen as "bloating the repository" to handle unsupported code. We could instead create the Haru FFI package as an external dependency for one willing to build PDF docs. This would reduce this patch set to a few lines fixing support to php 7 and using the external package instead of the haru ext.

Also, I belive FFI doesn't meet our minimum PHP requirement version.

FWIW, the current PDF related code doesn't meet the requirement versions either, since it requires PHP <= 5 AFAICT. With this changes, we would need PHP >= 7.4, which would only exclude 7.1 and 7.2 from the CI matrix (which is an improvement). We should also add a PHP version check if we are to proceed with this though.

@athos-ribeiro, have you been able to generate the docs as PDF? If so, could you please upload this for inspection? I assume that a lot of "details" are not properly supported, and we should try to assess the required total cost of reviving PDF support.

Yes, I could generate the docs. Still, as you mentioned, there are a few details to be worked on,keeping in mind that the PDF codebase has not been maintained for a while, so the PDF files presentation would need some working as well. Still, we can generate readable files for most of these docs.

Instead of uploading the output somewhere, I wrote this small shell script that would allow generating the output from a docker build. Is this enough for you to check the files? The benefit here would be to see the whole build process going on and spot the warnings and errors we still get with the build. If not, I can upload the pdf files somewhere.

#!/bin/bash

rm -rf ./output
IMAGE='localhost/php-pdf-docs:demo'
echo "Building ${IMAGE} ..."

docker build -t "${IMAGE}" - <<EOF
FROM ubuntu:kinetic
ENV TZ=UTC
RUN apt-get update
RUN DEBIAN_FRONTEND=noninteractive apt-get install -y tzdata git libhpdf-2.3.0 php php-dom php-sqlite3
WORKDIR /src
RUN git clone -b master https://github.com/php/doc-en en
RUN git clone -b master https://github.com/php/doc-base
RUN git clone -b fix-pdf-generation https://github.com/athos-ribeiro/phd
RUN php doc-base/configure.php
RUN php phd/render.php --docbook doc-base/.manual.xml --package PHP --format pdf
EOF

echo "Built ${IMAGE}"

CONTAINER=$(docker create "${IMAGE}")
docker cp "${CONTAINER}:/src/output" ./output
docker rm -f "${CONTAINER}"
docker rmi -f "${IMAGE}"