1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
---
description: FreshRSS introduction and conventions for AI agents and human contributors
---
# FreshRSS introduction and conventions
FreshRSS is an open-source news aggregator supporting RSS/ATOM/WebSub and also Web scraping.
The market segment is mostly self-hosting, although multiple user accounts are supported.
It is supposed to be installed on a modest server (mostly, but not limited to, Linux) and can be accessed through a Web UI and an API.
It is written in PHP to make it easy to deploy and easy to contribute to.
More information can be found in [README](README.md) and in the [documentation](docs/en/) published at <https://freshrss.github.io/FreshRSS/en/>
## Instruction structure for AI agents and humans
* [`.github/instructions/`](.github/instructions/) contain the instructions that primarily match filename patterns.
* [`.github/skills/`](.github/skills/) contain the skills to achieve higher-level goals, potentially combining multiple instructions.
* **`AGENTS.md`** is the entry point description for AI coding agents and contributors, referencing other documents such as instructions and skills.
* Favour standard conventions over vendor-specific ones.
* To reduce duplication, refer to enforceable configuration files instead of excessive free-text repetitions.
## Code structure
* `app/Controllers/` – Controllers extend `FreshRSS_ActionController`, named as `{name}Controller.php` with class `FreshRSS_{name}_Controller`
* `app/Models/` – Domain models extend `Minz_Model`.
* DAOs may have some database-specific inheritance, e.g.: `*DAO.php` (base or MySQL), `*DAOSQLite.php` (SQLite), `*DAOPGSQL.php` (PostgreSQL)
* `app/views/{controller}/` – View templates are `.phtml` files mixing PHP and HTML
* `app/views/helpers/` – Reusable view elements with `$this->partial('name')`
* `lib/core-extensions/` or `extensions/` – FreshRSS extensions
* `lib/Minz/` – Core framework: routing, sessions, translations, extensions, PDO abstraction
* `lib/lib_rss.php` – Contain `spl_autoload_register` and other global functions
* `p/` – Public Web root. Only the content of this folder should be exposed if possible (`p/` should not be visible in the public URL)
* Only the `p/i/` path should be access controlled. The main entry point is `p/i/index.php`
* `p/api/greader.php` – Primary API for mobile clients
* `p/api/pshb.php` – Receive realtime pushes via WebSub
* `p/themes/` – UI themes
### Configuration data
* Constants: [`constants.php`](constants.php) overridden in `constants.local.php`
* System config: [`config.default.php`](config.default.php) overridden in `data/config.php`
* User config: [`config-user.default.php`](config-user.default.php) overridden in `data/users/{username}/config.php`
> ℹ Access via `FreshRSS_Context::systemConf()` and `FreshRSS_Context::userConf()`
## Database patterns
Three database backends supported: SQLite, PostgreSQL, MySQL/MariaDB.
The SQL differences are implemented through inheritance:
```php
// Base DAO with common queries
class FreshRSS_EntryDAO extends Minz_ModelPdo { }
// Database-specific overrides
class FreshRSS_EntryDAOSQLite extends FreshRSS_EntryDAO { }
class FreshRSS_EntryDAOPGSQL extends FreshRSS_EntryDAO { }
```
A factory pattern selects the correct DAO, e.g.:
```php
FreshRSS_Factory::createEntryDao();
```
**Important**: in database, VARCHAR/TEXT fields are HTML-encoded, except `attributes` fields, which contain JSON, and which sub-strings are not HTML-encoded.
## Main development commands
> ℹ Recommended before committing
```sh
# Runs all tests: PHPUnit, PHPCS, PHPStan, typos
make test-all
# Auto-fix all trivial issues: whitespace, RTL CSS, translations
make fix-all
# See a list of commands:
make help
```
CI/CD is defined in [`.github/workflows/tests.yml`](.github/workflows/tests.yml)
A Dev Container is available under [`.devcontainer/`](.devcontainer/).
## Docker
> ℹ Check [Docker documentation](Docker/README.md).
## CLI Tools
There are scripts in `cli/` for admin tasks, such as:
```sh
./cli/list-users.php
```
> ℹ Check [CLI documentation](cli/README.md).
When possible, it is best to run as Web server user:
```sh
sudo -u www-data cli/actualize-user.php --user alice
```
or at least re-apply the file permissions after CLI operations:
```sh
cli/access-permissions.sh
```
|
