Typical workflow to use Phive in a project

[hussainweb]

I am exploring Phive and I see the value of the project and the concept. I am figuring out how to best use it in our existing workflows. I tried looking at the documentation and searching on the web and in Github issues to learn more. Unfortunately, this is still largely opaque to me.

I am mainly wondering what is the typical workflow people tend to use in their projects. It is clear to me that we would commit the phive.xml file but there are other questions.

1. Would you commit the tools directory? I'd rather not but I don't see any references to adding the directory to .gitignore. I know I can add it myself, of course, but I was wondering if there is a reason it's not there.
2. Is there a way to add the tools directory to the $PATH or would you rather add some other location to the path? (~/.phive/phars has different file names and it's not convenient.)
3. If I start without a phive.xml, it creates a file ./.phive/phars.xml. That appears to be the same structure as phive.xml. Which one should I prefer? Should I commit the .phive directory?
4. Using phive in a subdirectory of the project creates the files there. Is there a way to make it run in the project root context? I suppose I am more worried about executing the tools from any subdirectory (hence question 2) but I was curious about this as well.

[theseer]

Hi there,

glad you see a value in using phive :)
Your questions make it clear we still have a long way to go to document things. Maybe these answers will eventually get converted into web pages...

I am mainly wondering what is the typical workflow people tend to use in their projects. It is clear to me that we would commit the phive.xml file but there are other questions.

Just to confirm: Yes. Having the phive.xml commited into the repository is indeed the intended way of use.

1. Would you commit the tools directory? I'd rather not but I don't see any references to adding the directory to .gitignore. I know I can add it myself, of course, but I was wondering if there is a reason it's not there.

Adding the tools directory only makes sense when you let phive copy the phars rather than - as the default would be - create symbolic links. Having symlinks in git is not very helpful if you didn't add the source ;)

Whether or not you should add it, depends on your workflow and to some extend the type of project: While there is no official recommendation, the same line of thought applies as for composer: If you're creating a library or component that is to be shared with (potentially many) others, having an unnecessary large repository including things a regular use wouldn't need, tools (or vendor) should not be commited along. If, on the other hand, you're dealing with an "end" product, like say a website, that is rather unlikely to be included into other projects ;) having all the tools (and vendor) along, makes a lot of things a lot easier. Like CI Runs for instance.

2. Is there a way to add the tools directory to the $PATH or would you rather add some other location to the path? (~/.phive/phars has different file names and it's not convenient.)

Having tools in the $PATH implies to me the installation is global. Phive has a switch for that, which usually means to install into /usr/local/bin. I don't see a use case for having a project local installation - which is phive's default behavior - be in $PATH. All build automation tools I know of come with some form of variable referencing the current or project directory. So calling tools relatively from or to that shouldn't be a problem. The idea here is very much to not have common version but have each project keep its own. So you can use different versions of the tool of choice per project.

3. If I start without a phive.xml, it creates a file ./.phive/phars.xml. That appears to be the same structure as phive.xml. Which one should I prefer? Should I commit the .phive directory?

It's indeed identical. The phive.xml is the original file to keep track of things. We moved that for new projects to be .phive/phars.xml while of course supportring the original location as well. So when the original file is present, phive will keep making use of it.

The change was made to allow for additional configuration settings that will be spread over various files but not to clutter the project root directory.

4. Using phive in a subdirectory of the project creates the files there. Is there a way to make it run in the project root context? I suppose I am more worried about executing the tools from any subdirectory (hence question 2) but I was curious about this as well.

I'm not sure I understand this question. Phive, unless told to do otherwise, assumes the current work directory to be the one to base its work on. So tools will be created if missing. And .phive/phars.xml will be created or updated. We currently do not have a means of telling phive where an alternative root directory would be and phive isn't trying to find it like git. Was that your question?

[hussainweb]

Thank you for your answers.

1. I appreciate you saying that the same line of thought applies to phive as composer. This is what I was looking for. :)
2. I can imagine using composer would make it possible to point to the correct directory. That way, I can run the tools from any subdirectory without having to refer to it as ../../../tools/phpcs, for example. If I do this, it makes sense to integrate more with composer. I know there's a plugin and I will look more into that.
3. This answers my question. I will stick to using .phive directory.
4. Yes, that was my question. This is related to my second question and I think I got my answer here. I wish there was a way but then you would have to duplicate composer-like or git-like functionality and maybe you don't want that. I mean, I was imagining a solution like running phive phpcpd from any subdirectory and phive will find and run it from the correct path. That could be a big change and I can't suggest either way because I don't have a lot of context. Meanwhile, I have composer to run these for now.

[theseer]

Thank you for your answers.

1. I appreciate you saying that the same line of thought applies to phive as composer. This is what I was looking for. :)

👍

2. I can imagine using composer would make it possible to point to the correct directory. That way, I can run the tools from any subdirectory without having to refer to it as `../../../tools/phpcs`, for example. If I do this, it makes sense to integrate more with composer. I know there's a plugin and I will look more into that.

As far as I know, composer's default location for installing an 'executable' is ./vendor/bin. That's hardly different then phive's ./tools. It seems also a common practice to run everything with the project root directory as current work directory, making a call tools/app-of-choice or vendor/bin/app-of-choice, respectively.

3. This answers my question. I will stick to using `.phive` directory.

👍

4. Yes, that was my question. This is related to my second question and I think I got my answer here. I _wish_ there was a way but then you would have to duplicate composer-like or git-like functionality and maybe you don't want that. I mean, I was imagining a solution like running `phive phpcpd` from any subdirectory and phive will find and run it from the correct path. That could be a big change and I can't suggest either way because I don't have a lot of context. Meanwhile, I have composer to run these for now.

I'm not sure I'm understanding what you'd like to have here. If you have $projectRoot/src and you enter the src directory, a call to composer will not work directly as the composer.json is likely placed in the $projectRoot directory. You'd have to specify -d.. or something alike to point it to the right location - or interactively confirm what composer tried to find as a possible composer.json to use. Apart from the fact I consider that an edge case barely worth considering (the manual overhead to always specify an alternative -d is just waste of time), it won't change anything with regards to where the tool in question will be and you won't have it in the path.

I'd recommend using build automation tools that encapsulate the calls as needed and, depending on your build tool of choice, make it work from whatever subdirectory you are in.

[hussainweb]

You're right. I was mixing up composer with some other tool. I'm curious though. Can you give me an example of a build automation tool you mentioned? I keep thinking of composer scripts or Makefiles but there could be more appropriate ones.

[MacDada]

I'd wish that https://phar.io/ would document this kind of stuff. Maybe a FAQ section?

The first thing, that was confusing to me, was reading…

Install all phar files declared in phive.xml

phive install

…and then not being able to find the section describing how the phive.xml should look like ;-)

phar-io/phar.io#139

[theseer]

The website indeed would need some love... As would phive itself. I have so many things in my head i'd like to implement but so little time :-/

I'll try to update some things here as soon as I can to make things more obvious.