From 5c8496802b9948be10505c6d4187677b69163ffc Mon Sep 17 00:00:00 2001 From: gggeek Date: Thu, 5 Jan 2023 21:13:54 +0000 Subject: [PATCH] improve doc build toolchain to use latest phpdocumentor; one fix to the manual --- .gitignore | 4 +++ doc/build/composer.json | 2 ++ doc/build/convert.php | 5 ++-- doc/build/generate.sh | 11 +++++--- doc/build/setup_tools.sh | 44 ++++++++++++++++++++++++++------ doc/manual/phpxmlrpc_manual.adoc | 4 +-- 6 files changed, 55 insertions(+), 15 deletions(-) mode change 100644 => 100755 doc/build/setup_tools.sh diff --git a/.gitignore b/.gitignore index 9eb7cb7d..420d1383 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,11 @@ /.idea /doc/api /doc/build/.phpdoc +/doc/build/.phive /doc/build/composer.lock +/doc/build/docbook-xsl +/doc/build/phive +/doc/build/phpDocumentor /doc/build/vendor /doc/manual/phpxmlrpc_manual.html /doc/manual/phpxmlrpc_manual.pdf diff --git a/doc/build/composer.json b/doc/build/composer.json index 64b8c470..cec16710 100644 --- a/doc/build/composer.json +++ b/doc/build/composer.json @@ -7,6 +7,8 @@ "docbook/docbook-xsl": "^1.79", "phpdocumentor/phpdocumentor": "^2.9.1 || ^3.1.2" }, + "minimum-stability": "dev", + "prefer-stable": true, "repositories": [ { "type": "package", diff --git a/doc/build/convert.php b/doc/build/convert.php index 96c1730b..2ca35fe9 100644 --- a/doc/build/convert.php +++ b/doc/build/convert.php @@ -14,6 +14,7 @@ if ($_SERVER['argc'] < 4) { $doc = $_SERVER['argv'][1]; $xss = $_SERVER['argv'][2]; $target = $_SERVER['argv'][3]; +$docbookDir = isset($_SERVER['argv'][4]) ? $_SERVER['argv'][4] : './build/vendor/docbook/docbook-xsl'; if (!file_exists($doc)) error("KO: file $doc cannot be found"); @@ -23,8 +24,8 @@ if (!file_exists($xss)) info("Starting xsl conversion process..."); // Replace tokens in the existing xslt file -$docbookFoXslPath = realpath('./build/vendor/docbook/docbook-xsl/fo/docbook.xsl'); -$docbookChunkXslPath = realpath('./build/vendor/docbook/docbook-xsl/xhtml/chunk.xsl'); +$docbookFoXslPath = realpath($docbookDir.'/fo/docbook.xsl'); +$docbookChunkXslPath = realpath($docbookDir.'/xhtml/chunk.xsl'); file_put_contents( $xss, str_replace( diff --git a/doc/build/generate.sh b/doc/build/generate.sh index f15b7dc3..179c2acc 100755 --- a/doc/build/generate.sh +++ b/doc/build/generate.sh @@ -2,11 +2,16 @@ set -e -cd "$(dirname -- "$(dirname -- "${BASH_SOURCE[0]}")")" +cd "$(dirname -- "$(dirname -- "$(realpath "${BASH_SOURCE[0]}")")")" + +PHPDOC='./build/phpDocumentor' +DOCBOOKXSLTDIR='./build/docbook-xsl' +#PHPDOC='php ./build/vendor/bin/phpdoc' +#DOCBOOKXSLTDIR='./build/vendor/docbook/docbook-xsl' ### API docs -php ./build/vendor/bin/phpdoc run --cache-folder './build/.phpdoc' -d "$(realpath ../src/)" -t './api' --title PHPXMLRPC --defaultpackagename PHPXMLRPC +$PHPDOC run --cache-folder './build/.phpdoc' -d "$(realpath ../src/)" -t './api' --title PHPXMLRPC --defaultpackagename PHPXMLRPC ### User Manual @@ -18,6 +23,6 @@ php ./build/vendor/bin/phpdoc run --cache-folder './build/.phpdoc' -d "$(realpat # PDF file from asciidoc via docbook and apache fop # @todo test: is it faster to use pandoc+texlive (including tools download time)? Does it render better? asciidoctor -d book -b docbook -o './build/phpxmlrpc_manual.xml' './manual/phpxmlrpc_manual.adoc' -php ./build/convert.php './build/phpxmlrpc_manual.xml' './build/custom.fo.xsl' './manual/phpxmlrpc_manual.fo.xml' +php ./build/convert.php './build/phpxmlrpc_manual.xml' './build/custom.fo.xsl' './manual/phpxmlrpc_manual.fo.xml' "$DOCBOOKXSLTDIR" fop ./manual/phpxmlrpc_manual.fo.xml ./manual/phpxmlrpc_manual.pdf rm ./build/phpxmlrpc_manual.xml ./manual/phpxmlrpc_manual.fo.xml diff --git a/doc/build/setup_tools.sh b/doc/build/setup_tools.sh old mode 100644 new mode 100755 index c4aa14ad..0339a91a --- a/doc/build/setup_tools.sh +++ b/doc/build/setup_tools.sh @@ -8,15 +8,43 @@ sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \ asciidoctor fop git unzip zip PHPPKG=$(dpkg --list | grep php | grep cli | grep -v -F '(default)' | awk '{print $2}') -sudo DEBIAN_FRONTEND=noninteractive apt-get install -y "${PHPPKG/cli/xsl}" +sudo DEBIAN_FRONTEND=noninteractive apt-get install -y \ + asciidoctor \ + curl \ + gpg \ + "${PHPPKG}" \ + "${PHPPKG/cli/xsl}" \ + unzip cd "$(dirname -- "${BASH_SOURCE[0]}")" -# in case we are switching between php versions, always reinstall every tool with the correct version... -if [ -f composer.lock ]; then - rm composer.lock -fi -composer install --no-dev -#sudo chown -R "$(id -u):$(id -g)" vendor +# Install phpdocumentor and the docbook xslt using Composer +# Sadly this method, as of 2023/1, does not allow installing version 3.3.0 and later +## in case we are switching between php versions, always reinstall every tool with the correct version... +#if [ -f composer.lock ]; then +# rm composer.lock +#fi +#composer install --no-dev # required as of phpdoc 3.1.2 -sed -r -i -e "s|resource: '%kernel\\.project_dir%/vendor/phpdocumentor/reflection/src/phpDocumentor/Reflection/Php'|resource: '%kernel.project_dir%/../reflection/src/phpDocumentor/Reflection/Php'|g" ./vendor/phpdocumentor/phpdocumentor/config/reflection.yaml +#sed -r -i -e "s|resource: '%kernel\\.project_dir%/vendor/phpdocumentor/reflection/src/phpDocumentor/Reflection/Php'|resource: '%kernel.project_dir%/../reflection/src/phpDocumentor/Reflection/Php'|g" ./vendor/phpdocumentor/phpdocumentor/config/reflection.yaml +#sudo chown -R "$(id -u):$(id -g)" vendor + +# Install the DocBook xslt +if [ ! -d docbook-xsl ]; then + curl -fsSL -o dbx.zip "https://github.com/docbook/xslt10-stylesheets/releases/download/release/1.79.2/docbook-xsl-1.79.2.zip" + unzip dbx.zip + mv docbook-xsl-1.79.2 docbook-xsl + rm dbx.zip +fi + +# Install phpdocumentor via Phive +# @todo wouldn't it be quicker to just scan the github page for the last release and just get the phar? +curl -fsSL -o phive "https://phar.io/releases/phive.phar" +#curl -fsSL -o -O phive.phar.asc "https://phar.io/releases/phive.phar.asc" +#gpg --keyserver hkps://keys.openpgp.org --recv-keys 0x6AF725270AB81E04D79442549D8A98B29B2D5D79 +#gpg --verify phive.phar.asc phive.phar +#rm phive.phar.asc +chmod +x phive +./phive install --trust-gpg-keys F33A0AF69AF7A8B15017DB526DA3ACC4991FFAE5 -t "$(pwd)" phpdocumentor + +#sudo chown -R "$(id -u):$(id -g)" vendor diff --git a/doc/manual/phpxmlrpc_manual.adoc b/doc/manual/phpxmlrpc_manual.adoc index a7a15191..68d3d10b 100644 --- a/doc/manual/phpxmlrpc_manual.adoc +++ b/doc/manual/phpxmlrpc_manual.adoc @@ -1144,8 +1144,8 @@ to trigger execution of uncontrolled PHP code on your server, opening the door t enable this option when you trust completely the remote server/client. DO NOT USE THIS WITH UNTRUSTED USER INPUT Note also that there are multiple limitations to this: the same PHP class definition must be available on both ends of -the communication; the class constructor will be called but with no parameters at all, and methods such as `__unserialize` -or `__wakeup` will not be called. Also, if a different toolkit than the phpxmlrpc library is used on the receiving side, +the communication; the class constructor will be called but with no parameters at all, and methods such as `+__unserialize+` +or `+__wakeup+` will not be called. Also, if a different toolkit than the phpxmlrpc library is used on the receiving side, it might reject the generated xml as invalid. === Code generation, Proxy objects & co. -- 2.47.0