This doc is designed for users who want to develop on the DProofreaders (DP) codebase.
The DP code is almost entirely server-side PHP with a smattering of JS and CSS. It uses a MySQL backend database and requires a web server -- pgdp.net uses Apache but Nginx should work as well. See the installation docs for information on minimum middleware versions.
The code does not use a PHP framework or an ORM. It was developed 20 years ago and has grown very organically over the years. There has been effort in the past decade to standardize things but you'll find many different patterns remain. We have a defined coding style for the codebase and a set of best practices that cover some of our prescribed patterns.
DP code uses git for source control and is housed at GitHub in the DProofreaders/dproofreaders repository -- likely where you got this code to begin with.
We use the "fork, branch, develop, merge" model, where developers are expected to:
- fork the main repository
- create a development branch off master
- develop code on the branch
- generate a merge/pull request when ready to merge
Several CI tests will run when the PR is opened, including things like linting, security checks, phpstan, and more. Most of these can be run locally with:
# run the base set of linting and static analysis checks
make -C SETUP/ciSee also DP Code Development Using git and a similar guide specific to the dproofreaders repo.
The best current development environment is using the DP development VM which comes with a recent release of the DP code, all required middleware, and some sample data. There is a desire to get a true local development environment -- via vagrant or docker -- created but that has not yet been completed.
The code uses Composer to manage PHP dependencies. Some of these dependencies are runtime dependencies, others are just used for development (phpstan, phpunit, etc). To install PHP dependencies (runtime and development) run the following in the repo base:
composer installThe code also uses nodejs for some development only dependencies, such as linting (eslint) and CSS creation (less). Packages are installed with npm that comes with nodejs. In addition to the nodejs download site, Linux users can find packages for recent nodejs versions from nodesource.
To install nodejs dependencies run the following in the repo base:
npm installThe code is loosely organized around the following ideas:
- PHP pages end in
.phpextensions. As site entry points, all.phppages need to includepinc/base.incwhich sets up common infrastructure like database connections, gettext for localization, error handlers, and more. - PHP code that is included in PHP pages end in
.incextensions. - Strings are localized by using gettext. These are wrapped in a
_()function that the localization tooling will extract into.pofiles that volunteer translators will translate. We do not have any official change control over translated strings, just update them as necessary. See the translation best practices.
pinc/- Includes many of the.incfiles -- this is short for Php INClude.pinc/3rdparty/- code that we distribute but (generally) do not modify. See the 3rdparty readme.
scripts/- JS files used for various features.styles/- CSS scripts which include.lesssource files and the rendered.cssfiles. See CSS / style documentation.SETUP/- Non-runtime code, such as site admin docs, development docs, tests, tooling and other miscellanea. The expectation is that this directory will not, and should not be, accessible via the web context on a live site.SETUP/tests/- Tests, mostly automated but some manual. See the tests README.SETUP/upgrade/- Upgrade scripts. Each release gets a new subdir where we collect upgrade scripts for site admins to run when they install a new release. See also UPGRADE.SETUP/ci/- CI scripts that are run as part of Github Actions -- and can be run manually. See.github/workflows/ci.ymlfor the GHA workflows.