Error Running phpdox

[mikebronner]

I get the following error when running phpdox:

An application error occurred while processing:
The engine(s) 'graph' is/are not registered
Please verify your configuration.

Here is my config file (just basic to get up and running):

<phpdox xmlns="http://phpdox.net/config" silent="false">

    <project name="YourProject" source="app" workdir="${basedir}/build/api/xml">

        <collector publiconly="false" backend="parser">
            <include mask="*.php" />
            <exclude mask="*Autoload.php" />
        </collector>

        <generator output="${basedir}/build/api/docs">

            <build engine="html" enabled="true" output="html" />

            <build engine="todo" enabled="false" output="todo">
                <file name="todolist.txt" encoding="utf-8" />
            </build>

            <build engine="graph" enabled="true" output="graph" />

        </generator>
    </project>

</phpdox>

Is this an outdated file, should I be using a different one?

Thanks!

[mikebronner]

I was able to get this addressed by using the config file found on the web site (I got the config file above from a post about Jenkins-PHP somewhere).

But now I am finding that the {$basedir} variable in the config file doesn't work. Removing it seems to fix the problem.

[mikebronner]

Now I'm running into the following error:

[htmlpublisher] Archiving HTML reports...
[htmlpublisher] Archiving at BUILD level /var/lib/jenkins/workspace/project/build/api to /var/lib/jenkins/jobs/project/builds/2014-03-16_16-48-38/htmlreports/API_Documentation
ERROR: Directory '/var/lib/jenkins/workspace/project/build/api' exists but failed copying to '/var/lib/jenkins/jobs/project/builds/2014-03-16_16-48-38/htmlreports/API_Documentation'.
ERROR: This is especially strange since your build otherwise succeeded.
Build step 'Publish HTML reports' changed build result to FAILURE

Running phpDox from the command-line seems to run OK, and Jenkins isn't showing any errors. I have had to remove the {$basedir} variable from the phpdox.xml file though, to get this far. I also have moved phpdox.xml to the project root, instead of having it in the build folder.

Any ideas?

Something else I just thought of: I am running this on a vanilla install of Laravel. Would the above be the expected result if there are no doc blocks in the code?

[theseer]

Thank you for reporting your problems, as far as I can tell (luckily) neither qualifies as a bug.

1. The phpdox.xml configuration file you pasted is an interesting mix of outdated and up-to-date. While the namespaces is up to date, the graph engine as well as the todolist have been removed. Their output will return as a report as soon as I have the time to finish the report embedding.
2. The ${basedir} variable is resolved to the path of the phpdox.xml configuration file (as in, the path without the actual filename) - or by explicitly specifying an alternative value using the basedir attribute on the node. Since you didn't do the later, the basedir should be the former.
3. The error message you pasted from Jenkins suggest that actually generating an API Documentation should have worked. Can you verify that it actually do so?
4. Missing or incomplete DocBlocks do not affect phpDox in any way. Pretty much all documentation can be generated without having DocBlocks - it will just of course lag all the additional input they can provide.

[mikebronner]

Hi theseer,

1. You're right: the initial config file was doctored by me. No doubt in its original form it was completely outdated, but in the troubleshooting process I attempted to fix it, then ran into the graph issue and realized the entire thing must be wrong.
2. I see, thank you for clarifying how the {$basedir} variable works. I will update the config file accordingly.
3. I am unable to find any files at any point of the build process in build/api (which is what Jenkins-PHP is configured for). I also have "Keep Past HTML Reports" and "Allow Missing Report" checked in the Publish HTML Reports plugin. Here's the odd thing: if I run phpdox manually using:

phpdox -f build/phpdox.xml

It will generate the output files. However, if I run another build after that, the error returns. Here is my build file:

<?xml version="1.0" encoding="UTF-8"?>

<project name="YourProject" default="build" basedir=".">

    <target name="build"
        depends="build-common,phploc,pdepend,phpmd-ci,phpcs-ci,phpcpd,phpcb" />

    <target name="build-clean"
        depends="clean,build-common,phploc,pdepend,phpmd-ci,phpcs-ci,phpcpd,phpcb" />

    <target name="build-dox"
        depends="build-common,phpdox,phploc,pdepend,phpmd-ci,phpcs-ci,phpcpd,phpcb" />

    <target name="build-dox-clean"
        depends="clean,build-common,phpdox,phploc,pdepend,phpmd-ci,phpcs-ci,phpcpd,phpcb" />

    <target name="build-parallel"
        depends="build-common,tools-parallel" />

    <target name="build-parallel-clean"
        depends="clean,build-common,tools-parallel" />

    <target name="build-common" depends="lint,prepare,storage-permissions,composer,phpunit" />

    <target name="tools-parallel" description="Run tools in parallel">
        <parallel threadCount="2">
            <sequential>
                <antcall target="pdepend" />
                <antcall target="phpcs-ci" />
                <antcall target="phpmd-ci" />
            </sequential>
            <antcall target="phpcb" />
            <antcall target="phpcpd" />
            <antcall target="phpdox" />
            <antcall target="phploc" />
        </parallel>
    </target>

    <target name="clean" depends="clean-build,clean-composer" description="Cleanup build and composer artifacts" />

    <target name="clean-build" description="Cleanup build artifacts">
        <echo>Cleaning out the build artifacts</echo>
        <delete dir="${basedir}/build/api" />
        <delete dir="${basedir}/build/code-browser" />
        <delete dir="${basedir}/build/coverage" />
        <delete dir="${basedir}/build/logs" />
        <delete dir="${basedir}/build/pdepend" />
    </target>

    <target name="clean-composer" description="Cleanup composer artifacts">
        <echo>Cleaning out the composer artifacts</echo>
        <delete dir="${basedir}/vendor" />
        <delete file="${basedir}/composer.lock" />
    </target>

    <target name="composer" depends="composer-install,composer-update" description="Install or update dependencies" />

    <!--// Check to see it the vendor folder already exist, if so, then no reason to run //-->
    <target name="composer.check">
        <condition property="composer.exist">
            <available file="${basedir}/vendor" type="dir" />
        </condition>
    </target>

    <target name="composer-install" depends="composer.check" unless="composer.exist" description="Installing dependencies">
        <echo>Installing dependencies</echo>
        <exec executable="composer" failonerror="true">
            <arg value="install" />
        </exec>
    </target>

    <target name="composer-update" depends="composer.check" if="composer.exist" description="Updating dependencies">
        <echo>Updating dependencies</echo>
        <exec executable="composer" failonerror="true">
            <arg value="update" />
        </exec>
    </target>

    <target name="lint" description="Perform syntax check of sourcecode files">
        <apply executable="php" failonerror="false">
            <arg value="-l" />
            <fileset dir="${basedir}/app">
                <include name="**/*.php" />
                <modified />
            </fileset>
        </apply>
    </target>

    <target name="pdepend" description="Calculate software metrics using PHP_Depend">
        <exec executable="pdepend">
            <arg value="--jdepend-xml=${basedir}/build/logs/jdepend.xml" />
            <arg value="--jdepend-chart=${basedir}/build/pdepend/dependencies.svg" />
            <arg value="--overview-pyramid=${basedir}/build/pdepend/overview-pyramid.svg" />
            <arg path="${basedir}/app" />
        </exec>
    </target>

    <target name="phpcb" description="Aggregate tool output with PHP_CodeBrowser">
        <exec executable="phpcb">
            <arg value="--log" />
            <arg path="${basedir}/build/logs" />
            <arg value="--source" />
            <arg path="${basedir}/app" />
            <arg value="--output" />
            <arg path="${basedir}/build/code-browser" />
        </exec>
    </target>

     <target name="phpcpd" description="Find duplicate code using PHPCPD">
        <exec executable="phpcpd">
            <arg value="--log-pmd" />
            <arg value="${basedir}/build/logs/pmd-cpd.xml" />
            <arg path="${basedir}/app" />
        </exec>
    </target>

    <target name="phpcs"
         description="Find coding standard violations using PHP_CodeSniffer and print human readable output. Intended for usage on the command line before committing.">
        <exec executable="phpcs">
            <arg value="--standard=${basedir}/build/phpcs.xml" />
            <arg path="${basedir}/app" />
        </exec>
    </target>

    <target name="phpcs-ci" description="Find coding standard violations using PHP_CodeSniffer creating a log file for the continuous integration server">
        <exec executable="phpcs" output="/dev/null">
            <arg value="--report=checkstyle" />
            <arg value="--report-file=${basedir}/build/logs/checkstyle.xml" />
            <arg value="--standard=${basedir}/build/phpcs.xml" />
            <arg path="${basedir}/app" />
        </exec>
    </target>

    <target name="phpdox" description="Generate API documentation using phpDox">
        <exec executable="phpdox">
            <arg value="-f" />
            <arg value="${basedir}/build/phpdox.xml" />
        </exec>
    </target>

    <target name="phploc" description="Measure project size using PHPLOC">
        <exec executable="phploc">
           <arg value="--log-csv" />
           <arg value="${basedir}/build/logs/phploc.csv" />
           <arg path="${basedir}/app" />
        </exec>
    </target>

     <target name="phpmd" description="Perform project mess detection using PHPMD and print human readable output. Intended for usage on the command line before committing.">
        <exec executable="phpmd">
            <arg path="${basedir}/app" />
            <arg value="text" />
            <arg value="${basedir}/build/phpmd.xml" />
        </exec>
    </target>

    <target name="phpmd-ci" description="Perform project mess detection using PHPMD creating a log file for the continuous integration server">
        <exec executable="phpmd">
            <arg path="${basedir}/app" />
            <arg value="xml" />
            <arg value="${basedir}/build/phpmd.xml" />
            <arg value="--reportfile" />
            <arg value="${basedir}/build/logs/pmd.xml" />
        </exec>
    </target>

    <target name="phpunit" description="Run unit tests with PHPUnit">
        <exec executable="phpunit" failonerror="true">
            <arg value="-c" />
            <arg value="${basedir}/phpunit.xml.dist" />
            <arg value="--coverage-html" />
            <arg value="${basedir}/build/coverage" />
        </exec>
    </target>

    <target name="storage-permissions" depends="storage-permissions.unix,storage-permissions.windows" description="Setting storage permissions" />

    <target name="storage-permissions.unix" depends="storage.unix.check" if="storage.unix.exist" description="Setting storage permissions on unix">
        <echo>Setting app/storage to 777</echo>
        <chmod file="${basedir}/app/storage/**" perm="777" type="dir" failonerror="false" />
    </target>

    <target name="storage-permissions.windows" depends="storage.windows.check" if="storage.windows.exist" description="Setting storage permissions on windows">
        <echo>Setting app/storage to writable</echo>
        <attrib file="${basedir}/app/storage/**" perm="+R" failonerror="false" />
    </target>

    <!--// Check to see it the app/storage folder exist, if so, then can change permissions //-->
    <target name="storage.unix.check" description="Check for app/storage on unix">
        <condition property="storage.unix.exist">
            <and>
                <available file="${basedir}/app/storage" type="dir" />
                <os family="unix" />
            </and>
        </condition>
    </target>

    <!--// Check to see it the app/storage folder exist, if so, then can change permissions //-->
    <target name="storage.windows.check" description="Check for app/storage on windows">
        <condition property="storage.windows.exist">
            <and>
                <available file="${basedir}/app/storage" type="dir" />
                <os family="windows" />
            </and>
        </condition>
    </target>

     <target name="prepare" depends="clean-build" description="Prepare for build">
        <echo>Making the build artifact folders</echo>
        <mkdir dir="${basedir}/build/api" />
        <mkdir dir="${basedir}/build/code-browser" />
        <mkdir dir="${basedir}/build/coverage" />
        <mkdir dir="${basedir}/build/logs" />
        <mkdir dir="${basedir}/build/pdepend" />
    </target>
</project>

I wonder if there isn't a cleanup routine removing the files before the copy is taking place? Also, I don't see a link to the API Documentation anywhere on the Jenkins Project pages, which leads me to believe that it isn't working.

1. Thanks for clarifying that.

Thanks for your help! :)

[theseer]

Hi again,

1. That's the problem if people write tutorials about unfinished software. It's a moving target and since nobody tells me he or she wrote a tutorial I cannot notify them for updates :-/
2. No problem. Did that help at least?
3. For me, the most important message in this section is that phpDox seems to work fine when run individually. Reading the build.xml file only shows that - if i didn't miss a dependency - you remove everything and rebuild it all on pretty much every build target. Not sure if that is intended. Either way, this is out of scope for phpDox, so I'll be closing this bug.

[theseer]

In case you found a bug in the documentation on the Jenkins project pages, you should file a bug there :)

[mikebronner]

OK, thanks for looking into it. I have not been able to get it to run so far as part of the build process in Jenkins.

[theseer]

I'm sorry to hear that, but support for Jenkins related issues is beyond this issue tracker ;)