Compile Releases into Phar files

[quicksketch]

PHP Archives (Phar files) can be very useful to bundle together all the code of a PHP project into a single file. This can make deployment to servers or local environments easier because only a single file needs to be downloaded instead of an archive that expands to a directory. It's also potentially useful because the phar file can act as an executable directly, so there's no need to set up a path alias routing bee.php to just bee.

It would be nice is bee started creating releases on GitHub, and with each release it packaged a phar file for download. There are existing Marketplace actions like https://github.com/marketplace/actions/box-packager-for-phar that could be used, or a custom workflow could be created such as the example at https://github.com/sergeyklay/gh-actions-php-phar-create-release-example/tree/master/.github/workflows (both use the same underlying "box" project to create the phar file).

[ghost]

Phar out dude!

You want to install Bee from aPhar...?

This is by Phar the best idea I've heard!

</puns>

[yorkshire-pudding]

@quicksketch - I've been talking with @indigoxela about how we progress the idea of releases. Please can you confirm that adding releases to bee which doesn't have a .info file will not make it appear in the project installer? At present, the only release is marked as a pre-release which doesn't show up, but I wanted to double check that it won't cause a problem for the installer or the https://backdropcms.org/project/bee page.

[quicksketch]

Making a release will not make a corresponding project release node (or .zip package) for any project that does not have a .info file, but you will probably get a PACKAGING_ERRORS.txt (or something similar) attached to the GitHub release that says that a .info file is required. However this file can then be deleted from the GitHub release.

[indigoxela]

Some trial and recherche...

Box is a cool tool and easy to handle, tested it locally and was able to create a bee.phar with little effort.

The second example link from the description (gh-actions-php-phar-create-release-example) is very helpful. If I got things right, we could automatically - on tag creation - also create a (drafted) release and the "artifact" (bee.phar) would get attached as an asset.

If we run into trouble with the PACKAGING_ERRORS.txt file getting in the way, we could stick with pre-release (GH) - or would that still produce errors? Another option would be to move Bee to backdrop-ops.

Steps for a release (my current understanding):

• Set the version constant
• Create a tag (same as version string), also drafts a release
• Polish the release and publish (as pre-release)
• Set back version constant

[quicksketch]

If we run into trouble with the PACKAGING_ERRORS.txt file getting in the way, we could still stick with pre-release (GH) - or would that still produce errors? Another option would be to move Bee to backdrop-ops.

You can also simply delete the PACKAGING_ERRORS.txt file every time it gets attached. Not perfect, but I don't think it would do harm.

[yorkshire-pudding]

I've run a couple of tests and deleting the packaging errors text is really not onerous so I think we can go for full releases. This will avoid confusion for users and allow update scripts to target the latest.

I've never used Phar files but happy to include this as an asset type in a release. I think we're getting there. I'll write some documentation

[yorkshire-pudding]

If I got things right, we could automatically - on tag creation - also create a (drafted) release and the "artefact" (bee.phar) would get attached as an asset.

Perhaps I'm missing something, but in the GitHub UI, the tag is created on publish. I think we would want this to be created when the release was published.

When I create a release in the GitHub UI then I:

1. Click on Draft a new release
2. In tag, enter the tag name (e.g. 1.x-1.0.1) and select '+ Create new tag 1.x-1.0.1 on publish'
3. Normally enter the tag in the title so it is clear from the front page of the repo
4. Write the release notes
5. Click 'Publish release'

At point 5, the tag is created. I've never created tags by pushing from my local as I nearly always do things via my fork (so I can keep all the issue branches away from the main repo)

I think we want it to run when we do Publish release.

I have a question about phars. Do they have to be targeted at a version of PHP or do they have the same compatibility that the original files have?

[indigoxela]

The tag is either created at publish (when it's new and you select to create it), or you can create a tag any time. Like in vanilla git. You can also publish already existing tags... However, as you are maintainer, you choose the right workflow for yourself. :wink: If we ever decide to create phar files, anyway. So far there's probably not enough feedback for that.

The phar file is compatible with whatever PHP versions the source code is compatible with.

[izmeez]

Yes, please, a phar download will be great.

[totten]

PHARs are great - lots of ways to deploy them.

FWIW, I put this box.json into a local copy of bee.git:

$ vi box.json

{
    "chmod": "0755",
    "directories": ["commands", "includes"],
    "compactors": ["KevinGH\\Box\\Compactor\\Php"],
    "git-version": "package_version",
    "main": "bee.php",
    "output": "bee.phar",
    "stub": true
}

$ box compile
$ cp bee.phar ~/bin/bee
$ cd /path/to/my/backdrop
$ bee uli

It generally seemed to work. :smile:

I guess there could be issues in certain subcommands or options, but it seems like y'all have kept dependencies thin and have past experience with drush. So probably the style/discipline is amenable...

I have a question about phars. Do they have to be targeted at a version of PHP or do they have the same compatibility that the original files have?

The phar file is compatible with whatever PHP versions the source code is compatible with.

Same experience. (And I've built more than my fair-share of PHARs...)

Just to emphasize: box's build-time requirement differs from the run-time requirement. New versions of box will periodically raise the build-time requirements. So, for example, when I adopted box@4.6.1 I had to switch the build-step to use php82. But the resulting .phar works fine in php73. (To my eye, box@4.6 may get fussy if you need php71 or older, but I bet that has a workaround.)

The first few times when I updated box, I felt a bit paranoid/distrustful. (Why do you change the build-time requirements?! I need to keep my runtime target!). But it's always worked out. Think of .phar as being like .zip or .tar -- as long as the file-format stays the same, it's OK to use different tools/libraries/versions for building. (The formats change rarely... like "once a decade" not "once a week".)

[herbdool]

We're working on getting bee included in the CiviCRM build kit, so this would be a good improvement for that.

[herbdool]

I've created a PR: https://github.com/backdrop-contrib/bee/pull/367 @yorkshire-pudding. I recommend we include this and then we can manually build the phar on our local computer and then upload it to the appropriate release. In my testing it built correctly and I was able to use bee.phar to run commands.

[yorkshire-pudding]

I've created a PR: #367 @yorkshire-pudding. I recommend we include this and then we can manually build the phar on our local computer and then upload it to the appropriate release. In my testing it built correctly and I was able to use bee.phar to run commands.

Thanks for this @herbdool - I've tested it out and it creates a phar file ok, once I figured out how to install box. I need to think about the best workflow that will work for me. I'm looking at a GitHub Action but need to do some testing.

[herbdool]

@yorkshire-pudding that's good. Why not just upload your manually created phar to the release? At least for the short term. You can edit the release in GitHub and add arbitrary files.

[yorkshire-pudding]

Re-open as need to add box to the lando recipe