Cursor rule

1---
2description: PHP & Drupal Development Standards and Best Practices
3globs: *.php, *.module, *.theme, *.inc, *.info, *.install
4---
5# Enhanced PHP & Drupal Development Standards
6 
7Defines comprehensive coding standards and best practices for PHP and Drupal development, with a focus on modern PHP features, Drupal 10+ standards, and modularity.
8 
9<rule>
10name: enhanced_php_drupal_best_practices
11description: Enforce PHP 8.3+ features, Drupal 10+ coding standards, and modularity
12filters:
13  - type: file_extension
14    pattern: "\\.(php|module|inc|install|theme)$"
15  - type: file_path
16    pattern: "web/modules/custom/|web/themes/custom/"
17 
18actions:
19  - type: enforce
20    conditions:
21      - pattern: "^(?!declare\\(strict_types=1\\);)"
22        message: "Add 'declare(strict_types=1);' at the beginning of PHP files for type safety."
23 
24      - pattern: "(?<!\\bTRUE\\b)\\btrue\\b|(?<!\\bFALSE\\b)\\bfalse\\b|(?<!\\bNULL\\b)\\bnull\\b"
25        message: "Use uppercase for TRUE, FALSE, and NULL constants."
26 
27      - pattern: "(?i)\\/\\/\\s[a-z]"
28        message: "Ensure inline comments begin with a capital letter and end with a period."
29 
30      - pattern: "class\\s+\\w+\\s*(?!\\{[^}]*readonly\\s+\\$)"
31        message: "Consider using readonly properties where immutability is required."
32 
33      - pattern: "public\\s+function\\s+\\w+\\([^)]*\\)\\s*(?!:)"
34        message: "Add return type declarations for all methods to ensure type safety."
35 
36      - pattern: "extends\\s+\\w+\\s*\\{[^}]*public\\s+function\\s+\\w+\\([^)]*\\)\\s*(?!#\\[Override\\])"
37        message: "Add #[Override] attribute for overridden methods for clarity."
38 
39      - pattern: "\\$\\w+\\s*(?!:)"
40        message: "Use typed properties with proper nullability for better code maintainability."
41 
42      - pattern: "function\\s+hook_\\w+\\([^)]*\\)\\s*(?!:)"
43        message: "Add type hints and return types for all hooks to leverage PHP's type system."
44 
45      - pattern: "new\\s+\\w+\\([^)]*\\)\\s*(?!;\\s*//\\s*@inject)"
46        message: "Use proper dependency injection with services for better testability and modularity."
47 
48      - pattern: "extends\\s+FormBase\\s*\\{[^}]*validate"
49        message: "Implement proper form validation in FormBase classes for security."
50 
51      - pattern: "function\\s+\\w+\\s*\\([^)]*\\)\\s*\\{[^}]*\\$this->t\\("
52        message: "Use Drupal's t() function for strings that need translation."
53 
54      - pattern: "\\$this->config\\('\\w+'\\)"
55        message: "Use ConfigFactory for configuration management."
56      
57      - pattern: "array\\s*\\("
58        message: "Use short array syntax ([]) instead of array() for consistent code style."
59      
60      - pattern: "(?<!\\()\\s+\\(int\\)\\s*\\$"
61        message: "Put a space between the (type) and the $variable in a cast: (int) $mynumber."
62      
63      - pattern: "\\n[\\t ]+\\n"
64        message: "Remove whitespace from empty lines."
65      
66      - pattern: "\\s+$"
67        message: "Remove trailing whitespace at the end of lines."
68      
69      - pattern: "^(?!.*\\n$)"
70        message: "Ensure files end with a single newline character."
71      
72      - pattern: "if\\s*\\([^)]*\\)\\s*\\{[^{]*\\}\\s*else\\s*\\{"
73        message: "Place the opening brace on the same line as the statement for control structures."
74      
75      - pattern: "\\$_GET|\\$_POST|\\$_REQUEST"
76        message: "Never use superglobals directly; use Drupal's input methods."
77      
78      - pattern: "mysql_|mysqli_"
79        message: "Use Drupal's database API instead of direct MySQL functions."
80      
81      - pattern: "\\t+"
82        message: "Use 2 spaces for indentation, not tabs."
83      
84      - pattern: "function\\s+\\w+\\s*\\([^)]*\\)\\s*\\{[^}]*\\becho\\b"
85        message: "Don't use echo; use return values or Drupal's messenger service."
86      
87      - pattern: "(?<!\\/\\*\\*)\\s*\\*\\s+@"
88        message: "Use proper DocBlock formatting for documentation."
89      
90      - pattern: "\\bdie\\b|\\bexit\\b"
91        message: "Don't use die() or exit(); throw exceptions instead."
92      
93      - pattern: "\\$entity->get\\([^)]+\\)->getValue\\(\\)"
94        message: "Use $entity->get('field_name')->value instead of getValue() when possible."
95      
96      - pattern: "\\bvar_dump\\b|\\bprint_r\\b|\\bdump\\b"
97        message: "Don't use debug functions in production code; use Drupal's logger instead."
98      
99      - pattern: "\\bnew\\s+DateTime\\b"
100        message: "Use Drupal's DateTimeInterface and DrupalDateTime instead of PHP's DateTime."
101      
102      - pattern: "\\beval\\b"
103        message: "Never use eval() as it poses security risks."
104      
105      - pattern: "function\\s+\\w+_menu_callback\\("
106        message: "Use controller classes with route definitions instead of hook_menu() callbacks."
107      
108      - pattern: "\\/\\*\\*(?:[^*]|\\*[^/])*?@file(?:[^*]|\\*[^/])*?\\*\\/"
109        message: "All PHP files must include proper @file documentation in the docblock."
110      
111      - pattern: "function\\s+\\w+\\s*\\((?:[^)]|\\([^)]*\\))*\\)\\s*\\{(?:[^}]|\\{[^}]*\\})*\\$_SESSION"
112        message: "Use Drupal's user session handling instead of $_SESSION."
113      
114      - pattern: "function\\s+theme_\\w+\\("
115        message: "Theme functions should be replaced with Twig templates in Drupal 8+."
116      
117      - pattern: "drupal_add_js|drupal_add_css"
118        message: "Use #attached in render arrays instead of drupal_add_js() or drupal_add_css()."
119      
120      - pattern: "function\\s+\\w+_implements_hook_\\w+\\("
121        message: "Use proper hook implementation format: module_name_hook_name()."
122        
123      - pattern: "use\\s+[^;]+,\\s*[^;]+"
124        message: "Specify a single class per use statement. Do not specify multiple classes in a single use statement."
125        
126      - pattern: "use\\s+\\\\[A-Za-z]"
127        message: "When importing a class with 'use', do not include a leading backslash (\\)."
128        
129      - pattern: "\\bnew\\s+\\\\DateTime\\(\\)"
130        message: "Non-namespaced global classes (like Exception) must be fully qualified with a leading backslash (\\) when used in a namespaced file."
131        
132      - pattern: "(?<!namespace )Drupal\\\\(?!\\w+\\\\)"
133        message: "Modules should place classes inside a custom namespace: Drupal\\module_name\\..."
134        
135      - pattern: "class\\s+\\w+\\s*(?:extends|implements)(?:[^{]+)\\{\\s*[^\\s]"
136        message: "Leave an empty line between start of class/interface definition and property/method definition."
137        
138      - pattern: "Drupal\\\\(?!Core|Component)[A-Z]"
139        message: "Module namespaces should be Drupal\\module_name, not Drupal\\ModuleName (camelCase not PascalCase)."
140        
141      - pattern: "\\\\Drupal::request\\(\\)->attributes->set\\('([^_][^']*)',"
142        message: "Request attributes added by modules should be prefixed with underscore (e.g., '_context_value')."
143        
144      - pattern: "\\\\Drupal::request\\(\\)->attributes->get\\('(_(system_path|title|route|route_object|controller|content|account))'\\)"
145        message: "Avoid overwriting reserved Symfony or Drupal core request attributes."
146        
147      - pattern: "(?<!service provider)\\s+class\\s+\\w+Provider(?!Interface)"
148        message: "Classes that provide services should use the 'Provider' suffix (e.g., MyServiceProvider)."
149        
150      - pattern: "\\.services\\.yml[^}]*\\s+class:\\s+[^\\n]+\\s+arguments:"
151        message: "Services should use dependency injection through constructor arguments defined in services.yml."
152 
153  - type: suggest
154    message: |
155      **PHP/Drupal Development Best Practices:**
156      
157      ### General Code Structure
158      - **File Structure:** Each PHP file should have the proper structures: <?php tag, namespace declaration (if applicable), use statements, docblock, and implementation.
159      - **Line Length:** Keep lines under 80 characters whenever possible.
160      - **Indentation:** Use 2 spaces for indentation, never tabs.
161      - **Empty Lines:** Use empty lines to separate logical blocks of code, but avoid multiple empty lines.
162      - **File Endings:** All files must end with a single newline character.
163      
164      ### PHP Language Features
165      - **PHP Version:** Use PHP 8.3+ features where appropriate.
166      - **Strict Types:** Use declare(strict_types=1) at the top of files to enforce type safety.
167      - **Type Hints:** Always use parameter and return type hints.
168      - **Named Arguments:** Use named arguments for clarity in complex function calls.
169      - **Attributes:** Use PHP 8 attributes like #[Override] for better code comprehension.
170      - **Match Expressions:** Prefer match over switch for cleaner conditionals.
171      - **Null Coalescing:** Use ?? and ??= operators where appropriate.
172      
173      ### Drupal-Specific Standards
174      - **Fields API:** Use hasField(), get(), and value() methods when working with entity fields.
175      - **Exception Handling:** Use try/catch for exception handling with proper logging.
176      - **Database Layer:** Use Drupal's database abstraction layer for all queries.
177      - **Schema Updates:** Implement hook_update_N() for schema changes during updates.
178      - **Dependency Injection:** Use services.yml and proper container injection.
179      - **Routing:** Define routes in routing.yml with proper access checks.
180      - **Forms:** Extend FormBase or ConfigFormBase with proper validation and submission handling.
181      - **Entity API:** Follow entity API best practices for loading, creating, and editing entities.
182      - **Plugins:** Use plugin system appropriately with proper annotations.
183      
184      ### Service & Request Standards
185      - **Service Naming:** Use descriptive service names and appropriate naming patterns (Provider suffix for service providers).
186      - **Service Definition:** Define services in the module's *.services.yml file with appropriate tags and arguments.
187      - **Request Attributes:** When adding attributes to the Request object, prefix custom attributes with underscore (e.g., `_context_value`).
188      - **Reserved Attributes:** Avoid overwriting core-reserved request attributes like `_system_path`, `_title`, `_account`, `_route`, `_route_object`, `_controller`, `_content`.
189      - **Service Container:** Use dependency injection rather than the service container directly.
190      - **Factory Services:** Use factory methods for complex service instantiation.
191      
192      ### Namespace Standards
193      - **Module Namespace:** Use Drupal\\module_name\\... for all custom module code.
194      - **PSR-4 Autoloading:** Class in folder module/src/SubFolder should use namespace Drupal\\module_name\\SubFolder.
195      - **Use Statements:** Each class should have its own use statement; don't combine multiple classes in one use.
196      - **No Leading Backslash:** Don't add a leading backslash (\\) in use statements.
197      - **Global Classes:** Global classes (like Exception) must be fully qualified with a leading backslash (\\) when used in a namespaced file.
198      - **Class Aliasing:** Only alias classes to avoid name collisions, using meaningful names like BarBaz and ThingBaz.
199      - **String Class Names:** When specifying a class name in a string, use full name including namespace without leading backslash. Prefer single quotes.
200      - **Class Placement:** A class named Drupal\\module_name\\Foo should be in file module_name/src/Foo.php.
201      
202      ### Security Practices
203      - **Input Validation:** Always validate and sanitize user input.
204      - **Access Checks:** Implement proper access checks for all routes and content.
205      - **CSRF Protection:** Use Form API with proper form tokens for all forms.
206      - **SQL Injection:** Use parameterized queries with placeholders.
207      - **XSS Prevention:** Use Xss::filter() or t() with appropriate placeholders.
208      - **File Security:** Validate uploaded files and restrict access properly.
209      
210      ### Documentation and Comments
211      - **PHPDoc Blocks:** Document all classes, methods, and properties with proper PHPDoc.
212      - **Function Comments:** Describe parameters, return values, and exceptions.
213      - **Inline Comments:** Use meaningful comments for complex logic.
214      - **Comment Format:** Begin comments with a capital letter and end with a period.
215      - **API Documentation:** Follow Drupal's API documentation standards.
216      
217      ### Performance
218      - **Caching:** Implement proper cache tags, contexts, and max-age.
219      - **Database Queries:** Optimize queries with proper indices and JOINs.
220      - **Lazy Loading:** Use lazy loading for expensive operations.
221      - **Batch Processing:** Use batch API for long-running operations.
222      - **Static Caching:** Implement static caching for repeated operations.
223      
224      ### Testing
225      - **Unit Tests:** Write PHPUnit tests for business logic.
226      - **Kernel Tests:** Use kernel tests for integration with Drupal subsystems.
227      - **Functional Tests:** Implement functional tests for user interactions.
228      - **Mocking:** Use proper mocking techniques for dependencies.
229      - **Test Coverage:** Aim for high test coverage of critical functionality.
230      
231      ### API Documentation Examples
232      
233      #### File Documentation
234      
235      **Module Files (.module)**
236```php
237      <?php
238      
239      /**
240       * @file
241       * Provides [module functionality description].
242       */
243```
244      
245      **Install Files (.install)**
246```php
247      <?php
248      
249      /**
250       * @file
251       * Install, update and uninstall functions for the [module name] module.
252       */
253```
254      
255      **Include Files (.inc)**
256```php
257      <?php
258      
259      /**
260       * @file
261       * [Specific functionality] for the [module name] module.
262       */
263```
264      
265      **Class Files (in namespaced directories)**
266```php
267      <?php
268      
269      namespace Drupal\module_name\ClassName;
270      
271      use Drupal\Core\SomeClass;
272      
273      /**
274       * Provides [class functionality description].
275       *
276       * [Extended description if needed]
277       */
278      class ClassName implements InterfaceName {
279```
280      
281      #### Function Documentation
282      
283      **Standard Function**
284```php
285      /**
286       * Returns [what the function returns or does].
287       *
288       * [Additional explanation if needed]
289       *
290       * @param string $param1
291       *   Description of parameter.
292       * @param int $param2
293       *   Description of parameter.
294       *
295       * @return array
296       *   Description of returned data.
297       *
298       * @throws \Exception
299       *   Exception thrown when [condition].
300       *
301       * @see related_function()
302       */
303      function module_function_name($param1, $param2) {
304```
305      
306      **Hook Implementation**
307```php
308      /**
309       * Implements hook_form_alter().
310       */
311      function module_name_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
312```
313      
314      **Update Hook**
315```php
316      /**
317       * Implements hook_update_N().
318       *
319       * [Description of what the update does].
320       */
321      function module_name_update_8001() {
322```
323      
324      #### Class Documentation
325      
326      **Class Properties**
327```php
328      /**
329       * The entity type manager.
330       *
331       * @var \Drupal\Core\Entity\EntityTypeManagerInterface
332       */
333      protected $entityTypeManager;
334```
335      
336      **Method Documentation**
337```php
338      /**
339       * Gets entities of a specific type.
340       *
341       * @param string $entity_type
342       *   The entity type ID.
343       * @param array $conditions
344       *   (optional) An array of conditions to match. Defaults to an empty array.
345       *
346       * @return \Drupal\Core\Entity\EntityInterface[]
347       *   An array of entity objects indexed by their IDs.
348       *
349       * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
350       *   Thrown if the entity type doesn't exist.
351       * @throws \Drupal\Component\Plugin\Exception\InvalidPluginDefinitionException
352       *   Thrown if the storage handler couldn't be loaded.
353       */
354      public function getEntities(string $entity_type, array $conditions = []): array {
355```
356      
357      **Interface Method**
358```php
359      /**
360       * Implements \SomeInterface::methodName().
361       */
362      public function methodName() {
363```
364      
365      #### Namespace Examples
366      
367      **Using Classes From Other Namespaces**
368```php
369      namespace Drupal\mymodule\Tests\Foo;
370      
371      use Drupal\simpletest\WebTestBase;
372      
373      /**
374       * Tests that the foo bars.
375       */
376      class BarTest extends WebTestBase {
377```
378      
379      **Class Aliasing for Name Collisions**
380```php
381      use Foo\Bar\Baz as BarBaz;
382      use Stuff\Thing\Baz as ThingBaz;
383      
384      /**
385       * Tests stuff for the whichever.
386       */
387      function test() {
388        $a = new BarBaz(); // This will be Foo\Bar\Baz
389        $b = new ThingBaz(); // This will be Stuff\Thing\Baz
390      }
391```
392      
393      **Using Global Classes in Namespaced Files**
394```php
395      namespace Drupal\Subsystem;
396      
397      // Bar is a class in the Drupal\Subsystem namespace in another file.
398      // It is already available without any importing.
399      
400      /**
401       * Defines a Foo.
402       */
403      class Foo {
404      
405        /**
406         * Constructs a new Foo object.
407         */
408        public function __construct(Bar $b) {
409          // Global classes must be prefixed with a \ character.
410          $d = new \DateTime();
411        }
412      }
413```
414      
415      #### Service Definition Example
416      
417      **services.yml File**
418```yaml
419      services:
420        mymodule.my_service:
421          class: Drupal\mymodule\MyService
422          arguments: ['@entity_type.manager', '@current_user']
423          tags:
424            - { name: cache.context }
425```
426      
427      **Request Attribute Handling**
428```php
429      // Correctly adding a request attribute (with underscore prefix)
430      \Drupal::request()->attributes->set('_context_value', $myvalue);
431      
432      // Correctly retrieving a request attribute
433      $contextValue = \Drupal::request()->attributes->get('_context_value');
434```
435 
436  - type: validate
437    conditions:
438      - pattern: "web/modules/custom/[^/]+/\\.info\\.yml$"
439        message: "Ensure each custom module has a required .info.yml file."
440 
441      - pattern: "web/modules/custom/[^/]+/\\.module$"
442        message: "Ensure module has .module file if hooks are implemented."
443 
444      - pattern: "web/modules/custom/[^/]+/src/Form/\\w+Form\\.php$"
445        message: "Place form classes in the Form directory for organization."
446 
447      - pattern: "try\\s*\\{[^}]*\\}\\s*catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}"
448        message: "Implement proper exception handling in catch blocks."
449      
450      - pattern: "namespace\\s+Drupal\\\\(?!\\w+\\\\)"
451        message: "Namespace should be Drupal\\ModuleName\\..."
452      
453      - pattern: "class\\s+[^\\s]+\\s+implements\\s+[^\\s]+Interface"
454        message: "Follow PSR-4 for class naming and organization."
455      
456      - pattern: "\\*\\s+@return\\s+[a-z]+\\|null"
457        message: "Use nullable return types (e.g., ?string) instead of type|null in docblocks."
458      
459      - pattern: "function\\s+__construct\\([^)]*\\)\\s*\\{[^}]*parent::"
460        message: "Call parent::__construct() if extending a class with a constructor."
461      
462      - pattern: "function\\s+[gs]et[A-Z]\\w+\\("
463        message: "Use camelCase for method names (e.g., getId instead of get_id)."
464      
465      - pattern: "\\/\\*\\*(?:(?!\\@file).)*?\\*\\/"
466        message: "Add proper @file docblock for PHP files."
467      
468      - pattern: "function\\s+hook_[a-z0-9_]+\\("
469        message: "Replace 'hook_' prefix with your module name in hook implementations."
470      
471      - pattern: "(?<!\\s\\*)\\s+@(?:param|return|throws)\\b"
472        message: "DocBlock tags should be properly aligned with leading asterisks."
473      
474      - pattern: "@param\\s+(?!(?:array|bool|callable|float|int|mixed|object|resource|string|void|null|\\\\)[\\s|])"
475        message: "Use proper data types in @param tags (array, bool, int, string, etc.)."
476      
477      - pattern: "@return\\s+(?!(?:array|bool|callable|float|int|mixed|object|resource|string|void|null|\\\\)[\\s|])"
478        message: "Use proper data types in @return tags (array, bool, int, string, etc.)."
479      
480      - pattern: "\\*\\s*@param[^\\n]*?(?:(?!\\s{3,})[^\\n])*$"
481        message: "Parameter description should be separated by at least 3 spaces from the param type/name."
482      
483      - pattern: "function\\s+theme\\w+\\([^)]*\\)\\s*\\{[^}]*?(?!\\@ingroup\\s+themeable)"
484        message: "Theme functions should include @ingroup themeable in their docblock."
485      
486      - pattern: "\\*\\s*@code(?!\\s+[a-z]+\\s+)"
487        message: "@code blocks should specify the language (e.g., @code php)."
488      
489      - pattern: "namespace\\s+(?!Drupal\\\\)"
490        message: "Namespaces should start with 'Drupal\\'."
491        
492      - pattern: "web/modules/custom/[^/]+/\\.services\\.yml$"
493        message: "Every module using services should have a services.yml file."
494      
495      - pattern: "web/modules/custom/[^/]+/src/[^/]+Provider\\.php$"
496        message: "Service providers should be in the module's root namespace (src/ directory)."
497 
498metadata:
499  priority: critical
500  version: 1.5
501</rule>