Need Structured Documentation

[XedinUnknown]

Very often, I cannot understand how to work with this awesome tool, which could make life so much easier, without searching through the issues. My last case was in relation to auth. My regular use case is: I created a CLI tool, published it in a private GitHub repo, and want to install it into another application's environment.

• What are the supported ways of passing auth info to Phive, and how does it treat that?
  • Will it cache whatever it finds - into somewhere in the .phive directory?
    • In HOME or in project root?
    • auth.xml or phive-auth.xml?
    • Last time I specified GITHUB_AUTH_TOKEN env var, and it didn't get written into anywhere.
    • In a previous test, I had a .phive/auth.xml in project root (not sure how it got there). When I removed it, phive install --force-accept-unsigned <my-repo> still installed. I searched and searched for cached auth info, but couldn't find any:
      • Anywhere in .phive/ in project root.
      • No ~/.phive/auth.xml.
      • Not present in http-cache
      • No GITHUB_AUTH_TOKEN in environment.
      • The only thing that got the install to fail again - was re-building the Docker image, from which I run this
  • If I specify auth info in some auth.xml:
    • How should I know what to write there? Where can I find the spec/schema/template for that file?
    • Do I need to do this myself? Or will Phive generate it for me? What's the command to do that, if it exists?
• What exactly are valid ways to install a Phar?

  • I had first tried phive install https://github.com/vendor/package/releases/download/v0.2.0-beta1/my-app.phar. That didn't work:

    Could not extract PHAR version from my-app

    Apparently, there must be a version at the end of the Phar basename. How was I supposed to know that?

  • Then I added the version and tried phive install https://github.com/vendor/package/releases/download/v0.2.0-beta1/my-app-v0.2.0-beta1.phar. Didn't work:

    No matching release found for https://github.com/vendor/package/releases/download/v0.2.0-beta1/my-v0.2.0-beta1.phar

    Why does it need to look at any other releases, if I'm telling it to install from a specific URL? Is there another option for this, such as --url? How should I know this?

I mean no disrespect: this tool has the potential to ease a lot of installation for many peoplem, and to encourage the distrubution of PHP applications in a better way. But honestly, every time I interact with Phive - I spend a lot of time handling things that, looking at some other tools (package managers come to mind), seem like something I should take for granted. And most of this - is due to sparse documentation, rather than bugs or lacking features.

If I can help with some feedback or info - please let me know 🙏

[theseer]

I'll try to give phive and phar.io some love the upcoming weeks. Thanks a lot for the offer to help. I'll get back to you :)