psr12-moodle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PSR-12 Moodle Compliance Skill

PSR-12 Moodle 合规性检查技能

Automatic Activation Triggers

自动激活触发条件

This skill activates automatically when:

Writing or editing PHP files in Moodle plugin directories
User mentions "code standards", "PSR-12", "phpcs", or "coding style"
Discussions about refactoring or code quality
After implementing new Moodle functions or classes

本技能会在以下场景自动激活：

编写或编辑Moodle插件目录下的PHP文件
用户提及“代码规范”、“PSR-12”、“phpcs”或“编码风格”
讨论代码重构或代码质量相关话题
实现新的Moodle函数或类之后

Moodle-Specific PSR-12 Rules

Moodle 特定的 PSR-12 规则

Core Principle

核心原则

Moodle follows PSR-12 with specific exceptions for legacy compatibility.

Moodle 为兼容遗留代码，遵循带有特定例外规则的PSR-12规范。

Naming Conventions (EXCEPTIONS to PSR-12)

命名规范（PSR-12 的例外规则）

Classes

类

php

// ❌ PSR-12 Standard (PascalCase)
class FolderBrowser {}

// ✅ Moodle Standard (lowercase_with_underscores)
class folder_browser {}

php

// ❌ PSR-12 标准（大驼峰命名）
class FolderBrowser {}

// ✅ Moodle 标准（下划线分隔的小写命名）
class folder_browser {}

Functions & Methods

函数与方法

php

// ❌ PSR-12 Standard (camelCase)
public function getUserData() {}

// ✅ Moodle Standard (lowercase_with_underscores)
public function get_user_data() {}

php

// ❌ PSR-12 标准（小驼峰命名）
public function getUserData() {}

// ✅ Moodle 标准（下划线分隔的小写命名）
public function get_user_data() {}

Variables

变量

php

// ❌ PSR-12 Standard (camelCase)
$userData = [];

// ✅ Moodle Standard (lowercase_with_underscores)
$user_data = [];

php

// ❌ PSR-12 标准（小驼峰命名）
$userData = [];

// ✅ Moodle 标准（下划线分隔的小写命名）
$user_data = [];

Frankenstyle Naming (REQUIRED)

Frankenstyle 命名（强制要求）

All functions, classes, and namespaces must include component prefix:

php

// ❌ Missing component prefix
function get_folder_contents() {}
class folder_browser {}

// ✅ With frankenstyle prefix
function mod_nextcloudfolder_get_folder_contents() {}
class mod_nextcloudfolder_folder_browser {}

所有函数、类和命名空间必须包含组件前缀：

php

// ❌ 缺少组件前缀
function get_folder_contents() {}
class folder_browser {}

// ✅ 带有frankenstyle前缀
function mod_nextcloudfolder_get_folder_contents() {}
class mod_nextcloudfolder_folder_browser {}

PSR-12 Rules FOLLOWED by Moodle

Moodle 遵循的 PSR-12 规则

1. Indentation: 4 spaces

1. 缩进：4个空格

php

// ✅ Correct
function example() {
    if ($condition) {
        do_something();
    }
}

php

// ✅ 正确格式
function example() {
    if ($condition) {
        do_something();
    }
}

2. Line Length: 180 characters max (Moodle extends PSR-12's 120)

2. 行长度：最大180字符（Moodle 扩展了PSR-12的120字符限制）

php

// ⚠️ Moodle allows up to 180 characters per line
$result = $DB->get_record_sql('SELECT * FROM {table} WHERE field1 = ? AND field2 = ? AND field3 = ?', [$param1, $param2, $param3]);

php

// ⚠️ Moodle 允许每行最多180字符
$result = $DB->get_record_sql('SELECT * FROM {table} WHERE field1 = ? AND field2 = ? AND field3 = ?', [$param1, $param2, $param3]);

3. Opening Braces: Same line for control structures

3. 大括号位置：控制结构的大括号与语句同行

php

// ✅ Correct
if ($condition) {
    // code
}

// ✅ New line for functions/classes
function my_function()
{
    // code
}

php

// ✅ 正确格式
if ($condition) {
    // 代码
}

// ✅ 函数/类的大括号另起一行
function my_function()
{
    // 代码
}

4. Namespaces

4. 命名空间

php

// ✅ Correct namespace with frankenstyle
namespace mod_nextcloudfolder\local;

class helper {
    // ...
}

php

// ✅ 带有frankenstyle前缀的正确命名空间
namespace mod_nextcloudfolder\local;

class helper {
    // ...
}

5. Use statements

5. use 语句

php

// ✅ One per line, alphabetically sorted
use mod_nextcloudfolder\local\api;
use mod_nextcloudfolder\local\helper;

php

// ✅ 每行一个，按字母顺序排序
use mod_nextcloudfolder\local\api;
use mod_nextcloudfolder\local\helper;

Validation Workflow

验证工作流程

Step 1: Read Current Code

步骤1：读取当前代码

bash

undefined

bash

undefined

Use Read tool to examine PHP file

使用读取工具检查PHP文件

undefined

undefined

Step 2: Identify Violations

步骤2：识别违规问题

Check for:

camelCase naming → lowercase_with_underscores
Missing frankenstyle prefixes
Incorrect indentation (not 4 spaces)
Lines exceeding 180 characters
Missing or incorrect PHPDoc blocks
Improper brace placement

检查以下内容：

小驼峰命名 → 下划线分隔的小写命名
缺少frankenstyle前缀
缩进错误（非4个空格）
行长度超过180字符
缺少或不正确的PHPDoc块
大括号位置不当

Step 3: Run phpcs

步骤3：运行phpcs

bash

undefined

bash

undefined

Moodle code checker

Moodle代码检查器

vendor/bin/phpcs --standard=moodle path/to/plugin/

Or use dev helper if available

若有开发助手工具也可使用

./dev.sh check

undefined

./dev.sh check

undefined

Step 4: Apply Fixes

步骤4：应用修复

Automatic fixes:

bash

vendor/bin/phpcbf --standard=moodle path/to/plugin/

Manual fixes: Use Edit tool for:

Renaming violations
Adding frankenstyle prefixes
Fixing complex structural issues

自动修复：

bash

vendor/bin/phpcbf --standard=moodle path/to/plugin/

手动修复： 使用编辑工具处理以下情况：

重命名违规的标识符
添加frankenstyle前缀
修复复杂的结构问题

Step 5: Verify

步骤5：验证修复结果

bash

undefined

bash

undefined

Rerun phpcs to confirm clean

重新运行phpcs确认无问题

vendor/bin/phpcs --standard=moodle path/to/plugin/

undefined

vendor/bin/phpcs --standard=moodle path/to/plugin/

undefined

Common Violations & Fixes

常见违规问题与修复方案

1. camelCase Function Names

1. 小驼峰函数名

php

// ❌ Before
function getUserFolders($userid) {
    return $DB->get_records('folders', ['userid' => $userid]);
}

// ✅ After
function mod_nextcloudfolder_get_user_folders($userid) {
    return $DB->get_records('nextcloudfolder', ['userid' => $userid]);
}

php

// ❌ 修复前
function getUserFolders($userid) {
    return $DB->get_records('folders', ['userid' => $userid]);
}

// ✅ 修复后
function mod_nextcloudfolder_get_user_folders($userid) {
    return $DB->get_records('nextcloudfolder', ['userid' => $userid]);
}

2. Missing PHPDoc

2. 缺少PHPDoc

php

// ❌ Before
function get_folders() {
    // ...
}

// ✅ After
/**
 * Get all folders for current user.
 *
 * @return array Array of folder objects
 */
function mod_nextcloudfolder_get_folders() {
    // ...
}

php

// ❌ 修复前
function get_folders() {
    // ...
}

// ✅ 修复后
/**
 * 获取当前用户的所有文件夹。
 *
 * @return array 文件夹对象数组
 */
function mod_nextcloudfolder_get_folders() {
    // ...
}

3. Class Naming

3. 类命名

php

// ❌ Before
class FolderApi {
    // ...
}

// ✅ After
namespace mod_nextcloudfolder\local;

/**
 * Folder API helper class.
 *
 * @package    mod_nextcloudfolder
 * @copyright  2024 Your Name
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
class folder_api {
    // ...
}

php

// ❌ 修复前
class FolderApi {
    // ...
}

// ✅ 修复后
namespace mod_nextcloudfolder\local;

/**
 * 文件夹API辅助类。
 *
 * @package    mod_nextcloudfolder
 * @copyright  2024 你的名称
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 或更高版本
 */
class folder_api {
    // ...
}

4. Indentation Issues

4. 缩进问题

php

// ❌ Before (2 spaces or tabs)
function example() {
  if ($condition) {
    do_something();
  }
}

// ✅ After (4 spaces)
function example() {
    if ($condition) {
        do_something();
    }
}

php

// ❌ 修复前（2个空格或制表符）
function example() {
  if ($condition) {
    do_something();
  }
}

// ✅ 修复后（4个空格）
function example() {
    if ($condition) {
        do_something();
    }
}

5. Long Lines

5. 超长行

php

// ❌ Before (>180 chars)
$result = $DB->get_record_sql('SELECT * FROM {table} WHERE field1 = ? AND field2 = ? AND field3 = ? AND field4 = ? AND field5 = ?', [$param1, $param2, $param3, $param4, $param5]);

// ✅ After (split logically)
$sql = 'SELECT * FROM {table}
         WHERE field1 = ? AND field2 = ?
           AND field3 = ? AND field4 = ?
           AND field5 = ?';
$params = [$param1, $param2, $param3, $param4, $param5];
$result = $DB->get_record_sql($sql, $params);

php

// ❌ 修复前（超过180字符）
$result = $DB->get_record_sql('SELECT * FROM {table} WHERE field1 = ? AND field2 = ? AND field3 = ? AND field4 = ? AND field5 = ?', [$param1, $param2, $param3, $param4, $param5]);

// ✅ 修复后（合理拆分）
$sql = 'SELECT * FROM {table}
         WHERE field1 = ? AND field2 = ?
           AND field3 = ? AND field4 = ?
           AND field5 = ?';
$params = [$param1, $param2, $param3, $param4, $param5];
$result = $DB->get_record_sql($sql, $params);

Output Format

输出格式

After validation and fixes:

✅ PSR-12 Moodle Compliance Check

File: mod/nextcloudfolder/lib.php
Status: ✅ PASSED (or ❌ FAILED)

Issues Fixed:
- ✓ Renamed getUserData() → get_user_data()
- ✓ Added frankenstyle prefix to class folder_browser
- ✓ Fixed indentation (27 lines)
- ✓ Added missing PHPDoc blocks (5 functions)
- ✓ Split 3 lines exceeding 180 characters

Remaining Issues: 0

Next: Run `vendor/bin/phpcs --standard=moodle mod/nextcloudfolder/` to verify.

验证与修复完成后，输出如下格式：

✅ PSR-12 Moodle 合规性检查

文件：mod/nextcloudfolder/lib.php
状态：✅ 通过（或 ❌ 失败）

已修复问题：
- ✓ 将getUserData()重命名为get_user_data()
- ✓ 为folder_browser类添加frankenstyle前缀
- ✓ 修复缩进问题（27行）
- ✓ 补充缺失的PHPDoc块（5个函数）
- ✓ 拆分3行超长行

剩余问题：0

下一步：运行 `vendor/bin/phpcs --standard=moodle mod/nextcloudfolder/` 进行验证。

psr12-moodle

Original

Translation

PSR-12 Moodle Compliance Skill

PSR-12 Moodle 合规性检查技能

Automatic Activation Triggers

自动激活触发条件

Moodle-Specific PSR-12 Rules

Moodle 特定的 PSR-12 规则

Core Principle

核心原则

Naming Conventions (EXCEPTIONS to PSR-12)

命名规范（PSR-12 的例外规则）

Classes

类

Functions & Methods

函数与方法

Variables

变量

Frankenstyle Naming (REQUIRED)

Frankenstyle 命名（强制要求）

PSR-12 Rules FOLLOWED by Moodle

Moodle 遵循的 PSR-12 规则

1. Indentation: 4 spaces

1. 缩进：4个空格

2. Line Length: 180 characters max (Moodle extends PSR-12's 120)

2. 行长度：最大180字符（Moodle 扩展了PSR-12的120字符限制）

3. Opening Braces: Same line for control structures

3. 大括号位置：控制结构的大括号与语句同行

4. Namespaces

4. 命名空间

5. Use statements

5. use 语句

Validation Workflow

验证工作流程

Step 1: Read Current Code

步骤1：读取当前代码

Use Read tool to examine PHP file

使用读取工具检查PHP文件

Step 2: Identify Violations

步骤2：识别违规问题

Step 3: Run phpcs

步骤3：运行phpcs

Moodle code checker

Moodle代码检查器

Or use dev helper if available

若有开发助手工具也可使用

Step 4: Apply Fixes

步骤4：应用修复

Step 5: Verify

步骤5：验证修复结果

Rerun phpcs to confirm clean

重新运行phpcs确认无问题

Common Violations & Fixes

常见违规问题与修复方案

1. camelCase Function Names

1. 小驼峰函数名

2. Missing PHPDoc

2. 缺少PHPDoc

3. Class Naming

3. 类命名

4. Indentation Issues

4. 缩进问题

5. Long Lines

5. 超长行

Output Format

输出格式

Integration with Development Workflow

与开发工作流的集成

References

参考资料