# Contribution guidelines
## Development environment
### Prerequisites
- PHP 8.1+
- `make` , `awk` , `xargs`
- `entr` to watch for file changes
- `xdg-open` link handler to invoke browser
- `libgd` (`php-gd`, `phpX.Y-gd` ) for downsizing images
- (Optional) `doxygen` to generate documentation
### Official repositories
- Codeberg: < https: // codeberg . org / gravel / sessioncommunities . online >
- Lokinet Gitea (mirror): < https: // lokilocker . com / gravel / sessioncommunities . online >
- GitHub (archive): < https: // github . com / mdPlusPlus / sessioncommunities . online >
- Lokinet Gitea (archive): < https: // lokilocker . com / SomeGuy / sessioncommunities . online >
### Structure
[`fetch-servers.php` ](php/fetch-servers.php ) queries available servers, and [`generate-html.php` ](php/generate-html.php> ) generates static HTML. Static HTML is generated from the [`sites` ](sites ) directory to the [`output` ](output ) directory, which additionally contains static assets. All contents of `sites` are invoked to produce a HTML page unless they are prefixed with a `+` sign.
### Development
Run at least once: `make fetch` to query servers. This takes around 15 seconds thanks to the coroutine implementation.
Run when developing: `make dev` to watch for changes & serve HTML locally in browser.
See [`Makefile` ](Makefile ) for more details.
Recommended:
- Add the [default include paths ](.phpenv ) (`.`, `php` ) to your PHP intellisense.
- Get [EditorConfig ](https://editorconfig.org/#pre-installed ) for your IDE if not pre-installed.
- Symlink the commit hooks provided in [`etc/hooks` ](etc/hooks/ ) to `.git/hooks/<hook>` to run a full test cycle when committing to main.
- Use `doxygen` (or `make docs` ) to generate documentation you can reference when developing.
### Running your own copy
- point your webserver at the [`output` ](output/ ) folder
- edit [`sites/privacy.php` ](sites/privacy.php ) to correspond to your Privacy Policy
- install and enable systemd services from the [`etc/systemd` ](etc/systemd/ ) folder or an equivalent timer for periodic updates
## Code style guidelines
### General
**Indentation**: Tabs (4-wide)
**Filename separator**: Hyphen (`-`)
### PHP
**Identifier casing**: `snake_case` and `CONSTANT_CASE`
**Comments and documentation**: [Doxygen ](https://en.wikipedia.org/wiki/Doxygen )
**Whitespace**:
- The following exceptions apply to PHP expressions embedded within HTML:
- Flow control statements within HTML (`< ?php if ($condition): >`)
shall have zero indentation, akin to C macros or sh heredocs.
- Self-contained PHP `include` and variable shorthand statements
in multi-line HTML child node position shall be followed by an extra line:
```php
< body >
< div >
<?php if ($bowl->has_food()): ?>
<?= $bowl->describe_food() ?>
<?php else: ?>
<?php include 'bowl-empty.php'; ?>
<?php endif; ?>
< / div >
< / body >
```
**Other**:
- Strings shall be surrounded by single quotes `''`
where no variable expansion is taking place
### HTML & CSS
**Identifier casing**: `kebab-case` , legacy `snake_case`
**Comments and documentation**: PHP no-ops instead of HTML comments, if possible
### JavaScript
**Identifier casing**: `camelCase` and `CONSTANT_CASE` , occasional `snake_case` for references to DOM
**Comments and documentation**: [JSDoc ](https://jsdoc.app/ )
