Make the PHAR "website" a little more fancy #1156

benno5020 · 2025-06-30T22:22:05Z

This PR updates the gh-pages branch by styling the pages and adding a script to generate a listing of all downloadable phars.

Description

See #107

The pages are responsive and provide a light and dark mode.
I did not want to add any bloat so there is no build tooling at all.
I have prefixed the template and the php script with an underscore because I believe that will keep them from being served by GitHub Pages. Please verify that this behaves as expected.
I have linked the sources for the icons in my commit messages.
Please note that phars.html displays the git committer date of each file (https://git-scm.com/docs/pretty-formats). I wasn't sure what else to show as filemtime would not be right.
I did not look into generating phive.xml (as mentioned here: Make the PHAR "website" a little more fancy #107 (comment)). The filenames do not always match the respective version (note the dash in e.g. <release version="4.0.0-RC1" url="https://phars.phpcodesniffer.com/phars/phpcs-4.0.0RC1.phar">) and I didn't want to make any assumptions.
The php script is just something I quickly whipped up. I intentionally did not make it pass PHPStan's analysis because I believe that would make the code less readable.

Personally, I like the look of phars.html but index.html could still use some work. But in the interest of keeping things moving, I thought I should send this PR sooner rather than later.

Suggested changelog entry

n/a

Related issues/external references

Fixes #107

Types of changes

(I'm not sure if this applies for the gh-pages branch.)

Bug fix (non-breaking change which fixes an issue)
[] New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
- This change is only breaking for integrators, not for external standards or end-users.
Documentation improvement

PR checklist

I have checked there is no other PR open for the same change.
I have read the Contribution Guidelines.
I grant the project the right to include and distribute the code under the BSD-3-Clause license (and I have the right to grant these rights).
I have added tests to cover my changes.
I have verified that the code complies with the projects coding standards.
[Required for new sniffs] I have added XML documentation for the sniff.

jrfnl · 2025-07-04T01:36:21Z

@benno5020 Thank you so much for doing this!

I haven't reviewed the code in depth (yet), but looking at the principle, there are a couple of things I'd like to get your opinion on.

The pages are responsive and provide a light and dark mode.

💞

I have linked the sources for the icons in my commit messages.

Thanks for doing that 👍🏻

I have prefixed the template and the php script with an underscore because I believe that will keep them from being served by GitHub Pages. Please verify that this behaves as expected.

I don't believe this assumption is correct. Underscore prefixed pages do not get published when the site is build via the standard Jekyll publishing mechanism, except that is explicitly disabled for this GH Pages site via the .nojekyll file.

I did not want to add any bloat so there is no build tooling at all.

Please note that phars.html displays the git committer date of each file (https://git-scm.com/docs/pretty-formats). I wasn't sure what else to show as filemtime would not be right.

The php script is just something I quickly whipped up. I intentionally did not make it pass PHPStan's analysis because I believe that would make the code less readable.

Well, the PHP script is kind of a build tool 😉

To me, it feels counter-intuitive to have an auto-generated phars.html file committed to the repo, when there is a script available to auto-generate the file.
The risk of the committed file going out of date, because manually running the update is forgotten, feels unnecessary.

Side-note: I wonder whether the phars.html page should in actual fact be the phars/index.html page ?

So... what I'm currently thinking is this:

Re-organize the files in the gh-pages branch like so:
- root
  - CNAME
- .github/workflows
  - publish-website.yml
  - the generate_phars_list.php script and the phars.html.template file (or possibly have the script in a bin directory or both files in a build directory ?)
- src
  - the other pre-existing files, including your updates + the new styles.css file (not the phars.html file!)
Create a publish-website.yml workflow to run the generate_phars_list.php script and create the phars.html (or phars/index.html) file and deploy the website from the src directory on pushes to the branch.
Possibly use the GH API to retrieve the publish date of the relevant release for each PHAR file ? (to get round the modified/committer date issue).
The .nojekyll file would be removed as it would (should) no longer be necessary once the site is switched to a custom deploy script.

How does that sound to you ? Do you see any problems which I'm overlooking ?

Now, I don't know whether you have any experience with creating a custom GH Pages deploy script ?
If not, I'd be happy to whip something up myself. Or, if you prefer, coach you through creating the deploy script.

If we would decide to go down this road, I think the file moves need to be done in a separate commit, probably as the first commit for this PR, to allow for the best chance of git keeping track of the file history correctly.

I did not look into generating phive.xml (as mentioned here: Make the PHAR "website" a little more fancy #107 (comment)). The filenames do not always match the respective version (note the dash in e.g. <release version="4.0.0-RC1" url="https://phars.phpcodesniffer.com/phars/phpcs-4.0.0RC1.phar">) and I didn't want to make any assumptions.

That's totally fair and something which can be left as "future scope" to be added to the publish workflow at a later date.

Personally, I like the look of phars.html but index.html could still use some work. But in the interest of keeping things moving, I thought I should send this PR sooner rather than later.

Iteration is good ;-)

benno5020 · 2025-07-06T13:37:38Z

Hi @jrfnl,
thank you for your feedback!

I just tried it out and you are correct, files prefixed with an underscore are still served.
I agree that generated files should (generally) not be committed, so I'm very much in favour of a workflow.
We could definitely query the GitHub API, but then we'd have to think about the (unlikely) scenario that the API is down during deployment.

I have restructured the files and created a workflow.
You can see it in action here: https://github.com/benno5020/PHP_CodeSniffer/actions/runs/16099172225/job/45426029117 (Note that the linked workflow is not 100% identical to the one in this branch. I have since split up the PHP step.)
The resulting pages can be viewed here: https://benno5020.github.io/PHP_CodeSniffer/

jrfnl

Hi @benno5020 Thank you for your continued work on this!

We could definitely query the GitHub API, but then we'd have to think about the (unlikely) scenario that the API is down during deployment.

True - in that case, maybe we should leave the "date" bit for the next iteration and discuss that separately ?

My thoughts on this at this moment:

We could check the GH API, and if there is no usable response fall back to the original logic ?
Alternatively, we could check the status of the GH API from within the workflow using the https://github.com/crazy-max/ghaction-github-status action runner and fail the workflow run if the GH API has a partial_outage (or higher).
That would prevent deploying the phar site in a broken state and would allow for "Re-running failed build(s)" with just a few clicks once the API outage has resolved.

Side-note: we may want to use that action runner in the workflow either way to check for an outage of GH Pages before deploying...

I have restructured the files and created a workflow. You can see it in action here: https://github.com/benno5020/PHP_CodeSniffer/actions/runs/16099172225/job/45426029117 (Note that the linked workflow is not 100% identical to the one in this branch. I have since split up the PHP step.) The resulting pages can be viewed here: https://benno5020.github.io/PHP_CodeSniffer/

Great work!

I've left some questions and remarks inline.

If you'd like to see an example of a workflow which is using most of what's being discussed, you could have a look at the workflow in use for the schema.phpcodesniffer.com website: https://github.com/PHPCSStandards/schema.phpcodesniffer.com/blob/stable/.github/workflows/update-website.yml

There is one important difference between that website and this one - the schema website does not use the gh-pages branch, but is a repo specifically for that website. Other than that, the principles are very similar.

Feels like we're getting very close now!

jrfnl · 2025-07-07T13:41:22Z

.github/workflows/publish-website.yml

+
+on:
+  push:
+    branches: ["gh-pages"]


Nitpick for readability:

Suggested change

branches: ["gh-pages"]

branches:

- "gh-pages"

I'd like to also suggest to do a "dry-run" on pull requests to the gh-pages branch, i.e. run the script, but don't deploy.

To enable this, the script does need some tweaks. The example script I mention above for the "schema" website has these tweaks already in place.

Alternatively, we could leave this for a future iteration.

I have added a separate build job for pull requests.

jrfnl · 2025-07-07T13:48:22Z

.github/workflows/publish-website.yml

+      - name: Install PHP
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y php


Just curious: why are you installing PHP like this ?

IIRC, all actions images already come with a semi-recent PHP version pre-loaded, so if we don't want any control over the PHP version, we could just use that.
Ref: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md#php-tools

Alternatively, if we'd want more control over the PHP version and PHP ini settings and such, I'd recommend installing PHP using the shivammathur/setup-php action runner.

There was no particular reason. I assumed the image did not come with PHP and did not see a reason not to trust the apt repository or care about the exact php version or settings.

I have changed the code to use shivammathur/setup-php so it's consistent with schema.phpcodesniffer.com's workflow.

jrfnl · 2025-07-07T13:59:49Z

.github/workflows/publish-website.yml

+  cancel-in-progress: false
+
+jobs:
+  deploy:


While I can imagine this would inhibit testing at this time, for GH Pages deployments, I generally recommend having a job-level condition to only run/deploy when the workflow is triggered in the original repo.

This prevents lots of semi-duplicate GH Pages websites sprouting up when people contribute and reduces the risk of the CNAME being hijacked.

# Don't run on forks. if: github.repository == 'PHPCSStandards/PHP_CodeSniffer'

jrfnl · 2025-07-07T14:05:59Z

.gitignore

+vendor
+.phpunit.result.cache
+.idea


Unless I'm missing something, none of these have a risk of existing with the repo as it is at this time, so there is no reason for these to be .gitignored.

Side-note: .idea never belongs in .gitignore, that should always be a user specific global ignored directory.

They existed in my folder when I git switched from the master branch so I thought it wouldn't hurt to ignore them.

Regarding the side-note: Interesting, I hadn't heard of this. There seem to be different schools of thought:
Does not ignore .idea:

Symfony (https://github.com/symfony/symfony/blob/7.4/.gitignore)

Wordpress (https://github.com/WordPress/wordpress-develop/blob/trunk/.gitignore)

Drupal (https://github.com/drupal/drupal/blob/11.x/example.gitignore)

Ignores .idea in some form:

Laravel (https://github.com/laravel/laravel/blob/4ab121576ed4f28dbeba9e58c949552b3913d60a/.gitignore#L9)

phpunit (https://github.com/sebastianbergmann/phpunit/blob/f807247ef9bd4e3604715f4ef2d4df56481886db/.gitignore#L2)

CakePHP (https://github.com/cakephp/app/blob/df3967aa70375b9e19afd5d8b13da65e054f736b/.gitignore#L39)

CodeIgniter (https://github.com/codeigniter4/CodeIgniter4/blob/1f2fdf7f052d331518634539215c7fa5022f4dc0/.gitignore#L101)

composer (https://github.com/composer/composer/blob/0d632ffbf7ee93ce1109d3599b54aa426c0f2d59/.gitignore#L12)

Joomla (https://github.com/joomla/joomla-cms/blob/8868adc4b65bb262961ec9e717459376ff48294a/.gitignore#L6)

phpmyadmin (https://github.com/phpmyadmin/phpmyadmin/blob/26d685fa5811acaee1f3d4d3b2aaa20053e9bc59/.gitignore#L23)

mediawiki (https://github.com/wikimedia/mediawiki/blob/78384e34bc73dcbfcba32e2562b29b78fadfac5e/.gitignore#L83)

TYPO3 (https://github.com/TYPO3/typo3/blob/dcefe2fb688368b6f49d4082d4ce68486f1152be/.gitignore#L20)

Neos (https://github.com/neos/neos-development-collection/blob/eaeed0383ba36386716a7f01b270a8ff2a8caac5/Neos.Neos/.gitignore#L17)

Sorry, this list got out of hand. I tried to find more projects in support of your argument but kept running into projects that do ignore .idea. I don't care as much as this list would indicate ;)

They existed in my folder when I git switched from the master branch so I thought it wouldn't hurt to ignore them.

Okay, for vendor and the PHPUnit cache file I can imagine this, if the branch is checked out in a local fork also used for PHPCS itself, so fair. (I personally always created a separate local fork for gh-pages as switching between orphan branches can really mess things up)

As for the .idea folder: the fact that lots of projects ignore it, doesn't mean that's correct.
Different people use different editors/IDEs and that's a user-preference and unrelated to any specific project. That's why this should be ignored via the user-specific .gitignore_global file, not via a project .gitignore (unless a project forces you to use a specific IDE, but I can hardly imagine any project would do so).

the fact that lots of projects ignore it, doesn't mean that's correct.

Agreed, and I do see your point.

jrfnl · 2025-07-07T14:06:39Z

.gitignore

+vendor
+.phpunit.result.cache
+.idea
+src/phars/index.html


As a rule of thumb, I'd ask you to end every file on a new line character (here and elsewhere).

Do you think it would be a good idea to add this instruction to the codebase somehow? I'm not sure how much tooling you see fit. Personally, I'd add an

# .editorconfig root = true [*] insert_final_newline = true end_of_line = lf

(I do, of course, see that this would not technically enforce the rule.)

And come to think of it, wouldn't a .gitattributes file containing * text=auto eol=lf make sense as well?

.gitattributes 👍🏻

As for an .editorconfig, I have no objections against it, though I also don't see much use for it. Fine if others find it useful.

I have added .gitattributes but did not add an .editorconfig. I agree there's not much use for it if it's not strictly enforced.

jrfnl · 2025-07-07T14:13:56Z

build/generate_phars_list.php

+
+<?php


Suggested change

<?php

#!/usr/bin/env php

<?php

Might also be a good idea to have a minimal file docblock, which at the very least identifies the file as part of PHP_CodeSniffer + annotates the minimum PHP version for this script (as it doesn't have to comply with the same PHP requirements the main package has).

Maybe something along the lines of:

/** * Script to auto-generate the `phar/index.html` page for the GH Pages website. * * {@internal This script has a minimum PHP requirement of PHP ...} * * @copyright 2025 PHPCSStandards and contributors * @license https://github.com/PHPCSStandards/PHP_CodeSniffer/blob/master/licence.txt BSD Licence */

Done. I think the minimum PHP version should be PHP 7 because I used some type hints, but those could be removed if need be.

jrfnl · 2025-07-07T14:21:39Z

src/index.html

+        </div>
+        <aside class="additional-info">
+            <a href="./phars/">
+                See all PHAR files


We may need to think about this phrase a little.

The PHAR website doesn't contain all previously released PHAR files. Only the ones released since PHIVE support was added (and the PHAR files started to be signed).

I've renamed the page "PHAR Archive" and added a footnote.

jrfnl · 2025-07-07T14:23:43Z

src/styles.css

@@ -0,0 +1,200 @@
+@import url(https://fonts.bunny.net/css?family=open-sans:400,800);


Is there a strong reason to use an external font file ?

No, just convenience. I did pick bunny over Google fonts for GDPR reasons but did not want to look into font licenses when I wrote that bit of code.

Appreciate the GDPR consideration. I was more wondering why an external font is used at all, I mean, why not use the OS system fonts ?

Fanciness! Seriously though, it would have felt strange to not set a font when the goal is to achieve a more professional look. But I'm open to your suggestions :)

If you'd like to stick with Open Sans, I believe we could self-host it after downloading WOFF2 files from here: https://gwfh.mranftl.com/fonts/open-sans?subsets=latin
Here's the license: https://github.com/googlefonts/opensans/blob/main/OFL.txt

The download icon is taken from https://github.com/feathericons/feather/blob/main/icons/download.svg (MIT license). The GitHub logo is taken from https://github.com/logos

See https://git-scm.com/docs/pretty-formats

This ensures the pages still work as intended when served from a subdirectory (such as https://username.github.io/PHP_CodeSniffer/).

I think it makes sense to add this to help search engines when they encounter duplicate content in forked repositories.

jrfnl added Status: awaiting feedback Type: documentation Type: enhancement labels Jul 4, 2025

benno5020 force-pushed the gh-pages branch from f5d5d43 to 2659b09 Compare July 6, 2025 13:37

jrfnl removed the Status: awaiting feedback label Jul 7, 2025

jrfnl reviewed Jul 7, 2025

View reviewed changes

jrfnl added the Status: awaiting feedback label Jul 7, 2025

benno5020 added 11 commits July 7, 2025 21:21

gh-pages: restructure files in preparation of deployment via workflow

f542522

gh-pages: make pages fancier

05b61fc

The download icon is taken from https://github.com/feathericons/feather/blob/main/icons/download.svg (MIT license). The GitHub logo is taken from https://github.com/logos

gh-pages: add filesize and committer date

127edf8

See https://git-scm.com/docs/pretty-formats

gh-pages: add deployment workflow

ab0460e

gh-pages: use relative paths for styles and links

2374683

This ensures the pages still work as intended when served from a subdirectory (such as https://username.github.io/PHP_CodeSniffer/).

gh-pages: add canonical tag

28a555f

I think it makes sense to add this to help search engines when they encounter duplicate content in forked repositories.

gh-pages: add newline at end of files

9d0b8d5

gh-pages: add separate workflow job for pull requests

f231977

gh-pages: add .gitattributes

51d7b8d

gh-pages: add shebang and file docblock to build script

0fd05a8

gh-pages: change page title and add footnote

af5b852

benno5020 force-pushed the gh-pages branch from 2659b09 to af5b852 Compare July 7, 2025 19:23

jrfnl removed the Status: awaiting feedback label Jul 14, 2025

-<?php
+#!/usr/bin/env php
+<?php

		@@ -0,0 +1,200 @@
		@import url(https://fonts.bunny.net/css?family=open-sans:400,800);

Uh oh!

Make the PHAR "website" a little more fancy #1156

Are you sure you want to change the base?

Make the PHAR "website" a little more fancy #1156

Uh oh!

Conversation

benno5020 commented Jun 30, 2025

Description

Suggested changelog entry

Related issues/external references

Types of changes

PR checklist

Uh oh!

jrfnl commented Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

benno5020 commented Jul 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jrfnl left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jrfnl Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benno5020 Jul 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jrfnl commented Jul 4, 2025 •

edited

Loading

benno5020 commented Jul 6, 2025 •

edited

Loading

jrfnl left a comment •

edited

Loading

jrfnl Jul 7, 2025 •

edited

Loading

benno5020 Jul 7, 2025 •

edited

Loading