Added simple script to fetch API specs, #PG-5043

[lachiebol]

Description

NOTE: This OpenApiDocs change is needed to run this script matomo-org/plugin-ApiReference#30

Script to pull specs from cloud, default MATOMO_BASE_URL will be demo.matomo.cloud

MATOMO_BASE_URL="{matomo-url}" php fetch-openapi-specs.php

Checklist

• [✔] I have understood, reviewed, and tested all AI outputs before use
• [✔] All AI instructions respect security, IP, and privacy rules

Review

• Functional review done
• Potential edge cases thought about (behaviour of the code with strange input, with strange internal state or possible interactions with other Matomo subsystems)
• Usability review done (is anything maybe unclear or think about anything that would cause people to reach out to support)
• Security review done
• Wording review done
• Code review done
• Tests were added if useful/possible
• Reviewed for breaking changes
• Developer changelog updated if needed
• New documentation added or existing documentation updated

[AltamashShaikh]

we should use curl ideally for remote URLs

[AltamashShaikh]

Here it will keep continuing unnecessarily if file_put_contents fail, the issue would be consistent for all

[AltamashShaikh]

@lachiebol left few comments

[lachiebol]

@AltamashShaikh

From codex:

  1. High: the fetch is only atomic per file, not for the spec set, so a mid-run failure leaves the docs site serving a mixed snapshot. In fetch-openapi-specs.php:77, each plugin
     file is replaced immediately, and on the first later failure the script exits at fetch-openapi-specs.php:111. That means earlier plugins are now from the new Matomo instance/
     version, while untouched files still represent the previous run. Since the app reads whatever is present in app/public/openapi via app/helpers/OpenApiSpecRegistry.php:21, users
     can get a partially updated API reference without any indication it is inconsistent.

This doesn't seem too bad for our use case right? I know we could write to a tmp folder then move after everything is done.

Not sure if I need to address that one.

[AltamashShaikh]

@lachiebol AI review

High-risk issues (blocking)

  - Secret leakage in error output: fetch-openapi-specs.php:26 and fetch-openapi-specs.php:43 include the full request URL in thrown exceptions. That URL contains token_auth, so any network/API failure will print
    credentials to stderr via the top-level handlers at fetch-openapi-specs.php:71 and fetch-openapi-specs.php:112. For a script likely to run in CI or shared shells, that is a real credential exposure.
  - Stale spec files are never removed: the script only writes files for the current whitelist, but the docs app enumerates all matching files on disk via app/helpers/OpenApiSpecRegistry.php:21. If a plugin is removed
    from the whitelist or renamed, its old *_openapi_spec_v1.0.0.json file remains and will still be shown in the UI. That makes the generated docs drift from the source instance.

[lachiebol]

@lachiebol AI review

High-risk issues (blocking)

  - Secret leakage in error output: fetch-openapi-specs.php:26 and fetch-openapi-specs.php:43 include the full request URL in thrown exceptions. That URL contains token_auth, so any network/API failure will print
    credentials to stderr via the top-level handlers at fetch-openapi-specs.php:71 and fetch-openapi-specs.php:112. For a script likely to run in CI or shared shells, that is a real credential exposure.
  - Stale spec files are never removed: the script only writes files for the current whitelist, but the docs app enumerates all matching files on disk via app/helpers/OpenApiSpecRegistry.php:21. If a plugin is removed
    from the whitelist or renamed, its old *_openapi_spec_v1.0.0.json file remains and will still be shown in the UI. That makes the generated docs drift from the source instance.

Secret leakage in error output: Should only be leaking token_auth anonymous but can remove that

Stale spec files are never removed: Can fix that one

[AltamashShaikh]

@lachiebol Looks good we can test it together after deployment and I should be able to create a cron for you