AGENTS.md

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