Cursor rule

1---
2description: PHP memory optimisation standards and actionable checks
3globs: *.php, *.ini
4---
5# PHP Memory Optimisation Standards
6 
7Guidance and automated checks to reduce peak memory usage in PHP applications. Based on widely accepted practices and the article "PHP Memory Optimization Tips" by Khouloud Haddad.
8 
9<rule>
10name: php_memory_optimisation
11description: Detect memory-heavy patterns and suggest streaming, generators, and better data handling
12filters:
13  - type: file_extension
14    pattern: "\\.php$"
15 
16actions:
17  - type: enforce
18    conditions:
19      # Avoid loading entire DB result sets into memory.
20      - pattern: "->fetchAll\\("
21        message: "Avoid fetchAll() on large result sets; iterate with fetch() in a loop or wrap with a generator (yield)."
22 
23      - pattern: "\\bmysqli_fetch_all\\("
24        message: "Avoid mysqli_fetch_all() for large queries; prefer streaming fetch (e.g., mysqli_fetch_assoc in a loop)."
25 
26      # Avoid repeated full-file loads inside loops.
27      - pattern: "foreach\\s*\\([^)]*\\)\\s*\\{[^}]*file_get_contents\\("
28        message: "Avoid file_get_contents() inside loops; stream with SplFileObject or read once and reuse."
29 
30      # Avoid array_merge in tight loops as it copies arrays.
31      - pattern: "foreach\\s*\\([^)]*\\)\\s*\\{[^}]*=\\s*array_merge\\("
32        message: "Avoid array_merge() inside loops; append elements directly or preallocate arrays."
33 
34      # Use caution with range() on large ranges (allocates full array).
35      - pattern: "\\brange\\s*\\("
36        message: "range() allocates full arrays; for large ranges consider generators (yield) to avoid high memory."
37 
38  - type: suggest
39    message: |
40      **PHP memory optimisation recommendations:**
41 
42      - **Stream database results:** Prefer `$stmt->fetch(PDO::FETCH_ASSOC)` in a `while` loop or use generators instead of `fetchAll()`.
43      - **Use generators (yield):** Iterate large datasets without allocating full arrays.
44      - **Stream files:** Use `SplFileObject` or chunked reads instead of `file_get_contents()` for large files.
45      - **Minimise array copying:** Avoid `array_merge()` in loops; push items directly or pre-size with known capacity (e.g., `SplFixedArray`).
46      - **Free memory explicitly:** `unset($var)` after large data is no longer needed; consider `gc_collect_cycles()` for long-running scripts.
47      - **Profile memory:** Use `memory_get_usage()` and tools like Xdebug/Blackfire to spot peaks.
48      - **OPcache:** Ensure OPcache is enabled and sized appropriately in production.
49 
50  - type: validate
51    conditions:
52      # Detect full-file reads that likely could be streamed.
53      - pattern: "\\bfile\\s*\\("
54        message: "file() reads entire files into memory; prefer SplFileObject for line-by-line streaming."
55 
56metadata:
57  priority: high
58  version: 1.0
59</rule>
60 
61<rule>
62name: php_ini_opcache_recommendations
63description: Recommend enabling OPcache for lower memory and better performance when editing php.ini
64filters:
65  - type: file_extension
66    pattern: "\\.ini$"
67 
68actions:
69  - type: suggest
70    message: |
71      **OPcache recommendations (php.ini):**
72      - Set `opcache.enable=1` and `opcache.enable_cli=1` for CLI scripts that process large datasets.
73      - Size memory pool appropriately, e.g., `opcache.memory_consumption=128` (adjust to your project).
74      - Consider `opcache.interned_strings_buffer` and `opcache.max_accelerated_files` for larger codebases.
75 
76  - type: enforce
77    conditions:
78      - pattern: "(?mi)^opcache\\.enable\\s*=\\s*0"
79        message: "Enable OPcache in production (set opcache.enable=1) to reduce memory and CPU overhead."
80 
81metadata:
82  priority: medium
83  version: 1.0
84</rule>
85 
86