Skip to content

Commit a8e796d

Browse files
JanJakesJanJakes
committed
Add AGENTS.md and CLAUDE.md files
1 parent fdb7e28 commit a8e796d

2 files changed

Lines changed: 162 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
<!--
2+
MAINTENANCE: Update this file when:
3+
- Adding/removing composer scripts
4+
- Changing the directory structure (new modules, major refactors)
5+
- Modifying build/test workflows
6+
- Adding new architectural patterns or conventions
7+
-->
8+
9+
# AGENTS.md
10+
This file provides guidance to AI coding agents when working with code in this repository.
11+
12+
## Project overview
13+
This project implements SQLite database support for MySQL-based projects.
14+
15+
It is a monorepo that includes the following components:
16+
- **MySQL lexer** — A fast MySQL lexer with multi-version support.
17+
- **MySQL parser** — An exhaustive MySQL parser with multi-version support.
18+
- **SQLite driver** — A MySQL emulation layer on top of SQLite with a PDO-compatible API.
19+
- **MySQL proxy** — A MySQL binary protocol implementation to support MySQL-based projects beyond PHP.
20+
- **WordPress plugin** — A plugin that adds SQLite support to WordPress.
21+
- **Test suites** — A set of extensive test suites to cover MySQL syntax and functionality.
22+
23+
The codebase is pure PHP with zero dependencies. It supports PHP 7.2 through 8.5, MySQL syntax from version 5.7 onward, and requires SQLite 3.37.0 or newer (with legacy mode down to 3.27.0).
24+
25+
### New and old driver
26+
At the moment, the project includes two MySQL-on-SQLite driver implementations:
27+
1. A new, AST-based MySQL-on-SQLite driver (`class-wp-pdo-mysql-on-sqlite.php`).
28+
2. A legacy, token-based MySQL-to-SQLite translator (`class-wp-sqlite-translator.php`).
29+
30+
This state is temporary. The new driver will fully replace the legacy one. New features
31+
must always be implemented in the new driver. The legacy driver can receive small fixes.
32+
The new driver is under a `WP_SQLITE_AST_DRIVER` feature flag, but it is widely used.
33+
34+
## Commands
35+
The codebase is written in PHP and Composer is used to manage the project.
36+
The following commands are useful for development and testing:
37+
38+
```bash
39+
composer install # Install dependencies
40+
composer run check-cs # Check coding standards (PHPCS)
41+
composer run fix-cs # Auto-fix coding standards (PHPCBF)
42+
43+
# Tests
44+
composer run test # Run unit tests
45+
composer run test tests/SomeTest.php # Run specific unit test file
46+
composer run test -- --filter testName # Run specific unit test class/method
47+
composer run test-e2e # Run E2E tests (Playwright via WP env)
48+
49+
# WordPress tests
50+
composer run wp-setup # Set up WordPress with SQLite for tests
51+
composer run wp-test-start # Start WordPress environment (Docker)
52+
composer run wp-test-php # Run WordPress PHPUnit tests
53+
composer run wp-test-e2e # Run WordPress E2E tests (Playwright)
54+
composer run wp-test-clean # Clean up WordPress environment (Docker and DB)
55+
```
56+
57+
## Architecture
58+
The project consists of multiple components providing different APIs that funnel
59+
into the SQLite driver to support diverse use cases both inside and outside the
60+
PHP ecosystem.
61+
62+
### Component overview
63+
The following diagram shows how different types of applications can be supported
64+
using components from this project:
65+
66+
```
67+
Consumers: Components:
68+
69+
PHP applications ─────────────────────────┐
70+
Adminer, phpMyAdmin │
71+
│
72+
WordPress + plugins │
73+
WordPress Playground ─────→ wpdb drop-in ─────┼────→ SQLite driver ────→ SQLite
74+
(Studio, wp-env) │ (PDO API) (DB)
75+
│
76+
MySQL CLI │
77+
Desktop clients ─────→ MySQL proxy ──────┘
78+
```
79+
80+
### Query processing pipeline
81+
The following diagram illustrates how a MySQL query is processed and emulated:
82+
83+
```
84+
MySQL query
85+
↓ string
86+
Lexer
87+
↓ tokens
88+
Parser
89+
↓ AST
90+
Translation & Emulation ← INFORMATION_SCHEMA emulation
91+
↓ SQL
92+
SQLite
93+
```
94+
95+
## Principles
96+
This project implements sophisticated emulation and complex APIs. Any changes and
97+
new features must be carefully designed and planned, and their implementation
98+
must fit into the project architecture.
99+
100+
When working on changes to the project:
101+
- **Analyze** the existing code and its architecture.
102+
- **Design** changes in accordance with the existing architecture, if possible.
103+
- **Modify** or extend the architecture with consideration when appropriate.
104+
- **Plan** the implementation carefully so that the changes align with the project.
105+
- **Implement** the changes following the planned design and architecture.
106+
- **Test** all newly added logic using a test suite that is appropriate.
107+
- **Verify** implemented changes. Review their architecture and its suitability.
108+
- **Adjust** the implemented changes if needed to improve the implementation.
109+
- **Simplify** the implemented changes when possible to keep them lean.
110+
111+
Always aim to implement changes and solve problems fully and properly. Don't use
112+
shortcuts and hacks. Never silence errors, linters, or tests to simplify the job.
113+
114+
## Security
115+
Security is critical to this project. The implementation must prevent all vulnerabilities
116+
that could lead to data compromise or corruption. This includes:
117+
- **Quoting and escaping:** Always use correct escaping and quoting that's appropriate
118+
in a given context. Always correctly prevent SQL injection and other vulnerabilities.
119+
- **Encoding:** Be diligent about encodings and the nuances between MySQL and SQLite.
120+
- **Data integrity:** Always preserve data integrity to avoid data loss or corruption.
121+
122+
Always scrutinize implemented logic for security vulnerabilities and verify any
123+
assumptions. Never take shortcuts.
124+
125+
## Compatibility
126+
This project must support a range of PHP and SQLite versions, and it must evolve
127+
the public APIs responsibly, following semantic versioning practices.
128+
129+
In particular:
130+
- **Public APIs:** It's possible to evolve the public API, but this must always be
131+
surfaced to the developer so versioning decisions can be made.
132+
- **PDO API:** The SQLite driver must follow PDO\MySQL API as closely as possible.
133+
- **MySQL binary protocol:** The MySQL proxy must follow the MySQL binary protocol
134+
as closely as possible.
135+
- **PHP version support:** All PHP versions starting from **PHP 7.2** must be supported.
136+
It is possible to use PHP version checks when needed.
137+
- **SQLite version support:** All SQLite versions starting from **SQLite 3.37.0** must be
138+
supported. Older versions (down to 3.27.0) have limited compatibility and require setting
139+
`WP_SQLITE_UNSAFE_ENABLE_UNSUPPORTED_VERSIONS`.
140+
141+
## Coding conventions
142+
Follow these conventions when writing code in this project:
143+
- **Coding style:** Use WordPress Coding Standards via PHPCS (`phpcs.xml.dist`).
144+
- **Function ordering:** First caller, then callee. When function A calls function B, write first A, then B.
145+
- **Method ordering:** First public, then protected, then private. Respect Function ordering as well.
146+
147+
## Git
148+
When creating commits, branches, and pull requests, use clear, concise, and
149+
human-readable prose in plain English.
150+
151+
### Commits
152+
- Make commits readable for humans, not machines.
153+
- Make subject of a commit message short but clear.
154+
- Start with a verb, use present-tense, imperative form.
155+
- Explain details in a commit body below, if needed.
156+
- Include links in the body if the change relates to external sources, issues, PRs, or tickets.
157+
158+
### Pull requests
159+
- When creating a pull request, always follow the repository PR template.
160+
- Pull request title must be brief and accurate.
161+
- Pull request description must be clear, comprehensible, and well organized.

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

0 commit comments

Comments
 (0)