search

phar-io / phar.io

Website of the phar.io project
https://phar.io
45 stars 53 forks source link

Document phive.xml file structure #139

Open MacDada opened 1 year ago

MacDada commented 1 year ago

Install all phar files declared in phive.xml

phive install

  1. From what I've read somewhere else, it should be .phive/phars.xml now?
  2. What should it contain?
  3. An example would be nice
theseer commented 1 year ago

Good questisons. Let's see how to answer them:

  1. Yes and no. Phive will, when started on a new project, create .phive/phars.xml but it will always honor phive.xml in the current directory when one exists. Maybe we should make that more clear.

  2. You should not be required to manually edit that file, so we so far never bothered to explain exact construction. It will contain the list of phars you installed, the target path, the version constraint specified and the currently installed version. It also keeps a flag, whether to copy the phar or symlink it (the later being the default).

  3. Valid point.

MacDada commented 1 year ago
  1. Yes and no. Phive will, when started on a new project, create .phive/phars.xml but it will always honor phive.xml in the current directory when one exists. Maybe we should make that more clear.

I already understand that, but only because I read all the issues in the project's github repository – so yeah, it could use some explanation in the docs ;-)

As for my opinion in the matter: YAGNI :P If there is only one config file, I'd just stick to /phive.xml. Only when we'd have actually more config files I might add the folder structure.

But well… It is what it is now…

So… To me the best option would be to recommend using the default /.phive/phars.xml, while stating that /phive.xml is still working for backwards compatibility.

BTW, what happens if both files exist and differ? Which one has priority? Or is there an error? This could be clarified in the docs as well.

You should not be required to manually edit that file

Okeeeey… And how can I know that from reading the docs? :D I mean, I've read the docs, I've read the issues, I have even used Phive a few years ago… And I'm still not sure what's the real–world workflow with this tool – but that's probably a thing for another issue ;-) I need to figure it all out myself first, I guess.

theseer commented 1 year ago

Understood.

I'll try to keep that in mind when updating the site.