php-the-right-way: a reference site, not a library

A GitHub Pages repository whose product is a website

The README is short, and its first job is to say what kind of thing this is. This is the GitHub Pages repository for the PHP: The Right Way project, and it describes itself as an easy-to-read, quick reference for PHP best practices, accepted coding standards, and links to authoritative tutorials around the Web. Read carefully, that is a curated index with prose, not a standard and not a framework. The project's own framing of why it exists is a shortage rather than a gap in tooling: there has been a lot of discussion about how the PHP community lacks sufficient, credible information for programmers new to PHP, and this repository aims to solve that problem.

That shapes what you can expect from the tree. There is a `_config.yml` for Jekyll, a `Gemfile` and `Gemfile.lock` for the Ruby side, `_layouts/`, `_includes/`, `_posts/` and `pages/` for content, a `CNAME` file for the custom domain, and `index.html` as the entry point. The default branch is `gh-pages`, which is the branch GitHub Pages serves, so a fork that keeps a different default branch will publish nothing without saying so.

There is also a `LICENSE` file, and the README names the terms as the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. For a repository whose content is prose, that is a coherent choice. It is worth knowing before you copy code samples out of it, since the non-commercial clause travels with the text and a commercial project would not want it in its own documentation.

How the Markdown content becomes the navigation

The content model is described in four bullets and they are the whole build. Each section and sub-section are a Markdown file in `_posts/`, sub-sections carry `isChild: true` in their front matter, and the navigation and page structure are automatically generated from that. There is no hand-maintained table of contents to fall out of sync, which is the sort of detail that separates a documentation site that survives five years from one that does not.

It also means the writing unit is a file, and a new section is a new file rather than an edit to a shared index. For a project whose stated purpose is to be a quick reference, that is a sensible granularity: each page can be read on its own and linked to directly, which is exactly how most readers arrive at the site.

The front matter convention has one consequence that is easy to miss. Because sub-sections are marked rather than nested, depth is a property the build reads from a flag, not from directory nesting. Anyone adding content needs to get that flag right, and the README does not say what happens when it is wrong. That is the kind of detail the contributor documentation would cover.

Twenty-one translations and a rule for publishing them

The translations section is the most distinctive part of the repository, and it is a maintenance model rather than a list. Anyone interested in translating the project is invited to fork the repository and publish a localized fork to their own GitHub Pages account, with the primary document linking to it. Two hosting options are offered to avoid fragmentation and reader confusion: a GitHub Pages fork at `[username].github.io/php-the-right-way`, or a subdomain such as `ru.phptherightway.com`.

The subdomain path has a build requirement, and the README is explicit about it. Enter the subdomain into the `CNAME` file and ask the maintainers to set up DNS. If you are not using a subdomain, remove the `CNAME` file entirely, because otherwise the fork will not build when pushed. That is a fork which appears broken for a reason that lives in one file, and the warning exists because people have hit it.

The finished list covers English, Spanish, French, Indonesian, Italian, Polish, Brazilian Portuguese, Romanian, Slovenian, Serbian, Turkish, Bulgarian, Russian, Ukrainian, Arabic, Persian, Thai, Korean, Japanese, Simplified Chinese and Traditional Chinese. Translations are registered in a wiki page and announced by opening an issue on the issue tracker, so the count of languages on the front page is maintained by hand rather than discovered. The coordination cost is visible too: the README names two collaborators, Kris Jordan and Phil Sturgeon, alongside the author, Josh Lockhart, who is also the author of the Slim Framework.

Contributor rules precise enough to match without asking

The README defers to `CONTRIBUTING.md` for precise instructions and tips, then gives a summary in four steps: fork and edit, optionally install Ruby with the Jekyll gem to preview locally, and submit a pull request for consideration. The preview step being optional tells you the build is not required to make a correct change. `CONTRIBUTING.md` is in the tree and is the file to open first if you plan to contribute.

The contributor style guide is where this repository is unusually precise, and the four rules are worth setting out because they are the kind of thing that otherwise gets argued about in review:

1. Use American English spelling (primary English repo only).
2. Use four (4) spaces to indent text; do not use tabs.
3. Wrap all text to 120 characters.
4. Code samples should adhere to PSR-1 or higher.

The 120 character wrap is interesting on its own. Fixed width wrapping means diffs stay narrow and a changed sentence shows as a two line change rather than a rewrapped paragraph, which is the main practical benefit of a rule that otherwise seems fussy. The PSR-1 floor for code samples is the rule that ties the site's own examples to the PHP-FIG standards, and it is the closest this project comes to a technical position: the samples in the reference should at minimum look like code from a project trying to follow the standards.

A Grunt and LESS toolchain that has not moved in years

Styling for the site is built with Grunt, LESS, PostCSS and Autoprefixer, pinned in `package.json`:

"devDependencies": {
  "grunt": "~0.4.5",
  "grunt-contrib-less": "~1.0.1",
  "grunt-contrib-watch": "~0.6.1",
  "grunt-postcss": "^0.6.0",
  "autoprefixer": "^6.0.3"
}

The `less/` and `styles/` directories are in the tree alongside a `Gruntfile.js` and a `scripts/` directory, so the pipeline is Grunt driving LESS compilation with Autoprefixer filling in vendor prefixes. The versions are the story here. Grunt 0.4.5 and Autoprefixer 6 both come from an era that has since moved on, and the package itself sits at version 2.0.0. For a documentation site whose output is static HTML, an old toolchain is a low-stakes kind of staleness: nothing reaches a browser as a runtime dependency, and the build is not something most contributors will ever run.

It is still worth knowing before you clone and install. A Grunt that old on a current Node release is where a first-time contributor is likely to hit friction, which is presumably why the README frames local preview as optional. There are no releases for this repository to check against, so the version numbers in `package.json` and the date of the last push are the only change signals available.

Editorial conclusion

php-the-right-way is worth reading as a document rather than adopting as a dependency, and the repository is more interesting for what it reveals about the project than for anything you would install. Nothing in it is code you run: the build is a Jekyll site with Grunt and LESS for styling, and the guidance itself is a set of Markdown files in `_posts/` that link out to authoritative sources elsewhere. Two things make it unusual. The translation model is a genuine distributed maintenance structure, with 21 linked translations and a defined convention for publishing a fork, and the contributor rules are precise enough that anyone can match the house style without asking. The last push was on 2026-04-27. The content is versioned through the site rather than through releases, so there is no changelog to read, and the fastest way in is the English site itself, with `CONTRIBUTING.md` as the file to open if you intend to change anything.

Frequently asked questions

Official sources

1. codeguy/php-the-right-way on GitHub
2. Issues
3. Project website
4. README