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!

.github/workflows/publish-website.yml

.gitignore

build/generate_phars_list.php

src/index.html

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.

* Minor textual adjustments for the homepage. * Remove modified date for the PHAR listing (as it would currently be inaccurate). * Improve code style consistency of build script. * Remove trailing spaces in style.css file.

jrfnl

@benno5020 I'm really sorry it's taken me so long to get back to this. I've now had a final look and have added a small commit with a few minor tweaks.

Functionally, the only real change is the removal of the "modified date" as this would currently not be very informative while it is based on the commit date.

I've opened issue #1167 with the ideas discussed above for further iterative improvements and I've included the "date" issue in that ticket.

Thank you for your work on this and for contributing to PHP_CodeSniffer!

jrfnl · 2025-08-05T13:01:40Z

Deployment succeeded. This is now live at: https://phars.phpcodesniffer.com/

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

jrfnl added this to the 3.13.3 milestone Aug 5, 2025

gh-pages: various minor tweaks

d37c885

* Minor textual adjustments for the homepage. * Remove modified date for the PHAR listing (as it would currently be inaccurate). * Improve code style consistency of build script. * Remove trailing spaces in style.css file.

jrfnl mentioned this pull request Aug 5, 2025

Further iterative improvements for the PHAR website #1167

Open

3 tasks

jrfnl approved these changes Aug 5, 2025

View reviewed changes

jrfnl merged commit 68d302c into PHPCSStandards:gh-pages Aug 5, 2025
3 checks passed

jrfnl mentioned this pull request Aug 5, 2025

Dependabot: attempt to enable for orphan gh-pages branch #1169

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

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

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

Uh oh!

benno5020 commented Jun 30, 2025

Uh oh!

jrfnl commented Jul 4, 2025 •

edited

Loading

Uh oh!

benno5020 commented Jul 6, 2025 •

edited

Loading

Uh oh!

jrfnl left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jrfnl Jul 7, 2025

Uh oh!

benno5020 Jul 7, 2025

Uh oh!

jrfnl Jul 7, 2025

Uh oh!

benno5020 Jul 7, 2025

Uh oh!

jrfnl left a comment

Uh oh!

Uh oh!

jrfnl commented Aug 5, 2025

Uh oh!

Uh oh!

		@@ -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

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jrfnl Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

benno5020 Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

jrfnl Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

benno5020 Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

jrfnl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jrfnl commented Aug 5, 2025

Uh oh!

Uh oh!

jrfnl commented Jul 4, 2025 •

edited

Loading

benno5020 commented Jul 6, 2025 •

edited

Loading

jrfnl left a comment •

edited

Loading