[TASK] Allow to load `guides.xml` when in composer mode

[garvinhicking]

When building a PHAR, or using this project as a composer dependency, the vendor/bin/guides binary could not be called due to a PHP error.

This is because the file guides.xml is referenced via vendor/../guides.xml. That works in the root of the main render-guides repository, but not in a composer environment.

There the correct location is vendor/t3docs/render-guides/guides.xml.

This PR adds a check to resolve that file in case the first try returns FALSE for the realpath() lookup.

Generally this lookup code is a bit spaghetti-ish and we should properly refactor this. For the time being, a hotfix like this would allow me to continue on using render-guides as a dependency in referring projects.

[jaapio]

@garvinhicking I just merged #824, does this solve your issue as well? the error might be gone, but I think you have a more specific use case for typo3, when the tool is installed via composer?

[fe-hicking]

No, doesnt fix mine because I need the fallback without ../ just like in this PR. Maybe you could look at it again, it doesn't do so much more than the one you merged apart from one more directory check...

[fe-hicking]

Ah, now I see the problem - I need to reference the guides.xml of a specific composer packe, but it's one that uses "guides" but it isn't guides itself.

So we'd probably need another configuration directive to specify the projectConfig file. Can I override that later on in the workflow, or do you have a suggestion how to specify the file without needing a patch so individual like mine?

[jaapio]

Maybe we should solve this in some way in the typo3 project, let's see if that's possible someway.

[wouterj]

The script tries to load the guides.xml file from 3 locations:

• The directory containing vendor/ (i.e. the project root)
• The working directory, either the current directory where the guides command is ran or the directory specified using the --working-dir option
• From any other directory specified by --config

[garvinhicking]

The script tries to load the guides.xml file from 3 locations:

• The directory containing vendor/ (i.e. the project root)
• The working directory, either the current directory where the guides command is ran or the directory specified using the --working-dir option
• From any other directory specified by --config

Let me try to rephrase the problems I have.

The TYPO3 render-guides composer package (not really, because this is not offered as a composer package...) requires this phpdocumentor/guides. The guides.xml file of the render-guides repository is thus part of the "root" project.

When checking out the render-guides repository, the file will be loaded because it matches "vendor-dir/../guides.xml". All good so far. Additionally, another config file can additionally be loaded from a subdirectory (e.g. render-guides/Documentation/guides.xml). That sub-directory guides.xml only has documentation-specific configuration, while the main guides.xml has some core-level configuration.

core-level example:

<?xml version="1.0" encoding="UTF-8" ?>
<guides
    xmlns="https://www.phpdoc.org/guides"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
    links-are-relative="true"
    theme="typo3docs"
>
    <extension class="\phpDocumentor\Guides\RestructuredText\DependencyInjection\ReStructuredTextExtension"/>
    <extension class="\phpDocumentor\Guides\Bootstrap\DependencyInjection\BootstrapExtension"/>
    <extension class="\phpDocumentor\Guides\Graphs\DependencyInjection\GraphsExtension"/>
    <extension class="\phpDocumentor\Guides\Markdown\DependencyInjection\MarkdownExtension"/>
    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"/>
    <extension class="\T3Docs\GuidesExtension\DependencyInjection\Typo3GuidesExtension"/>
    <extension class="\T3Docs\GuidesPhpDomain\DependencyInjection\GuidesPhpDomainExtension"/>
    <output-format>html</output-format>
    <output-format>singlepage</output-format>
    <output-format>interlink</output-format>
</guides>

project-level:

<?xml version="1.0" encoding="UTF-8" ?>
<guides
    xmlns="https://www.phpdoc.org/guides"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
    <project title="Render guides"/>
    <extension
        class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
        edit-on-github="TYPO3-Documentation/render-guides"
        edit-on-github-branch="main"
        interlink-shortcode="t3docsRenderGuides"
        typo3-core-preferred="stable"
    />
    <!-- explicitly link to stable versions of extensions -->
    <inventory id="georgringer/news/stable" url="https://docs.typo3.org/p/georgringer/news/11.3/en-us/"/>
    <inventory id="cobweb/external_import/stable" url="https://docs.typo3.org/p/cobweb/external_import/7.2/en-us/"/>
</guides>

Both files need to be loaded (not just one). If I read the code right, the first one is $projectConfig, and the second one is $localConfig in the packages/guides-cli/bin/guides script.

If I now create a package that uses the phar or composer package, when running it, the vendor/../guides.xml no longer resolves to the guides.xml that is specified in t3docs/render-guides. Because that is actually in vendor/t3docs/render-guides/guides.xml.

To get this all running, what we need is to be able to influence BOTh the $projectConfig AND $localConfig.

The current phpdocumentor/guides-cli implementation only makes $localConfig configurable, and NOT $projectConfig. When using the phar I could thus only either specify the guides.xml of my own project or the one of t3docs/render-guides -- but I would need both.

So in the end I would need the ability to specify:

• vendorConfig = vendor/t3docs/render-guides/guides.xml
• projectConfig = /pth/to/my/project/guides.xml
• localConfig = /path/to/my/project/Documentation/guides.xml

Currently that first one is the one I need to "map" to t3docs/render-guides but it is not configurable. So on top of --working-dir and --config I would probably need --vendor-config?!

I hope this explanation is better understandable now.