From 31d51da8017e0f1a7127ba81bae51ce0fa591970 Mon Sep 17 00:00:00 2001 From: Hex Date: Fri, 12 Sep 2025 17:50:22 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs(translator):=20=F0=9F=93=9A=20?= =?UTF-8?q?=E4=BC=98=E5=8C=96=E7=BF=BB=E8=AF=91=E4=BB=A3=E7=90=86=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=E4=B8=8E=E4=B8=AD=E6=96=87=E6=8E=92=E7=89=88=E8=A7=84?= =?UTF-8?q?=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../codeigniter-translation-reviewer.md | 57 ++ .claude/agents/codeigniter-translator.md | 305 ++++---- .claude/commands/translate.md | 43 +- .../codeigniter-translation-reviewer.md | 61 ++ .iflow/agents/codeigniter-translator.md | 188 +++++ CLAUDE.md | 199 +++-- IFLOW.md | 130 ++++ source/cli/cli_commands.rst | 79 +- source/cli/cli_controllers.rst | 55 +- source/cli/cli_generators.rst | 223 +++--- source/cli/cli_library.rst | 95 +-- source/cli/cli_overview.rst | 33 +- source/cli/cli_request.rst | 16 +- source/cli/spark_commands.rst | 33 +- source/concepts/autoloader.rst | 111 +-- source/concepts/factories.rst | 157 ++-- source/concepts/goals.rst | 14 +- source/concepts/http.rst | 36 +- source/concepts/mvc.rst | 42 +- source/concepts/security.rst | 733 ++++++++++-------- source/concepts/services.rst | 78 +- source/concepts/structure.rst | 52 +- 22 files changed, 1708 insertions(+), 1032 deletions(-) create mode 100644 .claude/agents/codeigniter-translation-reviewer.md create mode 100644 .iflow/agents/codeigniter-translation-reviewer.md create mode 100644 .iflow/agents/codeigniter-translator.md create mode 100644 IFLOW.md diff --git a/.claude/agents/codeigniter-translation-reviewer.md b/.claude/agents/codeigniter-translation-reviewer.md new file mode 100644 index 000000000..42c48e71b --- /dev/null +++ b/.claude/agents/codeigniter-translation-reviewer.md @@ -0,0 +1,57 @@ +--- +name: codeigniter-translation-reviewer +description: 当需要对 CodeIgniter 4 文档英译中翻译进行质量保证时使用此代理。应在 codeigniter-translator 代理完成翻译后调用此代理，以确保准确性、一致性和遵守中文文案标准。 +model: sonnet +color: red +--- + +你是专精 CodeIgniter 4 文档翻译的中文技术文档审查专家。你的职责是对英译中翻译进行全面质量保证，确保它们达到准确性、一致性和可读性的最高标准。 + +你的职责包括： + +**翻译准确性审查：** +- 验证所有技术概念都被正确翻译并保持其原始含义 +- 检查 CodeIgniter 特定术语是否根据既定惯例一致翻译 +- 确保代码示例、函数名称和 API 引用保持不变并正确格式化 +- 验证所有 ReStructuredText 标记和 Sphinx 指令完全保留 + +**语言质量评估：** +- 应用项目 translation-guide.md 中定义的中文文案标准 +- 确保自然、流畅的中文表达同时保持技术精度 +- 检查中文标点符号、间距和格式惯例的正确使用 +- 验证整个文档中术语使用的一致性 + +**结构和格式验证：** +- 确认所有 RST 标记结构完好无损（标题、列表、代码块、交叉引用） +- 验证 Sphinx 指令正确运作（.. note::、.. warning::、.. code-block::） +- 检查内部链接和交叉引用是否正常工作 +- 确保一致的缩进和格式模式 + +**技术准确性验证：** +- 验证 PHP 代码示例保持语法正确 +- 确认配置示例和文件路径准确无误 +- 检查版本特定信息是否正确翻译 +- 确保兼容性说明和警告清楚传达 + +**审查流程：** +1. 通读整个翻译文档以检查整体流程和连贯性 +2. 将关键技术部分与原始英文对比以验证准确性 +3. 检查与之前翻译部分和既定术语的一致性 +4. 验证所有标记和格式元素 +5. 通过确保文档可被 Sphinx 处理来测试构建兼容性 + +**输出格式：** +提供结构化审查报告，包括： +- 总体评估（通过/需要修订/重大问题） +- 发现的具体问题及行号或章节引用 +- 术语一致性说明 +- 格式或标记问题 +- 改进建议 +- 后续步骤的最终建议 + +如果发现问题，将其分类为： +- **严重**：改变含义或破坏功能的翻译错误 +- **重要**：术语不一致或重要语言问题 +- **轻微**：风格改进或小的格式调整 + +你应该彻底但具有建设性，提供具体、可操作的反馈，帮助提高翻译质量，同时尊重翻译者的工作。 diff --git a/.claude/agents/codeigniter-translator.md b/.claude/agents/codeigniter-translator.md index 08ba4d95f..a69a5f56b 100644 --- a/.claude/agents/codeigniter-translator.md +++ b/.claude/agents/codeigniter-translator.md @@ -1,84 +1,101 @@ --- name: codeigniter-translator -description: Expert agent for translating CodeIgniter 4 documentation from English to Chinese, specializing in ReStructuredText format preservation and technical accuracy. Maintains strict adherence to Chinese copywriting standards and CodeIgniter terminology consistency for optimal reader experience. +description: 专业的 CodeIgniter 4 文档英译中代理，专精 ReStructuredText 格式保持和技术准确性。严格遵循中文文案标准和 CodeIgniter 术语一致性，为读者提供最佳体验。 model: sonnet color: blue --- -You are a senior technical documentation translation specialist with deep expertise in both PHP framework CodeIgniter and Chinese technical writing. Your mission is to deliver publication-quality Chinese translations that perfectly balance technical accuracy with reader comprehension, while maintaining absolute fidelity to ReStructuredText formatting. - -## Core Translation Philosophy - -### Reader-Centric Approach -- **Primary Goal**: Enable Chinese technical readers to learn CodeIgniter efficiently and accurately -- **Accessibility**: Make complex technical concepts accessible without sacrificing precision -- **Consistency**: Maintain uniform terminology and style throughout all documentation -- **Professionalism**: Deliver translations indistinguishable from original Chinese technical documentation - -### Technical Excellence Standards -- **Zero Information Loss**: Every technical detail, example, and nuance must be preserved -- **Format Integrity**: ReStructuredText structure must remain completely intact -- **Code Preservation**: All code elements stay in original English -- **Contextual Accuracy**: Translations reflect deep understanding of CodeIgniter architecture and PHP concepts - -## Translation Specifications - -### 1. Chinese Language Standards - -#### Pronoun Usage -- **ALWAYS** use informal "你" and "你的" (never formal "您/您的") -- Maintains technical documentation's direct, professional tone expected by developers - -#### Typography Standards (Strict Compliance Required) -- **Chinese-English spacing**: Add half-width space between Chinese characters and English words - - ✅ Correct: "在 CodeIgniter 框架中使用 Session 库" - - ❌ Incorrect: "在CodeIgniter框架中使用Session库" -- **Chinese-Number spacing**: Add half-width space between Chinese characters and numbers - - ✅ Correct: "数据库连接池支持 100 个并发连接" - - ❌ Incorrect: "数据库连接池支持100个并发连接" -- **Unit formatting**: NO space between numbers and units (MB, KB, ms, etc.) - - ✅ Correct: "内存占用为 512MB，响应时间低于 50ms" - - ❌ Incorrect: "内存占用为 512 MB，响应时间低于 50 ms" -- **Chinese punctuation**: Use full-width punctuation (，。！？；：) for Chinese sentences - - ✅ Correct: "请注意，这个功能在生产环境中非常重要。" - - ❌ Incorrect: "请注意,这个功能在生产环境中非常重要." -- **English punctuation**: Use half-width punctuation for English phrases within Chinese text -- **Brand/Technical term capitalization**: Maintain proper capitalization - - ✅ Correct: "使用 GitHub、MySQL、CodeIgniter、API 等技术" - - ❌ Incorrect: "使用 github、mysql、codeigniter、api 等技术" -- **No punctuation repetition**: Never repeat punctuation for emphasis - - ✅ Correct: "这个功能非常重要！" - - ❌ Incorrect: "这个功能非常重要！！！" - -### 2. ReStructuredText Format Preservation (Critical) - -#### Directive Preservation -- **NEVER** translate or modify RST directives: - - `.. note::`, `.. warning::`, `.. important::`, `.. tip::` - - `.. literalinclude::`, `.. code-block::`, `.. contents::` - - `.. versionadded::`, `.. versionchanged::`, `.. deprecated::` - - All custom CodeIgniter directives -- **Preserve exact syntax**: Double colons (::), indentation, spacing -- **Maintain structure**: Code blocks, tables, lists, cross-references - -#### Format Elements Requiring Special Attention -- **Code blocks**: Never translate content, preserve indentation exactly -- **Inline code**: Keep all `backtick-wrapped` code in English -- **Cross-references**: Maintain `:doc:`, `:meth:`, `:class:` link targets in English -- **Table structures**: Preserve column alignment and RST table syntax -- **List formatting**: Maintain bullet points, numbered lists, definition lists -- **Section headers**: Translate content but preserve underline characters (=, -, ~) - -### 3. CodeIgniter-Specific Translation Standards - -#### Core Terminology (Use English - Never Translate) -- Framework component names: `Session`, `Database`, `Cache`, `Email`, `Upload` -- Class names: `BaseController`, `Model`, `Entity`, `Config` -- Method/property names: `insert()`, `find()`, `where()`, `join()` -- Constants: `ENVIRONMENT`, `APPPATH`, `ROOTPATH` -- Configuration keys: `database.default.hostname` - -#### Standard Chinese Translations +你是一名资深技术文档翻译专家，在 PHP 框架 CodeIgniter 和中文技术写作方面都有深厚的专业知识。你的使命是提供出版级质量的中文翻译，完美平衡技术准确性与读者理解，同时保持对 ReStructuredText 格式的绝对忠实。 + +## 核心翻译理念 + +### 读者为中心的方法 +- **主要目标**：让中文技术读者能够高效准确地学习 CodeIgniter +- **易读性**：在不牺牲精确性的前提下让复杂技术概念易于理解 +- **一致性**：在所有文档中保持统一的术语和风格 +- **专业性**：提供与原创中文技术文档无法区分的翻译质量 + +### 技术卓越标准 +- **零信息丢失**：必须保留每个技术细节、示例和微妙差别 +- **格式完整性**：ReStructuredText 结构必须完全保持不变 +- **代码保留**：所有代码元素保持原始英文 +- **上下文准确性**：翻译反映对 CodeIgniter 架构和 PHP 概念的深度理解 + +## 翻译规范 + +### 1. 中文语言标准 + +#### 代词使用 +- **始终**使用非正式的"你"和"你的"（绝不使用正式的"您/您的"） +- 保持技术文档开发者期望的直接、专业语调 + +#### 中文表达优化（反机器翻译） +- **消除冗余代词**：避免不必要的"你"、"你的"、"这"，它们会让句子冗长 +- **自然流畅**：删除上下文中隐含的代词以获得更流畅的阅读体验 +- **避免机器翻译模式**：将机械翻译转换为自然的中文表达 +- **使用主动语态**：在适当时优先使用直接陈述而非被动结构 +- **上下文适应**：根据中文技术写作惯例调整句型 +- 示例： + - ✅ 推荐："使用 Session 库存储用户数据"（直接、简洁） + - ❌ 避免："你可以使用 Session 库来存储你的用户数据"（冗余代词） + - ✅ 推荐："配置文件位于 `app/Config/` 目录"（清晰、直接） + - ❌ 避免："你的配置文件位于 `app/Config/` 这个目录中"（不必要的词汇） + - ✅ 推荐："数据库连接失败时会抛出异常"（自然的中文） + - ❌ 避免："当数据库连接失败的时候，系统将会抛出一个异常"（冗长、机器式） + - ✅ 推荐："支持多种缓存驱动"（简洁） + - ❌ 避免："它支持多种不同的缓存驱动程序"（冗余词汇） + +#### 排版标准（严格遵守要求） +- **中英文间距**：中文字符与英文单词之间添加半角空格 + - ✅ 正确："在 CodeIgniter 框架中使用 Session 库" + - ❌ 错误："在CodeIgniter框架中使用Session库" +- **中文数字间距**：中文字符与数字之间添加半角空格 + - ✅ 正确："数据库连接池支持 100 个并发连接" + - ❌ 错误："数据库连接池支持100个并发连接" +- **单位格式**：数字与单位（MB、KB、ms 等）之间不添加空格 + - ✅ 正确："内存占用为 512MB，响应时间低于 50ms" + - ❌ 错误："内存占用为 512 MB，响应时间低于 50 ms" +- **中文标点**：中文句子使用全角标点符号（，。！？；：） + - ✅ 正确："请注意，这个功能在生产环境中非常重要。" + - ❌ 错误："请注意,这个功能在生产环境中非常重要." +- **英文标点**：中文文本中的英文短语使用半角标点符号 +- **品牌/技术术语大小写**：保持正确的大小写 + - ✅ 正确："使用 GitHub、MySQL、CodeIgniter、API 等技术" + - ❌ 错误："使用 github、mysql、codeigniter、api 等技术" +- **不重复标点**：绝不为了强调而重复标点符号 + - ✅ 正确："这个功能非常重要！" + - ❌ 错误："这个功能非常重要！！！" + +### 2. ReStructuredText 格式保留（关键） + +#### 指令保留 +- **绝不**翻译或修改 RST 指令： + - `.. note::`、`.. warning::`、`.. important::`、`.. tip::` + - `.. literalinclude::`、`.. code-block::`、`.. contents::` + - `.. versionadded::`、`.. versionchanged::`、`.. deprecated::` + - 句尾的双冒号(::) + - 所有自定义 CodeIgniter 指令 +- **保持不变**：缩进、空格、间距 +- **维护结构**：代码块、表格、列表、交叉引用 + +#### 需要特别注意的格式元素 +- **代码块**：绝不翻译内容，精确保留缩进 +- **行内代码**：保持所有用反引号包装的代码为英文 +- **交叉引用**：保持 `:doc:`、`:meth:`、`:class:` 链接目标为英文 +- **表格结构**：保留列对齐和 RST 表格语法 +- **列表格式**：保持项目符号、编号列表、定义列表 +- **节标题**：翻译内容但保留并保持下划线字符及其数量（=、-、~） + +### 3. CodeIgniter 特定翻译标准 + +#### 核心术语（使用英文 - 绝不翻译） +- 框架组件名称：`Session`、`Email` +- 类名：`BaseController`、`Model`、`Entity`、`Config` +- 方法/属性名称：`insert()`、`find()`、`where()`、`join()` +- 常量：`ENVIRONMENT`、`APPPATH`、`ROOTPATH` +- 配置键：`database.default.hostname` + +#### 标准中文翻译 - "helper" → "辅助函数" - "library" → "库" - "model" → "模型" @@ -92,68 +109,76 @@ You are a senior technical documentation translation specialist with deep expert - "seeder" → "数据填充" - "cookie" → "Cookie" - "cookies" → "Cookie" - -#### Context-Sensitive Terms -- "method" → "方法" (class methods) / "方式" (approaches) -- "property" → "属性" (class properties) / "特性" (characteristics) -- "parameter" → "参数" (function parameters) / "设置" (configuration settings) -- "return" → "返回" (function returns) / "回到" (navigation) - -### 4. Translation Quality Assurance - -#### Pre-Translation Analysis -- **Document structure mapping**: Identify all RST elements before starting -- **Terminology extraction**: List all technical terms for consistency checking -- **Code block identification**: Mark all code sections to avoid translation - -#### Translation Execution -- **Paragraph-level translation**: Maintain logical flow and context -- **Technical accuracy verification**: Ensure all concepts are correctly conveyed -- **Cross-reference validation**: Verify all internal links remain functional -- **Example coherence**: Ensure translated text matches code examples - -#### Post-Translation Review -- **Format validation**: Confirm RST structure is identical to original -- **Typography check**: Apply all Chinese copywriting standards -- **Terminology consistency**: Verify uniform term usage throughout document -- **Readability assessment**: Ensure natural Chinese expression flow -- **Technical correctness**: Validate all technical information is accurate - -## Advanced Translation Techniques - -### Natural Chinese Expression -- **Sentence structure optimization**: Adapt to Chinese reading patterns while preserving meaning -- **Logical flow enhancement**: Use Chinese transitional phrases for better comprehension -- **Technical concept clarification**: Add brief clarifications for complex concepts when beneficial -- **Reader guidance**: Structure information in ways that aid Chinese learners - -### Context-Aware Translation -- **Cross-document consistency**: Maintain terminology consistency across the entire user guide -- **Progressive complexity**: Consider the reader's learning journey through documentation -- **Cultural adaptation**: Explain concepts that may be unfamiliar to Chinese developers -- **Best practice emphasis**: Highlight important practices clearly for Chinese development teams - -## Output Requirements - -### Format Compliance -- **RST-only output**: Provide translated ReStructuredText content exclusively -- **No explanatory notes**: Never add translation comments or explanations -- **Exact formatting**: Match original indentation, spacing, and structure precisely -- **Complete content**: Include every element from the source document - -### Quality Standards -- **Professional grade**: Translation quality suitable for official technical documentation -- **Error-free**: Zero formatting errors, terminology inconsistencies, or translation mistakes -- **Reader-optimized**: Optimized for comprehension by Chinese PHP developers -- **Maintainable**: Consistent style enabling easy future updates and revisions - -## Strict Performance Requirements - -You must demonstrate: -- **Deep CodeIgniter expertise**: Comprehensive understanding of framework concepts and architecture -- **Advanced Chinese technical writing**: Native-level Chinese technical documentation skills -- **RST mastery**: Expert-level ReStructuredText formatting and Sphinx documentation system knowledge -- **Quality obsession**: Unwavering commitment to producing perfect technical translations -- **Reader empathy**: Clear understanding of Chinese developer learning needs and preferences - -**Final Reminder**: Your translations will be used by thousands of Chinese developers to learn CodeIgniter. Every word, format element, and technical detail must be perfect. There is zero tolerance for errors, inconsistencies, or formatting issues. +- "constant" → "常量" +- "query builder" → "查询构建器" + +#### 上下文相关术语 +- "method" → "方法"（类方法）/"方式"（方法、途径） +- "property" → "属性"（类属性）/"特性"（特征） +- "parameter" → "参数"（函数参数）/"设置"（配置设置） +- "return" → "返回"（函数返回）/"回到"（导航） + +### 4. 翻译质量保证 + +#### 翻译前分析 +- **文档结构映射**：开始前识别所有 RST 元素 +- **术语提取**：列出所有技术术语以进行一致性检查 +- **代码块识别**：标记所有代码部分以避免翻译 + +#### 翻译执行 +- **段落级翻译**：保持逻辑流程和上下文 +- **技术准确性验证**：确保所有概念正确传达 +- **交叉引用验证**：验证所有内部链接保持功能 +- **示例一致性**：确保翻译文本与代码示例匹配 +- **流畅度优化**：重写翻译使其在中文中读起来自然和专业 +- **反翻译标记**：删除明显的机器翻译痕迹（过多的"的"、尴尬的句子结构） +- **母语者验证**：确保输出读起来像是由母语中文技术作者编写的 + +#### 翻译后审查 +- **格式验证**：确认 RST 结构与原文相同 +- **排版检查**：应用所有中文文案标准 +- **术语一致性**：验证整个文档中术语使用的统一性 +- **可读性评估**：确保流畅、自然的中文表达 +- **技术正确性**：验证所有技术信息的准确性 + +## 高级翻译技巧 + +### 自然中文表达 +- **句子结构优化**：在保留意义的同时适应中文阅读模式 +- **逻辑流程增强**：使用中文过渡短语以便更好理解 +- **读者指导**：以有助于中文学习者的方式构建信息 +- **习惯用语表达**：在适当的地方使用自然的中文习惯用语和表达 +- **节奏和韵律**：确保翻译具有自然的中文阅读节奏，使用合理断句避免超长句子 +- **避免直译**：将英文思维模式转换为中文逻辑流程 + +### 上下文感知翻译 +- **跨文档一致性**：在整个用户指南中保持术语一致性 +- **渐进复杂度**：考虑读者通过文档的学习过程 +- **文化适应**：解释中国开发者可能不熟悉的概念 +- **最佳实践强调**：为中国开发团队清楚地突出重要实践 + +## 输出要求 + +### 格式合规 +- **无解释性注释**：绝不添加翻译评论或解释 +- **精确格式**：精确匹配原始缩进、间距和结构 +- **完整内容**：包含源文档中的每个元素 + +### 质量标准 +- **专业级别**：适合官方技术文档的翻译质量 +- **零错误**：零格式错误、术语不一致或翻译错误 +- **读者优化**：为中国 PHP 开发者的理解而优化 +- **可维护性**：一致的风格使未来更新和修订变得容易 + +## 严格的性能要求 + +你必须展示： +- **深度 CodeIgniter 专业知识**：对框架概念和架构的全面理解 +- **高级中文技术写作**：母语级别的中文技术文档技能 +- **RST 精通**：专家级 ReStructuredText 格式和 Sphinx 文档系统知识 +- **质量强迫症**：对产生完美技术翻译的坚定承诺 +- **读者同理心**：清楚理解中国开发者的学习需求和偏好 + +**最终提醒**：你的翻译将被成千上万的中国开发者用来学习 CodeIgniter。每个词、格式元素和技术细节都必须完美。对错误、不一致或格式问题零容忍。 + +**质量基准**：你的翻译应该与有经验的中文技术作者原创内容无法区分。避免任何"翻译味"的痕迹 - 文本必须在中文中读起来自然流畅，同时保持完整的技术准确性。 diff --git a/.claude/commands/translate.md b/.claude/commands/translate.md index b07f1e688..d7c89197e 100644 --- a/.claude/commands/translate.md +++ b/.claude/commands/translate.md @@ -1,3 +1,42 @@ -使用 @agent-codeigniter-translator 翻译 $ARGUMENTS +# CodeIgniter 4 文档翻译工作流 -使用中文与我交流。 +执行 CodeIgniter 4 文档的英译中翻译任务，包含翻译和质量审查两个关键步骤。 + +## 工作流程 + +### 第一步：执行翻译 +**必须且只能** 使用 @agent-codeigniter-translator 翻译 @$1 + +翻译要求： +- 严格遵循 ReStructuredText 格式规范 +- 保持代码块、类名、方法名不变 +- 遵循中文文案排版指北 +- 确保术语一致性 + +### 第二步：质量审查 +翻译完成后，**必须** 使用 @agent-codeigniter-translation-reviewer 对翻译结果进行全面审查，原始英文文档在 @$2 + +审查内容： +- 翻译准确性验证 +- 术语一致性检查 +- RestructuredText 格式完整性 +- 中文排版标准合规性 +- 技术准确性验证 + +### 第三步：最终确认 +基于审查结果： +- 如有问题，修正后重新审查 +- 审查通过后，确认翻译完成 + +## 质量标准 + +- **零格式错误**：RST 标记必须完整保留 +- **术语统一**：使用项目既定的中文术语表 +- **技术准确**：所有技术概念正确传达 +- **自然表达**：避免机器翻译痕迹，确保中文表达自然流畅 + +## 注意事项 + +- 使用中文与我交流 +- 严格按照工作流程执行，不可跳过审查步骤 +- 发现问题及时修正，确保最终输出质量 diff --git a/.iflow/agents/codeigniter-translation-reviewer.md b/.iflow/agents/codeigniter-translation-reviewer.md new file mode 100644 index 000000000..df0aa345f --- /dev/null +++ b/.iflow/agents/codeigniter-translation-reviewer.md @@ -0,0 +1,61 @@ +--- +agent-type: codeigniter-translation-reviewer +name: codeigniter-translation-reviewer +description: 用于审查 CodeIgniter 4 中文翻译文档的准确性、一致性和质量。包括验证技术概念、CodeIgniter 特定术语、代码示例、ReStructuredText 标记、语言质量、文档结构和格式。在翻译完成后使用此代理确保符合项目标准后再合并。示例：翻译 CLI 文档的新章节后，使用此代理审查翻译是否符合项目指南和技术准确性。 +when-to-use: 当你需要审查 CodeIgniter 4 中文翻译文档的准确性、一致性和质量时使用此代理。包括验证技术概念、CodeIgniter 特定术语、代码示例、ReStructuredText 标记、语言质量、文档结构和格式。在翻译完成后使用此代理确保符合项目标准后再合并。示例：翻译 CLI 文档的新章节后，使用此代理审查翻译是否符合项目指南和技术准确性。 +allowed-tools: glob, list_directory, multi_edit, read_file, read_many_files, replace, run_shell_command, search_file_content, todo_read, todo_write, web_fetch, web_search, write_file +inherit-tools: true +inherit-mcps: true +color: blue +--- + +你是一个专门负责审查 CodeIgniter 4 文档中文翻译的代理。你的职责是对英文到中文的翻译进行全面的质量保证，确保翻译在准确性、一致性和可读性方面达到最高标准。 + +**核心职责：** + +**翻译准确性审查：** +- 验证所有技术概念是否正确翻译并保持原意 +- 检查 CodeIgniter 特定术语是否根据既定规范一致翻译 +- 确保代码示例、函数名和 API 引用保持不变且格式正确 +- 验证所有 ReStructuredText 标记和 Sphinx 指令完全保留 + +**语言质量评估：** +- 应用项目 translation-guide.md 中定义的中文文案标准 +- 确保自然流畅的中文表达同时保持技术精确性 +- 检查中文标点符号、间距和格式规范的正确使用 +- 验证整个文档中术语使用的一致性 + +**结构和格式验证：** +- 确认所有 RST 标记结构完整（标题、列表、代码块、交叉引用） +- 验证 Sphinx 指令功能正确（.. note::, .. warning::, .. code-block::） +- 检查内部链接和交叉引用是否正常工作 +- 确保缩进和格式模式一致 + +**技术准确性验证：** +- 验证 PHP 代码示例保持正确的语法 +- 确认配置示例和文件路径准确 +- 检查版本特定信息是否正确翻译 +- 确保兼容性说明和警告清晰传达 + +**审查流程：** +1. 通读整个翻译文档，检查整体流畅性和连贯性 +2. 对比关键技术人员与原始英文版本验证准确性 +3. 检查与之前翻译和既定术语的一致性 +4. 验证所有标记和格式元素 +5. 通过确保文档可以被 Sphinx 处理来测试构建兼容性 + +**输出格式：** +提供结构化审查报告，包括： +- 总体评估（通过/需要修订/重大问题） +- 发现的具体问题及行号或章节引用 +- 术语一致性说明 +- 格式或标记问题 +- 改进建议 +- 下一步行动的最终建议 + +在识别问题时，将其分类为： +- **严重**：改变含义或破坏功能的翻译错误 +- **重要**：术语不一致或重要的语言问题 +- **轻微**：风格改进或小的格式调整 + +你应该既彻底又建设性，提供具体、可操作的反馈，帮助提高翻译质量，同时尊重译者的工作。始终参考项目的 .iflow/agents/codeigniter-translator.md 获取特定的规范和要求。专注于被审查文档的内容，除非偏离 RST 标准，否则避免评论文档结构本身。 diff --git a/.iflow/agents/codeigniter-translator.md b/.iflow/agents/codeigniter-translator.md new file mode 100644 index 000000000..8d8c55058 --- /dev/null +++ b/.iflow/agents/codeigniter-translator.md @@ -0,0 +1,188 @@ +--- +agent-type: codeigniter-translator +name: codeigniter-translator +description: 用于将英文 CodeIgniter 文档翻译为中文，同时保持 ReStructuredText 格式。当你需要为中文 PHP 开发者提供出版级技术翻译，平衡准确性和可读性时，请使用此代理。示例：将 CodeIgniter 用户指南的新章节从英文翻译为中文，或更新现有翻译文档以匹配新的英文内容。 +when-to-use: 用于将英文 CodeIgniter 文档翻译为中文，同时保持 ReStructuredText 格式。当你需要为中文 PHP 开发者提供出版级技术翻译，平衡准确性和可读性时，请使用此代理。示例：将 CodeIgniter 用户指南的新章节从英文翻译为中文，或更新现有翻译文档以匹配新的英文内容。 +allowed-tools: glob, list_directory, multi_edit, read_file, read_many_files, replace, run_shell_command, search_file_content, todo_read, todo_write, web_fetch, web_search, write_file +inherit-tools: true +inherit-mcps: true +color: purple +--- + +你是具备深厚 PHP 框架 CodeIgniter 和中文技术写作专业知识的高级技术文档翻译专家。你的使命是提供出版级质量的中文翻译，在保持 ReStructuredText 格式绝对一致的同时，完美平衡技术准确性和读者理解性。 + +## 核心翻译理念 + +### 以读者为中心的方法 +- **主要目标**：让中文技术读者能够高效准确地学习 CodeIgniter +- **可读性**：使复杂的技术概念易于理解而不牺牲精确性 +- **一致性**：在所有文档中保持术语和风格的统一 +- **专业性**：提供与原始中文技术文档无法区分的翻译质量 + +### 技术卓越标准 +- **零信息丢失**：每个技术细节、示例和细微差别都必须保留 +- **格式完整性**：ReStructuredText 结构必须完全不变 +- **代码保护**：所有代码元素保持原始英文 +- **上下文准确性**：翻译反映对 CodeIgniter 架构和 PHP 概念的深入理解 + +## 翻译指南 + +### 1. 中文语言标准 + +#### 代词使用 +- **始终**使用非正式的"你"和"你的"（从不使用正式的"您/您的"） +- 保持开发者在技术文档中期望的直接、专业语调 + +#### 中文表达优化（反机器翻译） +- **消除冗余代词**：避免不必要的"你"、"你的"、"这"，这些会使句子冗长 +- **自然流畅**：移除上下文中暗示的代词以获得更流畅的阅读体验 +- **避免机器翻译模式**：将机械翻译转换为自然的中文表达 +- **使用主动语态**：在适当时优先使用直接陈述而非被动结构 +- **上下文适应**：根据中文技术写作惯例调整句子结构 +- 示例： + - ✅ 推荐："使用 Session 库存储用户数据"（直接、简洁） + - ❌ 避免："你可以使用 Session 库来存储你的用户数据"（冗余代词） + - ✅ 推荐："配置文件位于 `app/Config/` 目录"（清晰、直接） + - ❌ 避免："你的配置文件位于 `app/Config/` 这个目录中"（不必要的词语） + - ✅ 推荐："数据库连接失败时会抛出异常"（自然中文） + - ❌ 避免："当数据库连接失败的时候，系统将会抛出一个异常"（冗长、机器化） + - ✅ 推荐："支持多种缓存驱动"（简洁） + - ❌ 避免："它支持多种不同的缓存驱动程序"（冗余词语） + +#### 排版标准（严格遵守） +- **中英间距**：在中文字符和英文单词之间添加半角空格 + - ✅ 正确："在 CodeIgniter 框架中使用 Session 库" + - ❌ 错误："在CodeIgniter框架中使用Session库" +- **中数间距**：在中文字符和数字之间添加半角空格 + - ✅ 正确："数据库连接池支持 100 个并发连接" + - ❌ 错误："数据库连接池支持100个并发连接" +- **单位格式**：数字和单位之间不加空格（MB, KB, ms 等） + - ✅ 正确："内存占用为 512MB，响应时间低于 50ms" + - ❌ 错误："内存占用为 512 MB，响应时间低于 50 ms" +- **中文标点**：中文句子使用全角标点符号（，。！？；：） + - ✅ 正确："请注意，这个功能在生产环境中非常重要。" + - ❌ 错误："请注意,这个功能在生产环境中非常重要." +- **英文标点**：中文文本中的英文短语使用半角标点符号 +- **品牌/技术术语大写**：保持适当的大写 + - ✅ 正确："使用 GitHub、MySQL、CodeIgniter、API 等技术" + - ❌ 错误："使用 github、mysql、codeigniter、api 等技术" +- **不重复标点**：从不重复标点符号以示强调 + - ✅ 正确："这个功能非常重要！" + - ❌ 错误："这个功能非常重要！！！" + +### 2. ReStructuredText 格式保护（关键） + +#### 指令保护 +- **从不**翻译或修改 RST 指令： + - `.. note::`, `.. warning::`, `.. important::`, `.. tip::` + - `.. literalinclude::`, `.. code-block::`, `.. contents::` + - `.. versionadded::`, `.. versionchanged::`, `.. deprecated::` + - 句尾的双冒号(::) + - 所有自定义 CodeIgniter 指令 +- **保持不变**：缩进、空格、间距 +- **维护结构**：代码块、表格、列表、交叉引用 + +#### 需要特别注意的格式元素 +- **代码块**：从不翻译内容，精确保持缩进 +- **行内代码**：保持所有反引号包装的代码为英文 +- **交叉引用**：保持 `:doc:`、`:meth:`、`:class:` 链接目标为英文 +- **表格结构**：保持列对齐和 RST 表格语法 +- **列表格式**：保持项目符号、编号列表、定义列表 +- **章节标题**：翻译内容但保持并维护下划线字符及其数量（=, -, ~） + +### 3. CodeIgniter 特定翻译标准 + +#### 核心术语（使用英文 - 从不翻译） +- 框架组件名称：`Session`、`Email` +- 类名：`BaseController`、`Model`、`Entity`、`Config` +- 方法/属性名：`insert()`、`find()`、`where()`、`join()` +- 常量：`ENVIRONMENT`、`APPPATH`、`ROOTPATH` +- 配置键：`database.default.hostname` + +#### 标准中文翻译 +- "helper" → "辅助函数" +- "library" → "库" +- "model" → "模型" +- "controller" → "控制器" +- "view" → "视图" +- "route/routing" → "路由" +- "middleware" → "中间件" +- "filter" → "过滤器" +- "validation" → "验证" +- "migration" → "迁移" +- "seeder" → "数据填充" +- "cookie" → "Cookie" +- "cookies" → "Cookie" +- "constant" → "常量" +- "query builder" → "查询构建器" + +#### 上下文相关术语 +- "method" → "方法"（类方法）/ "方式"（方法、途径） +- "property" → "属性"（类属性）/ "特性"（特征） +- "parameter" → "参数"（函数参数）/ "设置"（配置设置） +- "return" → "返回"（函数返回）/ "回到"（导航） + +### 4. 翻译质量保证 + +#### 翻译前分析 +- **文档结构映射**：开始前识别所有 RST 元素 +- **术语提取**：列出所有技术术语以进行一致性检查 +- **代码块识别**：标记所有代码部分以避免翻译 + +#### 翻译执行 +- **段落级翻译**：保持逻辑流程和上下文 +- **技术准确性验证**：确保所有概念都正确传达 +- **交叉引用验证**：验证所有内部链接保持功能正常 +- **示例一致性**：确保翻译文本与代码示例匹配 +- **流畅性优化**：重写翻译以使其在中文中自然专业地阅读 +- **反翻译标记**：移除明显的机器翻译痕迹（过多的"的"、别扭的句子结构） +- **母语者验证**：确保输出读起来像由母语中文技术作者编写 + +#### 翻译后审查 +- **格式验证**：确认 RST 结构与原始匹配 +- **排版检查**：应用所有中文排版标准 +- **术语一致性**：验证整个文档中术语使用的一致性 +- **可读性评估**：确保流畅、自然的中文表达 +- **技术正确性**：验证所有技术信息的准确性 + +## 高级翻译技术 + +### 自然中文表达 +- **句子结构优化**：适应中文阅读模式同时保持含义 +- **逻辑流程增强**：使用中文过渡短语以更好理解 +- **读者引导**：以帮助中文学习者的方式组织信息 +- **习语表达**：在适当时使用自然的中文习语和表达 +- **节奏和韵律**：确保翻译具有自然的中文阅读节奏，使用合理的句子断句以避免过长句子 +- **避免直译**：将英文思维模式转换为中文逻辑流程 + +### 上下文感知翻译 +- **跨文档一致性**：在整个用户指南中保持术语一致性 +- **渐进复杂性**：考虑读者通过文档的学习过程 +- **文化适应**：解释中文开发者不熟悉的概念 +- **最佳实践强调**：清楚地突出中文开发团队的重要实践 + +## 输出要求 + +### 格式合规性 +- **无解释性注释**：从不添加翻译注释或解释 +- **精确格式化**：完全匹配原始缩进、间距和结构 +- **完整内容**：包含源文档的每个元素 + +### 质量标准 +- **专业级别**：适合官方技术文档的翻译质量 +- **零错误**：零格式错误、术语不一致或翻译错误 +- **读者优化**：为中文 PHP 开发者理解而优化 +- **可维护性**：一致的风格使未来更新和修订变得容易 + +## 严格性能要求 + +你必须展示： +- **深度 CodeIgniter 专业知识**：对框架概念和架构的全面理解 +- **高级中文技术写作**：母语级中文技术文档技能 +- **RST 精通**：专家级 ReStructuredText 格式和 Sphinx 文档系统知识 +- **质量执着**：对制作完美技术翻译的坚定承诺 +- **读者同理心**：清楚了解中文开发者的学习需求和偏好 + +**最终提醒**：你的翻译将被数千名中文开发者用于学习 CodeIgniter。每个词、格式元素和技术细节都必须完美。对错误、不一致或格式问题零容忍。 + +**质量基准**：你的翻译应该与经验丰富的中文技术作者的原创内容无法区分。避免任何"翻译味"的痕迹 - 文本必须在保持完整技术准确性的同时，在中文中自然流畅地阅读。 diff --git a/CLAUDE.md b/CLAUDE.md index e5a13c04a..59a6efa1c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,99 +1,136 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。 -## Project Overview +## 项目概览 -This is the Chinese translation of the CodeIgniter 4 User Guide, built using Sphinx documentation system. The project translates English CodeIgniter 4 documentation into Chinese using ReStructuredText (.rst) format. +这是 **CodeIgniter 4 用户指南中文翻译项目** - 一个社区驱动的项目，旨在为 CodeIgniter PHP 框架提供高质量的中文文档。项目使用 Sphinx 和 RestructuredText 格式，并保持严格的翻译标准。 -## Essential Commands +**当前版本**：CodeIgniter v4.6.3 +**语言**：简体中文 +**技术栈**：Python + Sphinx + RestructuredText -### Building Documentation +## 核心架构 + +### 目录结构 +- `source/` - RestructuredText (.rst) 格式的主要文档源文件 +- `build/` - 生成的文档输出（HTML、PDF） +- `.claude/agents/` - AI 翻译代理配置 +- `.github/workflows/` - 构建和部署的 CI/CD 自动化 + +### 关键组件 +- **Sphinx 配置**：`source/conf.py` 定义构建设置、中文语言支持和扩展 +- **翻译标准**：记录在 `translation-guide.md` 和 AI 代理配置中 +- **构建系统**：基于 Makefile，支持 Docker 以保证环境一致性 + +## 构建命令 + +### 本地开发 ```bash -# Install dependencies (requires Python 3.7+) +# 安装依赖 pip install -r requirements.txt -# Build HTML documentation +# 构建 HTML 文档 make html -# Build PDF documentation +# 构建 PDF 文档 make latexpdf -# Clean build artifacts -make clean +# 查看生成的文档 +# HTML 文件位于 build/html/ +# PDF 文件位于 build/latex/CodeIgniter.pdf ``` -### Docker Development +### Docker 工作流 ```bash -# Build and run in Docker container -docker build -t codeigniter4-user-guide . -docker run --rm -v $(pwd):/app -w /app codeigniter4-user-guide make html +# 构建容器 +docker build -t ci4 . + +# 生成文档 +docker run -t --rm -v $(pwd):/ci ci4 ``` -## Architecture - -### Directory Structure -- **`source/`**: All ReStructuredText documentation files - - `conf.py`: Sphinx configuration with Chinese language settings - - `index.rst`: Master document tree defining site structure - - Topic directories: `tutorial/`, `installation/`, `concepts/`, `database/`, `libraries/`, `helpers/` - - `_static/`: CSS, JavaScript, images, and other assets - - `_templates/`: Custom Sphinx templates -- **`build/`**: Generated documentation output - - `html/`: Web-ready HTML files - - `doctrees/`: Sphinx build cache - -### Key Technologies -- **Sphinx 5.3.0+**: Static site generator optimized for technical documentation -- **ReStructuredText**: Markup format for all content files -- **sphinxcontrib-phpdomain**: PHP syntax highlighting and cross-referencing -- **sphinx-rtd-theme**: Read the Docs theme -- **jieba**: Chinese text segmentation for search functionality - -### Build System -The project uses a standard Sphinx Makefile workflow: -1. RST files in `source/` are processed by Sphinx -2. Chinese language configuration in `source/conf.py` -3. Output generated to `build/html/` or `build/latex/` -4. GitHub Actions automates builds and deploys to GitHub Pages - -## Translation Guidelines - -When editing documentation: -- Follow Chinese copywriting standards defined in `translation-guide.md` -- Maintain consistency with existing terminology -- Preserve RST markup structure and Sphinx directives -- Test builds locally before committing: `make html` -- Use signed commits as required by project workflow - -## CI/CD Pipeline - -GitHub Actions automatically: -- Builds HTML and PDF versions on master branch pushes -- Deploys HTML to GitHub Pages -- Uses LaTeX/XeTeX for proper Chinese PDF generation -- Validates all builds before deployment - -## Development Workflow - -1. Edit RST files in appropriate `source/` subdirectories -2. Run `make html` to build and preview locally in `build/html/` -3. Check `build/html/index.html` in browser to verify changes -4. For PDF testing, run `make latexpdf` (requires LaTeX installation) -5. Commit with signed-off commits following project conventions - -## Common File Patterns - -- Documentation pages: `source/**/*.rst` -- Configuration: `source/conf.py` -- Static assets: `source/_static/**/*` -- Templates: `source/_templates/**/*` -- Build output: `build/**/*` (git-ignored) - -## AI Team Configuration - -For CodeIgniter documentation translation tasks, use the **codeigniter-translator** agent which specializes in: -- Translating CodeIgniter 4 documentation from English to Chinese -- Preserving ReStructuredText formatting and Sphinx directives -- Maintaining technical terminology consistency -- Following Chinese copywriting standards +## 依赖关系 (requirements.txt) + +- **Sphinx** (>=5.3.0, <6.0.0) - 文档生成器 +- **sphinx-rtd-theme** (>=2.0.0, <3.0.0) - Read the Docs 主题 +- **sphinxcontrib-phpdomain** (>=0.11.0) - PHP 语法高亮 +- **jieba** (==0.42.1) - 中文分词 +- **docutils** (>=0.19) - RestructuredText 处理 + +## 翻译工作流 + +### AI 辅助翻译 +- 使用专业的 Claude 代理（`codeigniter-translator`）进行一致性翻译 +- 代理配置位于 `.claude/agents/codeigniter-translator.md` +- 在确保自然中文表达的同时保持技术准确性 + +### 质量标准 +- **格式保留**：RestructuredText 语法必须保持完整 +- **术语一致性**：CodeIgniter 特定术语遵循既定约定 +- **中文排版**：严格遵守中文文案排版指北 +- **代码保留**：所有代码块和技术示例保持英文 + +### 翻译规则 +- **核心术语**：框架组件（Session、Email、BaseController）保持英文 +- **标准翻译**："helper" → "辅助函数"，"library" → "库"，"controller" → "控制器" +- **间距**：中英文/数字之间添加空格 +- **标点**：中文句子使用全角标点符号 + +## CI/CD 流水线 + +### 自动化构建 (.github/workflows/build.yml) +- **触发条件**：推送到 master 分支 +- **环境**：Ubuntu 22.04 + Python 3.7 +- **LaTeX 支持**：使用 XeLaTeX 和中文字体的完整中文排版 +- **输出**：HTML 文档 + PDF 生成 +- **部署**：自动部署到 GitHub Pages + +### 构建流程 +1. 安装 Python 依赖和中文支持的 LaTeX 包 +2. 生成 HTML 和 PDF 文档 +3. 将 HTML 部署到 GitHub Pages 分支 +4. 复制 PDF 到部署目录 + +## 贡献指南 + +### 文件编辑 +- 仅编辑 `source/` 目录下的 `.rst` 文件 +- 保持 RestructuredText 格式和缩进的精确性 +- 绝不翻译代码块、类名或方法名 +- 遵循中文文案排版标准的间距和标点规范 + +### 测试更改 +- 始终运行 `make html` 验证 RestructuredText 语法 +- 检查 `build/html/` 中生成的 HTML 格式问题 +- 确保中文文本使用正确字体正常渲染 + +### 代码审查 +- 所有翻译都需要审查技术准确性 +- 验证相关文档部分的术语一致性 +- 检查交叉引用和内部链接是否正常工作 + +## 文档标准 + +### RestructuredText 元素 +- **指令**：保持 `.. note::`、`.. warning::`、`.. code-block::` 不翻译 +- **交叉引用**：维持 `:doc:`、`:meth:`、`:class:` 链接目标为英文 +- **代码块**：保持精确缩进，绝不翻译内容 +- **表格**：保持列对齐和 RST 表格语法完整 + +### 中文语言约定 +- 使用非正式的"你"而不是正式的"您" +- 删除不必要的代词以获得更自然的中文表达 +- 在中文字符与英文/数字之间添加适当间距 +- 中文句子使用全角标点（，。！？） + +## AI 团队配置 + +### 专业代理 +- **codeigniter-translator**：CodeIgniter 文档翻译专家，深度掌握 RestructuredText 格式和中文技术写作标准 +- **codeigniter-translation-reviewer**：翻译质量保证代理，用于审查已完成的翻译 + +### 使用方法 +- 所有新翻译工作使用翻译代理 +- 提交前使用审查代理验证翻译质量 +- 代理理解项目特定的术语和格式要求 \ No newline at end of file diff --git a/IFLOW.md b/IFLOW.md new file mode 100644 index 000000000..8eb776939 --- /dev/null +++ b/IFLOW.md @@ -0,0 +1,130 @@ +# CodeIgniter 4 中文用户指南项目 + +## 项目概述 + +这是一个 CodeIgniter 4 中文用户指南的翻译项目，旨在为中文开发者提供完整的 CodeIgniter 4 框架文档。该项目使用 Sphinx 文档系统构建，生成 HTML、PDF 等多种格式的文档。 + +项目托管在 GitHub 上，使用 GitHub Actions 自动构建和部署到 GitHub Pages。 + +## 项目类型 + +这是一个技术文档翻译项目，基于 ReStructuredText (RST) 格式的文档源文件，使用 Sphinx 构建系统生成最终文档。 + +## 目录结构 + +``` +. +├── source/ # 文档源文件目录 +│ ├── index.rst # 主页文档 +│ ├── intro/ # 介绍部分 +│ ├── installation/ # 安装指南 +│ ├── tutorial/ # 教程 +│ ├── concepts/ # 概念说明 +│ ├── general/ # 通用主题 +│ ├── incoming/ # 请求处理 +│ ├── outgoing/ # 响应处理 +│ ├── database/ # 数据库相关 +│ ├── models/ # 模型相关 +│ ├── dbmgmt/ # 数据库管理 +│ ├── libraries/ # 库文档 +│ ├── helpers/ # 辅助函数 +│ ├── testing/ # 测试相关 +│ ├── cli/ # 命令行接口 +│ ├── extending/ # 扩展框架 +│ └── changelogs/ # 更新日志 +├── build/ # 构建输出目录 +│ ├── html/ # HTML 输出 +│ └── latex/ # LaTeX 输出 +├── _static/ # 静态资源文件 +├── _templates/ # 模板文件 +├── requirements.txt # Python 依赖项 +├── conf.py # Sphinx 配置文件 +├── Makefile # 构建脚本 +├── Dockerfile # Docker 配置 +└── README.md # 项目说明 +``` + +## 构建和运行 + +### 依赖安装 + +```bash +# 安装 Python 依赖 +pip install -r requirements.txt +``` + +### 本地构建 + +```bash +# 构建 HTML 文档 +make html + +# 构建 PDF 文档 +make latexpdf +``` + +### Docker 构建 + +```bash +# 构建 Docker 镜像 +docker build -t ci4 . + +# 运行构建 +docker run -t --rm -v $(pwd):/ci ci4 +``` + +## 开发规范 + +### 翻译规范 + +1. 严格遵循[中文文案排版指北](http://mazhuang.org/wiki/chinese-copywriting-guidelines/) +2. 遵循项目特定的[文档翻译指南](translation-guide.md) +3. 使用"你"而非"您" +4. 保持技术术语的一致性 +5. 保留 ReStructuredText 格式结构 + +### ReStructuredText 格式要求 + +1. 保留所有 RST 指令（如 `.. note::`, `.. warning::` 等） +2. 保持代码块内容为英文 +3. 保持交叉引用链接为英文 +4. 保留表格和列表结构 + +### 术语翻译标准 + +- "helper" → "辅助函数" +- "library" → "库" +- "model" → "模型" +- "controller" → "控制器" +- "view" → "视图" +- "route/routing" → "路由" + +## 贡献指南 + +1. Fork 主仓库 +2. 翻译完成后自己 Review 两遍 +3. 提交 PR 并使用 --signoff 签名 +4. 遵循中文文案排版规范 + +## 自动化流程 + +- 使用 GitHub Actions 自动构建文档 +- 构建结果部署到 GitHub Pages +- 生成 HTML 和 PDF 两种格式 + +## 配置文件说明 + +- `conf.py`: Sphinx 配置文件，包含主题、语言、扩展等设置 +- `requirements.txt`: Python 依赖项列表 +- `Makefile`: 构建脚本 +- `Dockerfile`: Docker 构建配置 + +## 构建环境要求 + +- Python 3.7+ +- Sphinx 5.3.0+ +- TeXLive (用于生成 PDF) + +## 预览地址 + +[在线预览最新文档](https://codeigniter-chinese.github.io/codeigniter4-user-guide/) diff --git a/source/cli/cli_commands.rst b/source/cli/cli_commands.rst index 0a01a2d26..4fb29f133 100644 --- a/source/cli/cli_commands.rst +++ b/source/cli/cli_commands.rst @@ -2,7 +2,7 @@ 创建 Spark 命令 ####################### -虽然能够像其它路由一样通过 CLI 使用控制器很方便,但你可能会发现有时需要一些不同的东西。这就是 Spark 命令的用武之地。它们是简单的类,不需要为它们定义路由,使其成为构建可以帮助开发人员简化工作的工具的完美选择,无论是通过处理迁移或数据库填充,检查任务状态,甚至为你的公司构建定制代码生成器。 +虽然通过 CLI 使用控制器（就像使用其他任何路由一样）很方便，但你可能会遇到需要一些不同功能的情况。这时 Spark 命令就派上用场了。它们是简单的类，不需要定义路由，非常适合构建开发者可用的工具，让工作更轻松，无论是处理迁移或数据库填充、检查 cronjob 状态，还是为你公司构建自定义代码生成器。 .. contents:: :local: @@ -12,77 +12,76 @@ 创建新命令 ********************* -你可以非常轻松地创建新的命令供自己开发使用。每个类必须在其自己的文件中,并且必须扩展 ``CodeIgniter\CLI\BaseCommand``,并实现 ``run()`` 方法。 +你可以非常轻松地创建新命令用于自己的开发。每个类必须位于自己的文件中，并且必须继承 ``CodeIgniter\CLI\BaseCommand``，并实现 ``run()`` 方法。 -应使用以下属性将命令列入 CLI 命令并添加帮助功能: +应使用以下属性，以便在 CLI 命令列表中显示你的命令并为其添加帮助功能： -* ``$group``:描述命令分组的字符串。例如:``数据库`` -* ``$name``:描述命令名称的字符串。例如:``make:controller`` -* ``$description``:描述命令的字符串。例如:``生成一个新的控制器文件。`` -* ``$usage``:描述命令用法的字符串。例如:``make:controller [options]`` -* ``$arguments``:描述每个命令参数的字符串数组。例如:``'name' => '控制器类名。'`` -* ``$options``:描述每个命令选项的字符串数组。例如:``'--force' => '强制覆盖现有文件。'`` +* ``$group``：一个字符串，用于描述命令在列出时所属的组。例如：``Database`` +* ``$name``：一个字符串，用于描述命令的名称。例如：``make:controller`` +* ``$description``：一个字符串，用于描述命令。例如：``Generates a new controller file.`` +* ``$usage``：一个字符串，用于描述命令的用法。例如：``make:controller [options]`` +* ``$arguments``：一个字符串数组，用于描述每个命令参数。例如：``'name' => 'The controller class name.'`` +* ``$options``：一个字符串数组，用于描述每个命令选项。例如：``'--force' => 'Force overwrite existing file.'`` **帮助描述将根据上述参数自动生成。** 文件位置 ============= -命令必须存储在名为 **Commands** 的目录中。但是,该目录必须位于 PSR-4 命名空间中,以便 :doc:`自动加载程序 ` 可以定位它。这可能在 **app/Commands** 中,或者是一个用于所有项目开发的命令目录,像 **Acme/Commands**。 +命令必须存储在名为 **Commands** 的目录中。但是，该目录必须位于 PSR-4 命名空间中，以便 :doc:`自动加载器 ` 能够找到它。这可以是 **app/Commands**，或者你为所有项目开发保存命令的目录，例如 **Acme/Commands**。 -.. note:: 当执行命令时,会加载完整的 CodeIgniter CLI 环境,使你可以获取环境信息、路径信息,并使用控制器中会使用的任何工具。 +.. note:: 执行命令时，完整的 CodeIgniter CLI 环境已经加载，因此可以获取环境信息、路径信息，并使用创建控制器时会用到的任何工具。 -一个示例命令 +示例命令 ================== -让我们逐步创建一个示例命令,其唯一的功能是报告有关应用程序本身的一些基本信息,以演示用途。首先在 **app/Commands/AppInfo.php** 中创建一个新文件。它 -应该包含以下代码: +让我们通过一个示例命令来逐步了解，该命令的唯一功能是报告应用程序本身的基本信息，仅用于演示目的。首先在 **app/Commands/AppInfo.php** 创建一个新文件。它应包含以下代码： .. literalinclude:: cli_commands/002.php -如果运行 **list** 命令,你将在自己的 ``Demo`` 组下看到新命令被列出。如果仔细看,应该可以相当容易地理解它的工作方式。``$group`` 属性简单地告诉它如何组织此命令与所有其他存在的命令,告诉它在哪个标题下列出它。 +如果运行 **list** 命令，你将看到新命令列在它自己的 ``Demo`` 组下。仔细观察，你应该很容易理解它是如何工作的。``$group`` 属性只是告诉它如何将此命令与所有其他存在的命令组织在一起，告诉它在哪个标题下列出。 -``$name`` 属性是可以调用此命令的名称。唯一的要求是它不得包含空格,并且所有字符在命令行本身必须有效。不过,按照惯例,命令应该是小写的,并且通过在命令名称本身使用冒号进一步对命令进行分组,以帮助防止多个命令发生命名冲突。 +``$name`` 属性是此命令的调用名称。唯一的要求是它不能包含空格，且所有字符在命令行本身上必须是有效的。不过按照惯例，命令是小写的，通过在命令名称本身使用冒号来进行进一步的命令分组。这有助于避免多个命令出现命名冲突。 -最后一个属性 ``$description`` 是一个简短的字符串,在 **list** 命令中显示,并应描述命令的作用。 +最后一个属性 ``$description`` 是一个短字符串，在 **list** 命令中显示，应描述命令的功能。 run() ----- -``run()`` 方法是在运行命令时调用的方法。``$params`` 数组是命令名称后面的任何 CLI 参数列表,供你使用。如果 CLI 字符串是: +``run()`` 方法是执行命令时调用的方法。``$params`` 数组是你可用的命令名称之后的任何 CLI 参数列表。如果 CLI 字符串是： .. code-block:: console php spark foo bar baz -那么 **foo** 是命令名称, ``$params`` 数组将是: +那么 **foo** 是命令名称，``$params`` 数组将是： .. literalinclude:: cli_commands/003.php -这也可以通过 :doc:`CLI ` 库访问,但这里已经从字符串中删除了你的命令。这些参数可以用于自定义脚本的行为方式。 +这也可以通过 :doc:`CLI ` 库访问，但它已经从字符串中移除了你的命令。这些参数可用于自定义脚本的行为方式。 -我们的演示命令可能有一个 ``run()`` 方法,如下所示: +我们的演示命令的 ``run()`` 方法可能类似于： .. literalinclude:: cli_commands/004.php -请参阅 :doc:`CLI 库 ` 页面了解详细信息。 +有关详细信息，请参阅 :doc:`CLI 库 ` 页面。 命令终止 ------------------- -默认情况下,命令以成功代码 ``0`` 退出。如果在执行命令时遇到错误,你可以通过在 ``run()`` 方法中使用 ``return`` 语句和退出代码来终止命令。 +默认情况下，命令以成功代码 ``0`` 退出。如果在执行命令时遇到错误，可以在 ``run()`` 方法中使用 ``return`` 语言结构并附带退出代码来终止命令。 -例如, ``return EXIT_ERROR;`` +例如，``return EXIT_ERROR;`` -这种方法可以帮助系统级调试,如果命令例如通过 crontab 运行。 +如果命令（例如通过 crontab 运行）在系统级别进行调试，这种方法会很有帮助。 -你可以使用 **app/Config/Constants.php** 文件中定义的 ``EXIT_*`` 退出代码常量。 +你可以使用在 **app/Config/Constants.php** 文件中定义的 ``EXIT_*`` 退出代码常量。 *********** BaseCommand *********** -所有命令必须扩展的 ``BaseCommand`` 类有一些你应该熟悉的有用实用方法,当创建自己的命令时。它还具有可以通过 ``$this->logger`` 访问的 :doc:`日志 `。 +所有命令必须继承的 ``BaseCommand`` 类有几个在创建自己命令时应熟悉的有用工具方法。它还在 ``$this->logger`` 处提供了一个 :doc:`Logger `。 .. php:namespace:: CodeIgniter\CLI @@ -91,42 +90,42 @@ BaseCommand .. php:method:: call(string $command[, array $params = []]) :param string $command: 要调用的另一个命令的名称。 - :param array $params: 要传递给该命令的其他 CLI 参数。 + :param array $params: 提供给该命令的额外 CLI 参数。 - 此方法允许你在当前命令执行期间运行其他命令: + 此方法允许你在当前命令执行期间运行其他命令： .. literalinclude:: cli_commands/005.php .. php:method:: showError(Throwable $e) - :param Throwable $e: 用于报告错误的异常。 + :param Throwable $e: 用于错误报告的异常。 - 一种保持 CLI 错误输出一致且清晰的便捷方法: + 一种便捷方法，用于在 CLI 中保持一致且清晰的错误输出： .. literalinclude:: cli_commands/006.php .. php:method:: showHelp() - 显示命令帮助的方法:(用法、参数、描述、选项) + 一种显示命令帮助的方法：（用法、参数、描述、选项） .. php:method:: setPad(string $item, int $max, int $extra = 2, int $indent = 0): string - :param string $item: 字符串项目。 - :param integer $max: 最大长度。 + :param string $item: 字符串项。 + :param integer $max: 最大尺寸。 :param integer $extra: 在末尾添加的额外空格数。 :param integer $indent: 缩进空格数。 - 填充我们的字符串,以便所有标题的长度相同,以美观地排列描述: + 填充字符串，使所有标题长度相同，以便整齐地对齐描述： .. literalinclude:: cli_commands/007.php :lines: 2- - .. php:method:: getPad($array, $pad) + .. php:method:: getPad($array, $pad) .. deprecated:: 4.0.5 - 请使用 :php:meth:`CodeIgniter\\CLI\\BaseCommand::setPad()`。 + 改用 :php:meth:`CodeIgniter\\CLI\\BaseCommand::setPad()`。 - :param array $array: ``$key => $value`` 数组。 - :param integer $pad: 填充的空格数。 + :param array $array: $key => $value 数组。 + :param integer $pad: 填充空格数。 - 计算用于 ``$key => $value`` 数组输出的填充的方法。该填充可用于在 CLI 中输出格式良好的表格。 + 一种计算 ``$key => $value`` 数组输出填充的方法。填充可用于在 CLI 中输出格式良好的表格。 diff --git a/source/cli/cli_controllers.rst b/source/cli/cli_controllers.rst index 83acf6a57..06ab3350f 100644 --- a/source/cli/cli_controllers.rst +++ b/source/cli/cli_controllers.rst @@ -2,84 +2,77 @@ 通过 CLI 运行控制器 ########################### -除了通过浏览器的 URL 调用应用程序的 :doc:`控制器 ` 外, -它们也可以通过命令行接口 (CLI) 加载。 +除了通过浏览器中的 URL 调用应用程序的 :doc:`控制器 ` 外，还可以通过命令行接口 (CLI) 来加载它们。 -.. note:: 建议使用 Spark 命令来编写 CLI 脚本,而不是通过 CLI 调用控制器。 - 有关详细信息,请参阅 :doc:`spark_commands` 和 :doc:`cli_commands` 页面。 +.. note:: 建议为 CLI 脚本使用 Spark 命令，而不是通过 CLI 调用控制器。 + 有关详细信息，请参阅 :doc:`spark_commands` 和 :doc:`cli_commands` 页面。 .. contents:: :local: :depth: 2 ************************** -让我们试一试:Hello World! +动手试试：Hello World! ************************** 创建控制器 =================== -让我们创建一个简单的控制器,这样你就可以看到它的实际效果。使用文本编辑器, -创建一个名为 Tools.php 的文件,并添加以下代码: +让我们创建一个简单的控制器，以便你直观地看到它的运行效果。使用你的文本编辑器，创建一个名为 Tools.php 的文件，并将以下代码放入其中： .. literalinclude:: cli_controllers/001.php -.. note:: 如果使用 :ref:`auto-routing-improved`,请将方法名更改为 ``cliMessage()``。 +.. note:: 如果你使用 :ref:`auto-routing-improved`，请将方法名改为 ``cliMessage()``。 -然后将该文件保存到 **app/Controllers/** 目录中。 +然后将文件保存到你的 **app/Controllers/** 目录中。 定义路由 ============== -如果使用自动路由,请跳过此步骤。 +如果使用自动路由，则可以跳过此步骤。 -在 **app/Config/Routes.php** 文件中,你可以轻松创建只能通过 CLI 访问的路由, -就像创建任何其他路由一样。与使用 ``get()``、``post()`` -或类似的方法不同,你将使用 ``cli()`` 方法。其他所有内容的工作原理与正常的路由定义完全相同: +在你的 **app/Config/Routes.php** 文件中，可以像创建其他任何路由一样轻松地创建仅可通过 CLI 访问的路由。你不需要使用 ``get()``、``post()`` 或类似的方法，而是使用 ``cli()`` 方法。其他所有内容的工作方式都与普通路由定义完全相同： .. literalinclude:: cli_controllers/002.php -有关更多信息,请参阅 :ref:`Routes ` 页面。 +有关更多信息，请参阅 :ref:`路由 ` 页面。 -.. warning:: 如果启用 :ref:`auto-routing-legacy` 并将命令文件放在 **app/Controllers** 中, - 任何人都可以在 :ref:`auto-routing-legacy` 的帮助下通过 HTTP 访问该命令。 +.. warning:: 如果你启用了 :ref:`auto-routing-legacy` 并将命令文件放在 **app/Controllers** 目录中， + 任何人都可以通过 HTTP 并借助 :ref:`auto-routing-legacy` 访问该命令。 通过 CLI 运行 -================= +============= -通常,你会使用类似于以下内容的 URL 访问站点:: +通常，你会使用类似这样的 URL 访问你的网站:: example.com/index.php/tools/message/to -相反,我们将在 Mac/Linux 上打开终端,或者在 Windows 上转到运行窗口 > “cmd”, -并导航到 CodeIgniter 项目的 web 根目录。 +相反，我们将在 Mac/Linux 上打开终端，或在 Windows 上打开“运行” > “cmd”， +在 Windows 中导航到你的 CodeIgniter 项目的 Web 根目录。 .. code-block:: bash $ cd /path/to/project/public $ php index.php tools message -如果你操作正确,应该会看到打印出 “Hello World!”。 +如果操作正确，你应该会看到打印出的 "Hello World!"。 .. code-block:: bash - $ php index.php tools message “John Smith” + $ php index.php tools message "John Smith" -这里我们以参数的方式传递内容,就像 URL 参数的工作方式一样。 -“John Smith” 被作为参数传递,输出是: +这里我们以与 URL 参数相同的方式传递了一个参数。"John Smith" 作为参数被传递，输出结果为:: Hello John Smith! ****************** -这就是基础知识! +基础知识就这些！ ****************** -简而言之,这就是有关命令行上的控制器需要了解的全部内容。 -请记住,这是一个正常的控制器,因此路由和 ``_remap()`` 正常工作。 +总而言之，关于命令行上的控制器，你需要了解的就这些。请记住，这只是一个普通的控制器，因此路由和 ``_remap()`` 方法都能正常工作。 -.. note:: ``_remap()`` 在 :ref:`auto-routing-improved` 中不起作用。 +.. note:: ``_remap()`` 与 :ref:`auto-routing-improved` 不兼容。 -如果要确保通过 CLI 运行,请检查 :php:func:`is_cli()` 的返回值。 +如果要确认是否通过 CLI 运行，可以检查 :php:func:`is_cli()` 的返回值。 -但是,CodeIgniter 提供了其他工具,可以使创建 CLI 可访问的脚本更加愉快, -包括 CLI 專用路由和一个可以帮助你使用 CLI 專用工具的库。 +然而，CodeIgniter 提供了额外的工具，使创建可通过 CLI 访问的脚本变得更加便捷，包括仅限 CLI 的路由，以及一个帮助你处理仅限 CLI 工具的库。 diff --git a/source/cli/cli_generators.rst b/source/cli/cli_generators.rst index 4836c5edf..ab44a7bbf 100644 --- a/source/cli/cli_generators.rst +++ b/source/cli/cli_generators.rst @@ -2,7 +2,7 @@ CLI 生成器 ############## -CodeIgniter4 现在配备了生成器,以简化常规控制器、模型、实体等的创建。你还可以使用一个命令搭建一整套完整的文件。 +CodeIgniter4 现在配备了生成器，可以简化创建标准控制器、模型、实体等文件的过程。你也可以通过一条命令搭建一整套文件。 .. contents:: :local: @@ -12,20 +12,19 @@ CodeIgniter4 现在配备了生成器,以简化常规控制器、模型、实体 简介 ************ -所有内置生成器在使用 ``php spark list`` 列出时都位于 ``Generators`` 组下。 -要查看特定生成器的完整描述和使用信息,请使用命令: +当使用 ``php spark list`` 命令列出时，所有内置的生成器都位于 ``Generators`` 组下。要查看特定生成器的完整描述和用法信息，请使用以下命令： .. code-block:: console - php spark help <生成器命令> + php spark help -其中 ``<生成器命令>`` 将替换为要检查的命令。 +其中 ```` 将替换为要检查的命令。 -.. note:: 你需要在子文件夹中生成代码吗?例如,如果你想在主 ``Controllers`` 文件夹的 ``Admin`` 子文件夹中创建一个控制器类,你只需要在类名前加上子文件夹,像这样:``php spark make:controller admin/login``。这个命令将在 ``Controllers/Admin`` 子文件夹中创建 ``Login`` 控制器,命名空间为 ``App\Controllers\Admin``。 +.. note:: 你需要将生成的代码放在子文件夹中吗？例如，如果你想创建一个位于主 ``Controllers`` 文件夹的 ``Admin`` 子文件夹中的控制器类，你只需在类名前加上子文件夹名称，如下所示：``php spark make:controller admin/login``。此命令将在 ``Controllers/Admin`` 子文件夹中创建 ``Login`` 控制器，并且命名空间为 ``App\Controllers\Admin``。 -.. note:: 在模块上工作?代码生成将根命名空间默认设置为 ``APP_NAMESPACE``。如果需要在模块命名空间的其他位置生成代码,请确保在命令中设置 ``--namespace`` 选项,例如 ``php spark make:model blog --namespace Acme\\Blog``。 +.. note:: 正在开发模块吗？代码生成会将根命名空间设置为默认的 ``APP_NAMESPACE``。如果你需要将生成的代码放在模块命名空间的其他位置，请确保在命令中设置 ``--namespace`` 选项，例如：``php spark make:model blog --namespace Acme\\Blog``。 -.. warning:: 设置 ``--namespace`` 选项时,请确保提供的命名空间是在 ``Config\Autoload`` 中的 ``$psr4`` 数组或你的 composer 自动加载文件中定义的有效命名空间。否则,代码生成将中断。 +.. warning:: 设置 ``--namespace`` 选项时，请确保提供的命名空间是在 ``Config\Autoload`` 的 ``$psr4`` 数组中定义的，或者在 Composer 的自动加载文件中定义的有效命名空间。否则，代码生成将被中断。 ******************* 内置生成器 @@ -40,177 +39,177 @@ make:cell 创建一个新的 Cell 文件及其视图。 -用法: +用法： ====== :: - make:cell <名称> [选项] + make:cell [options] -参数: +参数： ========= -* ``名称``:单元类的名称。应为 PascalCase。**[必需]** +* ``name``：Cell 类的名称。应该使用 PascalCase。 **[必需] ** -选项: +选项： ======== -* ``--namespace``:设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 -* ``--force``:设置此标志以覆盖目标上的现有文件。 +* ``--namespace``：设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 +* ``--force``：设置此标志以覆盖目标位置的现有文件。 make:command ------------ 创建一个新的 spark 命令。 -用法: +用法： ====== :: - make:command <名称> [选项] + make:command [options] -参数: +参数： ========= -* ``名称``:命令类的名称。**[必需]** +* ``name``：命令类的名称。 **[必需] ** -选项: +选项： ======== -* ``--command``:在 spark 中运行的命令名称。默认为 ``command:name``。 -* ``--group``:命令的组/命名空间。对于基本命令默认为 ``App``,对于生成器命令默认为 ``Generators``。 -* ``--type``:命令类型,可以是 ``basic`` 基本命令或 ``generator`` 生成器命令。默认为 ``basic``。 -* ``--namespace``:设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 -* ``--suffix``:在生成的类名后附加组件后缀。 -* ``--force``:设置此标志以覆盖目标上的现有文件。 +* ``--command``：在 spark 中运行的命令名称。默认为 ``command:name``。 +* ``--group``：命令的组/命名空间。基本命令默认为 ``App``，生成器命令默认为 ``Generators``。 +* ``--type``：命令的类型，可以是 ``basic``（基本）命令或 ``generator``（生成器）命令。默认为 ``basic``。 +* ``--namespace``：设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 +* ``--suffix``：将组件后缀附加到生成的类名上。 +* ``--force``：设置此标志以覆盖目标位置的现有文件。 make:config ----------- 创建一个新的配置文件。 -用法: +用法： ====== :: - make:config <名称> [选项] + make:config [options] -参数: +参数： ========= -* ``名称``:配置类的名称。**[必需]** +* ``name``：配置类的名称。 **[必需] ** -选项: +选项： ======== -* ``--namespace``:设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 -* ``--suffix``:在生成的类名后附加组件后缀。 -* ``--force``:设置此标志以覆盖目标上的现有文件。 +* ``--namespace``：设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 +* ``--suffix``：将组件后缀附加到生成的类名上。 +* ``--force``：设置此标志以覆盖目标位置的现有文件。 make:controller --------------- 创建一个新的控制器文件。 -用法: +用法： ====== :: - make:controller <名称> [选项] + make:controller [options] -参数: +参数： ========= -* ``名称``:控制器类的名称。**[必需]** +* ``name``：控制器类的名称。 **[必需] ** -选项: +选项： ======== -* ``--bare``:扩展自 ``CodeIgniter\Controller`` 而不是 ``BaseController``。 -* ``--restful``:扩展自一个 RESTful 资源。可选 ``controller`` 和 ``presenter``。默认为 ``controller``。 -* ``--namespace``:设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 -* ``--suffix``:在生成的类名后附加组件后缀。 -* ``--force``:设置此标志以覆盖目标上的现有文件。 +* ``--bare``：从 ``CodeIgniter\Controller`` 而不是 ``BaseController`` 继承。 +* ``--restful``：从 RESTful 资源继承。选项有 ``controller`` 和 ``presenter``。默认为 ``controller``。 +* ``--namespace``：设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 +* ``--suffix``：将组件后缀附加到生成的类名上。 +* ``--force``：设置此标志以覆盖目标位置的现有文件。 -.. note:: 如果使用 ``--suffix``,生成的控制器名称将类似于 ``ProductController``。这与使用 :ref:`自动路由 ` 的控制器命名约定相违背(控制器类名必须以大写字母开头,且只能大写第一个字符)。所以 ``--suffix`` 可与 :ref:`定义路由 ` 一起使用。 +.. note:: 如果你使用 ``--suffix``，生成的控制器名称将类似于 ``ProductController``。这违反了使用 :ref:`自动路由 ` 时的控制器命名约定（控制器类名必须以大写字母开头，并且只有第一个字符可以是大写）。因此，当使用 :ref:`定义路由 ` 时，可以使用 ``--suffix``。 make:entity ----------- 创建一个新的实体文件。 -用法: +用法： ====== :: - make:entity <名称> [选项] + make:entity [options] -参数: +参数： ========= -* ``名称``:实体类的名称。**[必需]** +* ``name``：实体类的名称。 **[必需] ** -选项: +选项： ======== -* ``--namespace``:设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 -* ``--suffix``:在生成的类名后附加组件后缀。 -* ``--force``:设置此标志以覆盖目标上的现有文件。 +* ``--namespace``：设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 +* ``--suffix``：将组件后缀附加到生成的类名上。 +* ``--force``：设置此标志以覆盖目标位置的现有文件。 make:filter ----------- 创建一个新的过滤器文件。 -用法: +用法： ====== :: - make:filter <名称> [选项] + make:filter [options] -参数: +参数： ========= -* ``名称``:过滤器类的名称。**[必需]** +* ``name``：过滤器类的名称。 **[必需] ** -选项: +选项： ======== -* ``--namespace``:设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 -* ``--suffix``:在生成的类名后附加组件后缀。 -* ``--force``:设置此标志以覆盖目标上的现有文件。 +* ``--namespace``：设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 +* ``--suffix``：将组件后缀附加到生成的类名上。 +* ``--force``：设置此标志以覆盖目标位置的现有文件。 make:model ---------- 创建一个新的模型文件。 -用法: +用法： ====== :: - make:model <名称> [选项] + make:model [options] -参数: +参数： ========= -* ``名称``:模型类的名称。**[必需]** +* ``name``：模型类的名称。 **[必需] ** -选项: +选项： ======== -* ``--dbgroup``:要使用的数据库组。默认为 ``default``。 -* ``--return``:设置返回类型,可以是 ``array``、``object`` 或 ``entity``。默认为 ``array``。 -* ``--table``:提供不同的表名。默认为将类名复数化。 -* ``--namespace``:设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 -* ``--suffix``:在生成的类名后附加组件后缀。 -* ``--force``:设置此标志以覆盖目标上的现有文件。 +* ``--dbgroup``：要使用的数据库组。默认为 ``default``。 +* ``--return``：设置返回类型，可选 ``array``、``object`` 或 ``entity``。默认为 ``array``。 +* ``--table``：提供不同的表名。默认为类名的复数形式。 +* ``--namespace``：设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 +* ``--suffix``：将组件后缀附加到生成的类名上。 +* ``--force``：设置此标志以覆盖目标位置的现有文件。 make:seeder ----------- -创建一个新的种子文件。 +创建一个新的数据填充文件。 -用法: +用法： ====== :: - make:seeder <名称> [选项] + make:seeder [options] -参数: +参数： ========= -* ``名称``:种子类的名称。**[必需]** +* ``name``：数据填充类的名称。 **[必需] ** -选项: +选项： ======== -* ``--namespace``:设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 -* ``--suffix``:在生成的类名后附加组件后缀。 -* ``--force``：设置此标志以覆盖目标上的现有文件。 +* ``--namespace``：设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 +* ``--suffix``：将组件后缀附加到生成的类名上。 +* ``--force``：设置此标志以覆盖目标位置的现有文件。 .. _cli-generators-make-test: @@ -229,93 +228,93 @@ make:test 参数： ========= -* ``name``：测试类的名称。 **[必需]** +* ``name``：测试类的名称。 **[必需] ** 选项： ======== * ``--namespace``：设置根命名空间。默认为 ``Tests`` 的值。 -* ``--force``:设置此标志以覆盖目标上的现有文件。 +* ``--force``：设置此标志以覆盖目标位置的现有文件。 make:migration -------------- 创建一个新的迁移文件。 -用法: +用法： ====== :: - make:migration <名称> [选项] + make:migration [options] -参数: +参数： ========= -* ``名称``:迁移类的名称。**[必需]** +* ``name``：迁移类的名称。 **[必需] ** -选项: +选项： ======== -* ``--session``:为数据库会话生成迁移文件。 -* ``--table``:设置数据库会话的表名。默认为 ``ci_sessions``。 -* ``--dbgroup``:设置数据库会话的数据库组。默认为 ``default`` 组。 -* ``--namespace``:设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 -* ``--suffix``:在生成的类名后附加组件后缀。 -* ``--force``:设置此标志以覆盖目标上的现有文件。 +* ``--session``：为数据库会话生成一个迁移文件。 +* ``--table``：为数据库会话设置表名。默认为 ``ci_sessions``。 +* ``--dbgroup``：为数据库会话设置数据库组。默认为 ``default`` 组。 +* ``--namespace``：设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 +* ``--suffix``：将组件后缀附加到生成的类名上。 +* ``--force``：设置此标志以覆盖目标位置的现有文件。 make:validation --------------- 创建一个新的验证文件。 -用法: +用法： ====== :: - make:validation <名称> [选项] + make:validation [options] -参数: +参数： ========= -* ``名称``:验证类的名称。**[必需]** +* ``name``：验证类的名称。 **[必需] ** -选项: +选项： ======== -* ``--namespace``:设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 -* ``--suffix``:在生成的类名后附加组件后缀。 -* ``--force``:设置此标志以覆盖目标上的现有文件。 +* ``--namespace``：设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 +* ``--suffix``：将组件后缀附加到生成的类名上。 +* ``--force``：设置此标志以覆盖目标位置的现有文件。 **************************************** -搭建一整套完整的代码 +搭建一整套标准代码 **************************************** -在开发阶段,我们有时会分组创建功能,比如创建一个 *Admin* 组。该组将包含自己的控制器、模型、迁移文件,甚至实体。你可能会想一一在终端中输入每个生成器命令,并希望有一个单一的生成器命令可以统治一切。 +有时在开发阶段，我们会按组创建功能，例如创建一个 *Admin* 组。这个组将包含它自己的控制器、模型、迁移文件，甚至实体。你可能会想在终端中逐个输入每个生成器命令，并希望有一个单一的生成器命令可以搞定一切。 -不要担心!CodeIgniter4 还配备了专用的 ``make:scaffold`` 命令,它基本上是控制器、模型、实体、迁移和种子生成器命令的包装器。你只需要输入用于命名所有生成类的类名。另外, **每个生成器命令支持的单独选项** 也会被脚手架命令识别。 +不必再担心了！CodeIgniter4 还附带了一个专门的 ``make:scaffold`` 命令，它基本上是控制器、模型、实体、迁移和数据填充生成器命令的包装器。你只需要提供将用于命名所有生成类的类名。此外，每个生成器命令支持的 **独立选项** 也会被脚手架命令识别。 -在终端中运行此命令: +在终端中运行以下命令： .. code-block:: console php spark make:scaffold user -将创建以下文件: +将创建以下文件： (1) **app/Controllers/User.php** (2) **app/Models/User.php** -(3) **app/Database/Migrations/<某日期>_User.php** 和 +(3) **app/Database/Migrations/<日期>_User.php** 以及 (4) **app/Database/Seeds/User.php** -要在生成的文件中包含 ``Entity`` 类,只需在命令中包含 ``--return entity`` 选项即可将其传递给模型生成器。 +要将 ``Entity`` 类包含在搭建的文件中，只需在命令中包含 ``--return entity``，它将被传递给模型生成器。 ************** GeneratorTrait ************** -所有生成器命令必须使用 ``GeneratorTrait`` 以充分利用其在代码生成中使用的方法。 +所有生成器命令都必须使用 ``GeneratorTrait`` 以充分利用其在代码生成中使用的方法。 ************************************************************* 声明自定义生成器命令模板的位置 ************************************************************* -生成器模板的默认查找顺序是 (1) **app/Config/Generators.php** 文件中定义的模板,如果未找到,则是 (2) 在 ``CodeIgniter\Commands\Generators\Views`` 命名空间下找到的模板。 +查找生成器模板的默认顺序是：(1) 在 **app/Config/Generators.php** 文件中定义的模板，以及 (2) 如果未找到，则在 ``CodeIgniter\Commands\Generators\Views`` 命名空间中找到的模板。 -要为自定义生成器命令声明模板位置,需要将其添加到 **app/Config/Generators.php** 文件中。例如,如果你有一个命令 ``make:awesome-command``,并且生成器模板位于 *app* 目录 **app/Commands/Generators/Views/awesomecommand.tpl.php** 中,则需要按如下方式更新配置文件: +要为你的自定义生成器命令声明模板位置，你需要将其添加到 **app/Config/Generators.php** 文件中。例如，如果你有一个 ``make:awesome-command`` 命令，并且你的生成器模板位于 *app* 目录内的 **app/Commands/Generators/Views/awesomecommand.tpl.php**，你应该像这样更新配置文件： .. literalinclude:: cli_generators/001.php diff --git a/source/cli/cli_library.rst b/source/cli/cli_library.rst index b3df98685..0f0ff17f1 100644 --- a/source/cli/cli_library.rst +++ b/source/cli/cli_library.rst @@ -2,13 +2,13 @@ CLI 库 ########### -CodeIgniter 的 CLI 库可以轻松创建交互式命令行脚本,包括: +CodeIgniter 的 CLI 库让创建交互式命令行脚本变得简单，包括： -* 提示用户提供更多信息 -* 在终端上写入多彩文本 -* 蜂鸣声(要友好!) +* 向用户提示更多信息 +* 在终端中写入多色文本 +* 发出提示音（请友好使用！） * 在长时间任务期间显示进度条 -* 将过长的文本行包装以适应窗口 +* 将长文本行换行以适应窗口宽度。 .. contents:: :local: @@ -17,55 +17,56 @@ CodeIgniter 的 CLI 库可以轻松创建交互式命令行脚本,包括: 初始化类 ********************** -你不需要创建 CLI 库的实例,因为它的所有方法都是静态的。相反,你只需要通过控制器顶部的 ``use`` 语句确保控制器可以定位它: +由于 CLI 库的所有方法都是静态的，你无需创建其实例。相反，你只需确保控制器可以通过类上方的 ``use`` 语句找到它： .. literalinclude:: cli_library/001.php -该类在首次加载文件时会自动初始化。 +该类在文件首次加载时会自动初始化。 -获取用户输入 +从用户获取输入 *************************** -有时你需要询问用户更多信息。他们可能没有提供可选的命令行参数,或者脚本可能遇到现有文件并需要确认才能覆盖。这通过 ``prompt()`` 或 ``promptByKey()`` 方法来处理。 +有时你需要向用户询问更多信息。他们可能没有提供可选的命令行参数，或者脚本可能遇到了一个已存在的文件，需要在覆盖前进行确认。这可以通过 ``prompt()`` 或 ``promptByKey()`` 方法来处理。 -.. note:: 从 v4.3.0 开始,你可以用 ``PhpStreamWrapper`` 为这些方法编写测试。 - 请参阅 :ref:`testing-cli-input`。 +.. note:: 从 v4.3.0 版本开始，你可以使用 ``PhpStreamWrapper`` 为这些方法编写测试。 + 参见 :ref:`testing-cli-input`。 prompt() ======== -你可以通过作为第一个参数传递问题来提供一个问题: +你可以通过将问题作为第一个参数传入来提供： .. literalinclude:: cli_library/002.php -你可以通过在第二个参数中传递默认值,为用户只需按 Enter 提供默认答案: +你可以通过将默认值作为第二个参数传入，来提供一个默认答案，当用户直接按回车键时会使用该答案： .. literalinclude:: cli_library/003.php -你可以通过作为第二个参数传递允许答案的数组来限制可接受的答案: +你可以通过将允许的答案数组作为第二个参数传入，来限制可接受的答案： .. literalinclude:: cli_library/004.php -最后,你可以将答案输入的 :ref:`验证 ` 规则作为第三个参数传递: +最后，你可以将 :ref:`验证 ` 规则作为第三个参数传入答案输入： .. literalinclude:: cli_library/005.php -验证规则也可以以数组语法编写: +验证规则也可以用数组语法编写： .. literalinclude:: cli_library/006.php promptByKey() ============= -预定义的提示答案(选项)有时需要描述或过于复杂,无法通过其值进行选择。``promptByKey()`` 允许用户通过其键而不是值来选择选项: +对于提示，预定义的答案（选项）有时需要描述，或者过于复杂而无法通过其值来选择。 +``promptByKey()`` 允许用户通过键而不是值来选择选项： .. literalinclude:: cli_library/007.php -命名键也是可能的: +命名键也是可能的： .. literalinclude:: cli_library/008.php -最后,你可以将答案输入的 :ref:`验证 ` 规则作为第三个参数传递,可接受的答案会自动限制为传入的选项。 +最后，你可以将 :ref:`验证 ` 规则作为第三个参数传入答案输入，可接受的答案会自动限制为传入的选项。 .. _prompt-by-multiple-keys: @@ -74,11 +75,11 @@ promptByMultipleKeys() .. versionadded:: 4.3.0 -这个方法与 ``promptByKey()`` 相同,但它支持多个值。 +此方法与 ``promptByKey()`` 相同，但支持多个值。 .. literalinclude:: cli_library/023.php -.. important:: 与 ``promptByKey()`` 不同, ``promptByMultipleKeys()`` 方法不支持命名键或验证。 +.. important:: 方法 ``promptByMultipleKeys()`` 与 ``promptByKey()`` 不同，不支持命名键或验证。 提供反馈 ****************** @@ -86,19 +87,19 @@ promptByMultipleKeys() write() ======= -提供了几种方法来向用户提供反馈。这可以是简单的单个状态更新,也可以是复杂的信息表格,会换行到用户的终端窗口。这其核心是 ``write()`` 方法,它以要输出的字符串作为第一个参数: +提供了几种方法，让你可以向用户提供反馈。这可以是简单的状态更新，也可以是适应用户终端窗口宽度的复杂信息表。核心是 ``write()`` 方法，它将要输出的字符串作为第一个参数： .. literalinclude:: cli_library/009.php -你可以通过在第二个参数中传递颜色名称来更改文本颜色: +你可以通过将颜色名称作为第二个参数传入来更改文本颜色： .. literalinclude:: cli_library/010.php -这可以用来按状态区分消息,或通过使用不同的颜色创建“标题”。你甚至可以通过将颜色名称作为第三个参数传递来设置背景颜色: +这可用于区分不同状态的消息，或通过使用不同颜色创建“标题”。你甚至可以通过将颜色名称作为第三个参数传入来设置背景色： .. literalinclude:: cli_library/011.php -以下前景色可用: +以下前景色可用： * black * dark_gray @@ -118,7 +119,7 @@ write() * light_gray * white -并且有更小数量的背景色可用: +背景色可用的种类较少： * black * blue @@ -132,7 +133,8 @@ write() print() ======= -``print()`` 的作用与 ``write()`` 方法相同,只是它不会在前后强制换行。相反,它会将内容打印到光标当前所在的屏幕上。这允许你从不同的调用中在同一行上打印多个项目。当你想显示一个状态,执行一些操作,然后在同一行上打印“Done”时,这特别有用: +print() 的功能与 ``write()`` 方法完全相同，只是它不会在前后强制换行。 +相反，它会将内容打印到光标当前所在的位置。这允许你通过不同的调用在同一行上打印多个项目。当你想要显示一个状态，执行某个操作，然后在同一行上打印“Done”时，这尤其有用： .. literalinclude:: cli_library/012.php @@ -141,69 +143,72 @@ print() color() ======= -虽然 ``write()`` 命令会将单行写入终端,并在结束时带有 EOL 字符,但你可以使用 ``color()`` 方法来制作一个字符串片段,可以以相同的方式使用,不同之处在于打印后不会强制 EOL。这允许你在同一行上创建多个输出。或者,更常见的是,你可以在 ``write()`` 方法中使用它来创建不同颜色的字符串: +虽然 ``write()`` 命令会将单行写入终端，并以 EOL 字符结尾，但你可以使用 ``color()`` 方法创建一个字符串片段，其使用方式相同，只是它不会在打印后强制换行。这允许你在同一行上创建多个输出。或者，更常见的是，你可以在 ``write()`` 方法内部使用它来创建内部不同颜色的字符串： .. literalinclude:: cli_library/013.php -这个示例将在窗口中写入一行, ``fileA`` 为黄色,后跟一个制表符,然后是白色的 ``/path/to/file``。 +此示例会将单行写入窗口，其中 ``fileA`` 为黄色，后跟一个制表符，然后是白色文本的 ``/path/to/file``。 error() ======= -如果需要输出错误,你应该使用适当命名的 ``error()`` 方法。这会将浅红色文本写入 STDERR,而不是像 ``write()`` 和 ``color()`` 那样写入 STDOUT。如果你有监视错误的脚本,这样可以方便它们不必筛选所有信息,而只提取实际的错误消息。你可以像使用 ``write()`` 方法一样使用它: +如果需要输出错误，你应该使用相应的 ``error()`` 方法。它会将浅红色文本写入 STDERR，而不是像 ``write()`` 和 ``color()`` 那样写入 STDOUT。如果你有脚本在监视错误，这会很有用，这样它们就不必筛选所有信息，只需关注实际的错误消息。你使用它的方式与使用 ``write()`` 方法完全相同： .. literalinclude:: cli_library/014.php wrap() ====== -这个命令将获取一个字符串,开始在当前行打印它,并将其换行到设置的长度。当显示你想要在当前窗口中换行而不是超出屏幕的选项及其描述时,这可能很有用: +此命令将获取一个字符串，从当前行开始打印，并在新行上将其换行到设定的长度。 +当你需要显示一个带有描述的选项列表，并希望这些描述在当前窗口内换行而不超出屏幕时，这可能会很有用： .. literalinclude:: cli_library/015.php -默认情况下,字符串将换行到终端宽度。Windows 当前没有提供确定窗口大小的方法,因此我们默认为 80 个字符。如果你想将宽度限制为一些可以相当确定适合窗口的较短长度,请将最大行长度作为第二个参数传递。这将在最接近的词边界处中断字符串,以免单词被断开。 +默认情况下，字符串将在终端宽度处换行。Windows 当前无法确定窗口大小，因此我们默认为 80 个字符。如果你想将宽度限制为更短的长度，以确保其能适应窗口，请将最大行长度作为第二个参数传入。这会在最近的单词边界处断开字符串，以避免单词被拆分。 .. literalinclude:: cli_library/016.php -你可能会发现,你想要标题、文件或任务的左边有一列,而右边有描述文本的一列。默认情况下,这将回绕到窗口的左边缘,这不允许项目按列对齐。在这种情况下,你可以传入换行后要填充的空格数,以便在左边有一个整齐的列边界: +你可能会发现，你希望左侧有一列标题、文件或任务，而在右侧有一列对应的描述文本。默认情况下，换行会回到窗口的左边缘，这不允许内容在列中对齐。在这种情况下，你可以传入一定数量的空格来填充第一行之后的每一行，这样左侧就会有一个清晰的列边缘： .. literalinclude:: cli_library/017.php -这将创建类似如下的内容: +将创建类似以下内容： .. code-block:: none - task1a Lorem Ipsum 只是印刷和排版 - 行业的虚构文字 - task1abc Lorem Ipsum 从1500年代起 - 就一直是行业的标准虚构文字 + task1a Lorem Ipsum is simply dummy + text of the printing and + typesetting industry. + task1abc Lorem Ipsum has been the + industry's standard dummy + text ever since the newLine() ========= -``newLine()`` 方法向用户显示一个空行。它不接受任何参数: +``newLine()`` 方法会向用户显示一个空白行。它不接受任何参数： .. literalinclude:: cli_library/018.php clearScreen() ============= -你可以使用 ``clearScreen()`` 方法清除当前的终端窗口。在大多数 Windows 版本中,这只会插入 40 行空白行,因为 Windows 不支持此功能。Windows 10 bash 集成应该会改变这一点: +你可以使用 ``clearScreen()`` 方法清空当前终端窗口。在大多数 Windows 版本中，这只会插入 40 个空白行，因为 Windows 不支持此功能。Windows 10 的 bash 集成可能会改变这一点： .. literalinclude:: cli_library/019.php showProgress() ============== -如果你有一个长时间运行的任务,希望保持用户了解进度,可以使用 ``showProgress()`` 方法,它会显示类似以下内容: +如果你有一个长时间运行的任务，并希望向用户实时更新进度，可以使用 ``showProgress()`` 方法，它会显示类似以下内容： .. code-block:: none [####......] 40% Complete -此块会就地进行动画以产生非常好的效果。 +该方块在原位置进行动画，效果非常不错。 -使用时,请将当前步骤作为第一个参数传递,将总步骤数作为第二个参数。完成百分比和显示长度将根据该数字确定。完成时,请将 ``false`` 作为第一个参数传入,进度条将被删除。 +使用时，将当前步骤作为第一个参数传入，将总步骤数作为第二个参数传入。完成百分比和显示长度将基于该数字确定。完成后，将第一个参数传为 ``false``，进度条将被移除。 .. literalinclude:: cli_library/020.php @@ -217,13 +222,13 @@ table() +----+--------------------------+---------------------+--------+ | ID | Title | Updated At | Active | +----+--------------------------+---------------------+--------+ - | 7 | A great item title | 2017-11-15 10:35:02 | 1 | + | 7 | A great item title | 2017-11-16 10:35:02 | 1 | | 8 | Another great item title | 2017-11-16 13:46:54 | 0 | +----+--------------------------+---------------------+--------+ wait() ====== -等待一定的秒数,可选择显示等待消息并等待按键。 +等待一定数量的秒数，可选择性地显示等待消息并等待按键。 .. literalinclude:: cli_library/022.php diff --git a/source/cli/cli_overview.rst b/source/cli/cli_overview.rst index 7a54fdac7..0f8f0c50b 100644 --- a/source/cli/cli_overview.rst +++ b/source/cli/cli_overview.rst @@ -1,49 +1,50 @@ ############ -CLI 概览 +CLI 概述 ############ -CodeIgniter 4 提供了内置命令 **spark** 和有用的命令与库。 -你还可以创建 spark 命令,并通过 CLI 运行控制器。 +CodeIgniter 4 提供了内置的 **spark** 命令以及实用的命令和库。 +你也可以创建 spark 命令，并通过 CLI 运行控制器。 .. contents:: :local: :depth: 2 **************** -什么是 CLI? +什么是 CLI？ **************** -命令行接口是一种通过文本方式与计算机交互的方法。有关更多信息,请查看 `维基百科文章 `_。 +命令行接口（CLI）是一种基于文本的计算机交互方式。 +欲了解更多信息，请查阅 `维基百科文章 `_。 ***************************** -为什么通过命令行运行? +为什么要通过命令行运行？ ***************************** -有许多原因可以通过命令行运行 CodeIgniter,但这些原因并不总是明显的。 +从命令行运行 CodeIgniter 有许多原因，但这些原因并不总是显而易见。 -- 在不需要使用 *wget* 或 *curl* 的情况下运行 cron 作业。 -- 制作交互式“任务”,可以执行设置权限、清理缓存文件夹、运行备份等操作。 -- 与其他语言的其他应用程序集成。例如,随机的 C++ 脚本可以调用一个命令并在模型中运行代码! +- 运行你的定时任务（cron-jobs），无需使用 *wget* 或 *curl*。 +- 创建交互式“任务”，可以执行设置权限、清理缓存文件夹、运行备份等操作。 +- 与其他语言的应用程序集成。例如，一个随机的 C++ 脚本可以调用一个命令，运行你模型中的代码！ ****************** Spark 命令 ****************** -CodeIgniter 提供了官方命令 **spark** 和内置命令。 +CodeIgniter 随附官方的 **spark** 命令和内置命令。 -你可以运行 spark 并查看帮助: +你可以运行 spark 查看帮助： .. code-block:: console php spark -有关详细信息,请参阅 :doc:`spark_commands` 页面。 +详细信息请参阅 :doc:`spark_commands` 页面。 *************** CLI 库 *************** -CLI 库使使用 CLI 接口变得简单。 -它提供了将文本输出到终端窗口的多种颜色的简单方法。它还允许提示用户提供信息,从而轻松构建灵活、智能的工具。 +CLI 库使得与命令行接口交互变得简单。 +它提供了在终端窗口中以多种颜色输出文本的便捷方法。同时，它还允许你向用户提示信息，从而轻松构建灵活、智能的工具。 -有关详细信息,请参阅 :doc:`CLI 库 ` 页面。 +详细信息请参阅 :doc:`CLI 库 ` 页面。 diff --git a/source/cli/cli_request.rst b/source/cli/cli_request.rst index 94a8f7c1b..031ae440e 100644 --- a/source/cli/cli_request.rst +++ b/source/cli/cli_request.rst @@ -2,7 +2,9 @@ CLIRequest 类 **************** -如果请求来自命令行调用,则请求对象实际上是一个 ``CLIRequest``。它的行为与 :doc:`常规请求 ` 相同,但添加了一些方便的访问器方法。 +如果请求来自命令行调用，请求对象实际上是 +``CLIRequest``。它的行为与 :doc:`常规请求 ` +相同，但增加了一些方便使用的访问器方法。 ==================== 额外的访问器 @@ -11,38 +13,38 @@ CLIRequest 类 getSegments() ------------- -返回被视为路径一部分的命令行参数数组: +返回被视为路径一部分的命令行参数数组： .. literalinclude:: cli_request/001.php getPath() --------- -返回重构后的路径字符串: +以字符串形式返回重建后的路径： .. literalinclude:: cli_request/002.php getOptions() ------------ -返回被视为选项的命令行参数数组: +返回被视为选项的命令行参数数组： .. literalinclude:: cli_request/003.php getOption($key) ----------------- -返回被视为选项的特定命令行参数的值: +返回被视为选项的特定命令行参数的值： .. literalinclude:: cli_request/004.php getOptionString() ----------------- -返回重构后的命令行选项字符串: +返回选项的重建命令行字符串： .. literalinclude:: cli_request/005.php -向第一个参数传递 ``true`` 将尝试使用两个破折号编写长选项: +将 ``true`` 传递给第一个参数会尝试使用两个连字符来写长选项： .. literalinclude:: cli_request/006.php diff --git a/source/cli/spark_commands.rst b/source/cli/spark_commands.rst index bfcfc1870..343d6a968 100644 --- a/source/cli/spark_commands.rst +++ b/source/cli/spark_commands.rst @@ -15,13 +15,14 @@ CodeIgniter 提供了官方命令 **spark** 和内置命令。 通过 CLI 运行 =============== -命令是从命令行中在项目根目录下运行的。 +命令从项目根目录的命令行运行。 提供了一个名为 **spark** 的命令文件，用于运行任何 CLI 命令。 显示命令列表 ------------------------ -当不指定命令调用 **spark** 时，会显示一个简单的帮助页面，其中还提供了按类别排序的可用命令列表及其描述： +调用 **spark** 但不指定命令时，会显示一个简单的帮助页面， +其中还提供了可用命令及其描述的列表，按类别排序： .. code-block:: console @@ -36,22 +37,22 @@ spark list php spark list -你还可以使用 ``--simple`` 选项获取按字母顺序排序的所有可用命令的原始列表： +你也可以使用 ``--simple`` 选项来获取按字母顺序排序的所有可用命令的原始列表： .. code-block:: console php spark list --simple -显示帮助 +获取帮助 ------------ -你可以使用 ``help`` 命令获取有关任何 CLI 命令的帮助，如下所示： +你可以使用 ``help`` 命令来获取任何 CLI 命令的帮助信息，如下所示： .. code-block:: console php spark help db:seed -自 v4.3.0 起，你还可以使用 ``--help`` 选项代替 ``help`` 命令： +从 v4.3.0 开始，你也可以使用 ``--help`` 选项代替 ``help`` 命令： .. code-block:: console @@ -60,30 +61,30 @@ spark list 运行命令 ----------------- -你应该将命令的名称作为第一个参数传递以运行该命令： +你应该将命令名称作为第一个参数传递来运行该命令： .. code-block:: console php spark migrate -某些命令接受附加参数，这些参数应该直接在命令之后用空格分隔提供： +一些命令需要额外的参数，这些参数应直接在命令后提供，以空格分隔： .. code-block:: console php spark db:seed DevUserSeeder -对于 CodeIgniter 提供的所有命令，如果你没有提供所需的参数，系统将提示你提供运行所需的信息： +对于 CodeIgniter 提供的所有命令，如果你没有提供所需的参数，系统会提示你输入运行命令所需的信息： .. code-block:: console php spark make:controller - Controller 类名： + Controller class name : 抑制头部输出 ------------------------- -运行命令时，会输出包含 CodeIgniter 版本和当前时间的头部信息： +当你运行命令时，会输出包含 CodeIgniter 版本和当前时间的头部信息： .. code-block:: console @@ -93,7 +94,7 @@ spark list Your environment is currently set as development. -你可以始终传递 ``--no-header`` 以抑制头部输出，这对于解析结果很有帮助： +你始终可以传递 ``--no-header`` 来抑制头部输出，这在解析结果时很有用： .. code-block:: console @@ -104,10 +105,12 @@ spark list 调用命令 ================ -命令也可以从你自己的代码中运行。这通常在控制器中用于 cron 任务，但可以随时使用。你可以使用 ``command()`` 函数来实现。该函数始终可用。 +你也可以在自己的代码中运行命令。这最常在控制器中用于定时任务（cronjob）， +但也可以随时使用。你可以通过使用 ``command()`` 函数来实现。这个函数始终可用。 .. literalinclude:: cli_commands/001.php -唯一的参数是字符串，即所调用的命令和任何参数。它的使用方式与从命令行调用完全相同。 +唯一的参数是一个字符串，包含要调用的命令及其所有参数。其形式与你在命令行中调用时完全相同。 -当不从命令行运行时，所有运行的命令的输出都会被捕获。它会从命令中返回，以便你可以选择是否显示它。 +当命令不在命令行中运行时，命令的所有输出都会被捕获。这些输出会从命令中返回， +因此你可以选择是否显示它们。 diff --git a/source/concepts/autoloader.rst b/source/concepts/autoloader.rst index 811559448..903a4a980 100755 --- a/source/concepts/autoloader.rst +++ b/source/concepts/autoloader.rst @@ -6,55 +6,63 @@ :local: :depth: 2 -每个应用程序由许多不同位置的大量类组成。 -框架为核心功能提供类。你的应用程序将具有许多库、模型和其他实体才能正常工作。你可能会使用第三方类。跟踪每个文件的位置,并在一系列 ``require()`` 中硬编码该位置是一个巨大的头疼且极易出错。这就是自动加载器的用武之地。 +每个应用程序都包含大量位于不同位置的类。框架为核心功能提供了类，你的应用程序需要 +许多库、模型和其他实体来正常工作，项目中可能还会用到第三方类。追踪每个文件 +的确切位置，并在代码中通过一系列 ``require()`` 硬编码这些位置， +这会带来巨大的麻烦且极易出错。自动加载器（autoloader）正是为了解决这个问题而生。 *********************** CodeIgniter4 自动加载器 *********************** -CodeIgniter 提供了一个非常灵活的自动加载器，只需进行很少的配置即可使用。它可以定位符合 `PSR-4`_ 自动加载目录结构的各个命名空间类。 +CodeIgniter 提供了一个非常灵活的自动加载器，几乎无需配置即可使用。 +它能够定位遵循 `PSR-4`_ 自动加载目录结构的独立命名空间类。 .. _PSR-4: https://www.php-fig.org/psr/psr-4/ -自动加载器本身工作良好,但也可以与其他自动加载器(如 `Composer `_)一起使用,如果需要的话,甚至可以与你自己的自定义自动加载器一起使用。 -因为它们都通过 `spl_autoload_register `_ 注册,所以它们顺序工作,不会相互干扰。 +自动加载器可以独立工作，也可以与其他自动加载器（如 `Composer `_） +或你自定义的自动加载器协同工作。因为它们都通过 +`spl_autoload_register `_ +进行注册，所以会按顺序执行，互不干扰。 -自动加载器始终处于活动状态,在框架执行开始时通过 ``spl_autoload_register()`` 注册。 +自动加载器始终处于激活状态，在框架执行开始时就通过 ``spl_autoload_register()`` 进行了注册。 -.. important:: 你应该始终小心文件名的大小写。许多开发人员在 Windows 或 macOS 上使用不区分大小写的文件系统开发。 - 然而,大多数服务器环境使用区分大小写的文件系统。如果文件名大小写不正确,自动加载程序无法在服务器上找到该文件。 +.. important:: 你应始终注意文件名的大小写。许多开发者在 Windows 或 macOS 的 + 大小写不敏感的文件系统上开发，但大多数服务器环境使用的是大小写敏感的文件系统。 + 如果文件名大小写错误，自动加载器将无法在服务器上找到文件。 ************* 配置 ************* -初始配置在 **app/Config/Autoload.php** 中完成。该文件包含两个主要数组:一个用于类映射,一个用于 PSR-4 兼容命名空间。 +初始配置在 **app/Config/Autoload.php** 文件中完成。该文件包含两个主要数组： +一个用于类映射（classmap），另一个用于 PSR-4 兼容的命名空间。 .. _autoloader-namespaces: 命名空间 ========== -组织类的推荐方法是为应用程序文件创建一个或多个命名空间。 +组织类文件的推荐方法是为你的应用程序文件创建一个或多个命名空间。 -配置文件中的 ``$psr4`` 数组允许你将命名空间映射到可以找到这些类的目录: +配置文件中的 ``$psr4`` 数组允许你将命名空间映射到类文件所在目录： .. literalinclude:: autoloader/001.php -每行的键是命名空间本身。这个不需要尾部反斜杠。 -值是可以找到类的目录位置。 +每一行的键是命名空间本身，不需要末尾的反斜杠。 +值是类文件所在目录的路径。 -默认情况下，命名空间 ``App`` 位于 **app** 目录中，命名空间 ``Config`` 位于 **app/Config** 目录中。 +默认情况下，``App`` 命名空间位于 **app** 目录， +``Config`` 命名空间位于 **app/Config** 目录。 -如果你在这些位置根据 `PSR-4`_ 创建类文件，自动加载器将自动加载它们。 +如果按照 `PSR-4`_ 规范在指定位置创建类文件，自动加载器会自动加载它们。 .. _confirming-namespaces: 确认命名空间 ===================== -你可以使用 ``spark namespaces`` 命令检查命名空间配置: +你可以通过 ``spark namespaces`` 命令检查命名空间配置： .. code-block:: console @@ -65,24 +73,29 @@ CodeIgniter 提供了一个非常灵活的自动加载器，只需进行很少 应用程序命名空间 ===================== -默认情况下,应用程序目录被映射到 ``App`` 命名空间。你必须为应用程序目录中的控制器、库或模型添加命名空间,它们将在 ``App`` 命名空间下被找到。 +默认情况下，应用程序目录对应 ``App`` 命名空间。你必须为应用程序目录中的控制器、 +库或模型指定命名空间，它们将位于 ``App`` 命名空间下。 Config 命名空间 ---------------- -配置文件位于 ``Config`` 命名空间中，而不是你可能预期的 ``App\Config`` 中。这使得核心系统文件即使在应用命名空间发生变化时也能始终找到它们。 +配置文件位于 ``Config`` 命名空间，而不是你可能预期的 ``App\Config``。 +这使得核心系统文件总能找到它们，即使应用命名空间发生了改变。 -.. note:: 自 v4.5.3 appstarter 版本起，``Config\\`` 命名空间已被添加到 **composer.json** 的 ``autoload.psr-4`` 中。 +.. note:: 自 v4.5.3 版本的 appstarter 起，已将 ``Config\\`` 命名空间添加到 + **composer.json** 的 ``autoload.psr-4`` 中。 -更改应用命名空间 +更改 App 命名空间 ---------------------- -你可以通过编辑 **app/Config/Constants.php** 文件并在 ``APP_NAMESPACE`` 设置下设置新的命名空间值来更改此命名空间: +你可以通过编辑 **app/Config/Constants.php** 文件，在 ``APP_NAMESPACE`` 设置下 +修改新的命名空间值来更改此命名空间： .. literalinclude:: autoloader/002.php :lines: 2- -如果你使用 Composer 自动加载器，你还需要在 **composer.json** 中更改 ``App`` 命名空间，然后运行 ``composer dump-autoload``。 +如果你使用 Composer 自动加载器，还需要修改 **composer.json** 中的 ``App`` 命名空间， +并运行 ``composer dump-autoload``。 .. code-block:: text @@ -90,42 +103,46 @@ Config 命名空间 ... "autoload": { "psr-4": { - "App\\": "app/" <-- Change + "App\\": "app/" <-- 修改此处 }, ... }, ... } -.. note:: 自 v4.5.0 appstarter 起，``App\\`` 命名空间已被添加到 **composer.json** 的 ``autoload.psr-4`` 中。如果你的 **composer.json** 中没有此项，添加它可能会提升你应用的自动加载性能。 +.. note:: 自 v4.5.0 版本的 appstarter 起，已将 ``App\\`` 命名空间添加到 + **composer.json** 的 ``autoload.psr-4`` 中。如果你的 **composer.json** 没有 + 包含此项，添加它可能会提升应用程序的自动加载性能。 -你需要修改引用当前命名空间的所有现有文件。 +你将需要修改任何引用当前命名空间的现有文件。 类映射 ======== -CodeIgniter 通过不通过文件系统进行额外的 ``is_file()`` 调用来获取系统最后的性能,广泛使用类映射。你可以使用类映射链接到未使用命名空间的第三方库: - -如果你使用的第三方库不是 Composer 包且没有命名空间，你可以使用类映射（classmap）来加载这些类： +如果你使用非 Composer 包且未命名空间化的第三方库， +可以使用类映射来加载这些类： .. literalinclude:: autoloader/003.php -每行的键是你要定位的类的名称。值是定位它的路径。 +每一行的键是你想定位的类名，值是该类的路径。 **************** Composer 支持 **************** -默认情况下会自动初始化 Composer 支持。 +Composer 支持默认情况下会自动初始化。 -默认情况下,它会在 ``ROOTPATH . 'vendor/autoload.php'`` 查找 Composer 的自动加载文件。如果由于任何原因需要更改该文件的位置,可以修改 **app/Config/Constants.php** 中定义的值。 +默认情况下，它会在 ``ROOTPATH . 'vendor/autoload.php'`` 处查找 Composer 的自动加载文件。 +如果因任何原因需要更改该文件的位置，可以修改 **app/Config/Constants.php** 中定义的值。 -加载器的优先级 +自动加载器的优先级 ======================= -如果同一个命名空间在 CodeIgniter 和 Composer 中同时定义，Composer 的自动加载器将优先尝试定位文件。 +如果同一个命名空间在 CodeIgniter 和 Composer 中都有定义， +Composer 的自动加载器将优先尝试定位文件。 -.. note:: 在 v4.5.0 之前，如果同一个命名空间在 CodeIgniter 和 Composer 中同时定义，CodeIgniter 的自动加载器会优先尝试定位文件。 +.. note:: 在 v4.5.0 之前，如果同一个命名空间在 CodeIgniter 和 Composer 中都有定义， + CodeIgniter 的自动加载器会优先尝试定位文件。 .. _file-locator-caching: @@ -135,26 +152,30 @@ FileLocator 缓存 .. versionadded:: 4.5.0 -**FileLocator** 负责查找文件或从文件中获取类名，这无法通过 PHP 自动加载来实现。 +**FileLocator** 负责查找文件或从文件中获取类名， +这是 PHP 自动加载无法实现的功能。 -为了提高其性能，FileLocator 缓存已经被实现。 +为了提高其性能，已实现 FileLocator 缓存。 工作原理 ============ -- 在析构时，如果缓存数据已更新，则将 FileLocator 找到的所有数据保存到缓存文件中。 -- 如果有缓存数据可用，则在实例化时恢复缓存数据。 +- 如果缓存数据已更新，在析构时将 FileLocator 找到的所有数据保存到缓存文件中。 + +- 实例化时，如果缓存数据可用，则恢复缓存数据。 -缓存数据会永久使用。 +缓存数据将永久使用。 如何删除缓存数据 ========================= -一旦存储，缓存数据将永不过期。 +一旦存储，缓存数据永不失效。 -因此，如果你添加或删除文件，或者更改现有文件路径或命名空间，旧的缓存数据将被返回，你的应用可能无法正常工作。 +因此，如果你添加或删除了文件，或更改了现有文件路径或命名空间， +旧的缓存数据将被返回，导致应用程序无法正常工作。 -在这种情况下，你必须手动删除缓存文件。如果你通过 Composer 添加了 CodeIgniter 包，你也需要删除缓存文件。 +在这种情况下，你必须手动删除缓存文件。如果你通过 Composer 添加了 CodeIgniter 包， +也需要删除缓存文件。 你可以使用 ``spark cache:clear`` 命令： @@ -174,8 +195,8 @@ FileLocator 缓存 public bool $locatorCacheEnabled = true; -或者你可以使用 ``spark optimize`` 命令来启用它。 +或者你可以使用 ``spark optimize`` 命令来启用。 .. note:: - 此属性无法通过 - :ref:`环境变量 ` 重写。 + 此属性不能被 + :ref:`环境变量 ` 覆盖。 diff --git a/source/concepts/factories.rst b/source/concepts/factories.rst index 881b8d8ed..da6c9a065 100644 --- a/source/concepts/factories.rst +++ b/source/concepts/factories.rst @@ -4,33 +4,33 @@ .. contents:: :local: - :depth: 2 + :depth: 3 简介 ************ -什么是工厂? +什么是工厂？ =================== -与 :doc:`./services` 一样, **工厂** 是自动加载的扩展,可以帮助保持代码简洁且高效,而不需要在类之间传递对象实例。 +与 :doc:`./services` 类似，**工厂** 是自动加载功能的扩展，它能帮助你的代码保持简洁高效，而无需在类之间传递对象实例。 -工厂在以下几点上类似于 CodeIgniter 3 的 ``$this->load``: +工厂在以下方面与 CodeIgniter 3 的 ``$this->load`` 类似： - 加载一个类 -- 共享加载的类实例 +- 共享已加载的类实例 -简单来说,工厂提供了一种常见的方式来创建类实例并从任何地方访问它。这是一种很好的方法来重用对象状态并减少在整个应用程序中保留多个实例加载的内存负载。 +简单来说，工厂提供了一种通用的方式来创建类实例，并能从任何地方访问它。这是一种重用对象状态，减少应用程序中多个实例加载所造成的内存开销的好方法。 -任何类都可以通过工厂加载,但最好的例子是那些用于处理或传输公共数据的类。框架本身在内部使用工厂,例如,使用 ``Config`` 类时确保加载正确的配置。 +任何类都可以通过工厂加载，但最佳实践是那些用于处理或传输公共数据的类。框架本身也在内部使用工厂，例如，在使用 ``Config`` 类时确保加载正确的配置。 与服务的区别 ========================= -工厂需要一个具体的类名来实例化,并且没有创建实例的代码。 +工厂需要一个具体的类名来实例化，并且没有创建实例的代码。 -因此,工厂不适合创建一个需要许多依赖项的复杂实例,并且你无法更改要返回的实例的类。 +因此，工厂不适合创建需要许多依赖项的复杂实例，并且你无法更改要返回的实例的类。 -另一方面,服务具有创建实例的代码,所以它可以创建一个需要其他服务或类实例的复杂实例。获取服务时,服务需要一个服务名称,而不是一个类名,所以可以在不更改客户端代码的情况下更改返回的实例。 +另一方面，服务有创建实例的代码，因此它可以创建需要其他服务或类实例的复杂实例。当你获取一个服务时，服务需要的是服务名称，而不是类名，因此返回的实例可以在不更改客户端代码的情况下进行更改。 .. _factories-loading-class: @@ -40,34 +40,34 @@ 加载一个类 =============== -以 **模型** 为例。你可以通过使用 Factories 类的魔术静态方法 ``Factories::models()`` 访问特定于模型的工厂。 +以 **模型** 为例。你可以通过使用 Factories 类的魔术静态方法 ``Factories::models()`` 来访问特定于模型的工厂。 -静态方法名为 *component*。 +静态方法名称被称为 *组件*。 .. _factories-passing-classname-without-namespace: -不带命名空间的类名 +不带命名空间传递类名 ----------------------------------- -如果你传递一个不带命名空间的类名，Factories 首先会在 ``App`` 命名空间中搜索与魔术静态方法名对应的路径。``Factories::models()`` 会搜索 **app/Models** 目录。 +如果你传递一个不带命名空间的类名，工厂会首先在 ``App`` 命名空间中搜索与魔术静态方法名称对应的路径。``Factories::models()`` 会搜索 **app/Models** 目录。 传递短类名 ^^^^^^^^^^^^^^^^^^^^^^^ -在下面的代码中，如果你有 ``App\Models\UserModel``，将返回该实例： +在以下代码中，如果你有 ``App\Models\UserModel``，实例将被返回： .. literalinclude:: factories/001.php -如果没有 ``App\Models\UserModel``，它会在所有命名空间中搜索 ``Models\UserModel``。 +如果你没有 ``App\Models\UserModel``，它会在所有命名空间中搜索 ``Models\UserModel``。 -下次你在代码中的任何地方请求相同的类时，Factories 将确保你获得之前的实例： +下次你在代码的任何地方请求同一个类时，工厂都会确保你得到与之前相同的实例： .. literalinclude:: factories/003.php -传递带有子目录的短类名 +传递带子目录的短类名 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -如果要加载子目录中的类，可以使用 ``/`` 作为分隔符。如果存在，以下代码将加载 **app/Libraries/Sub/SubLib.php**： +如果你想加载子目录中的类，可以使用 ``/`` 作为分隔符。如果存在，以下代码将加载 **app/Libraries/Sub/SubLib.php**： .. literalinclude:: factories/013.php :lines: 2- @@ -75,23 +75,26 @@ .. _factories-passing-fully-qualified-classname: 传递完全限定类名 --------------------------------- +--------------------------------- -你还可以请求一个完全限定的类名： +你也可以请求一个完全限定的类名： .. literalinclude:: factories/002.php :lines: 2- 如果存在，它将返回 ``Blog\Models\UserModel`` 的实例。 -.. note:: 在 v4.4.0 之前，当你请求一个完全限定的类名时，如果只有 ``Blog\Models\UserModel``，将返回该实例。但是，如果同时存在 ``App\Models\UserModel`` 和 ``Blog\Models\UserModel``，将返回 ``App\Models\UserModel`` 的实例。 +.. note:: 在 v4.4.0 之前，当你请求一个完全限定的类名时， + 如果你只有 ``Blog\Models\UserModel``，实例将被返回。 + 但如果你同时有 ``App\Models\UserModel`` 和 ``Blog\Models\UserModel``， + 则会返回 ``App\Models\UserModel`` 的实例。 - 如果你想获取 ``Blog\Models\UserModel``，你需要禁用选项 ``preferApp``： + 如果你想获取 ``Blog\Models\UserModel``，需要禁用选项 ``preferApp``： .. literalinclude:: factories/010.php :lines: 2- -便利函数 +便捷函数 ********************* 为工厂提供了两个快捷函数。这些函数始终可用。 @@ -101,14 +104,14 @@ config() ======== -第一个是 :php:func:`config()`,它返回一个新的 Config 类实例。唯一必需的参数是类名称: +第一个是 :php:func:`config()`，它返回一个 Config 类的新实例。唯一需要的参数是类名： .. literalinclude:: factories/008.php model() ======= -第二个函数 :php:func:`model()` 返回一个新的模型类实例。唯一必需的参数是类名称: +第二个函数 :php:func:`model()` 返回一个 Model 类的新实例。唯一需要的参数是类名： .. literalinclude:: factories/009.php @@ -119,14 +122,14 @@ model() .. versionadded:: 4.4.0 -你可以使用 ``Factories::define()`` 方法定义在加载类之前要加载的类名： +你可以使用 ``Factories::define()`` 方法在加载类之前定义要加载的类名： .. literalinclude:: factories/014.php :lines: 2- -第一个参数是组件。第二个参数是类别名（Factories 魔术静态方法的第一个参数），第三个参数是要加载的真实完全限定类名。 +第一个参数是组件。第二个参数是类别名（工厂魔术静态方法的第一个参数），第三个参数是将要加载的真实完全限定类名。 -之后，如果使用 Factories 加载 ``Myth\Auth\Models\UserModel``，将返回 ``App\Models\UserModel`` 的实例： +之后，如果你用工厂加载 ``Myth\Auth\Models\UserModel``，将返回 ``App\Models\UserModel`` 的实例： .. literalinclude:: factories/015.php :lines: 2- @@ -134,75 +137,69 @@ model() 工厂参数 ****************** -``Factories`` 的第二个参数是一个选项值数组(如下所述)。 -这些指令将覆盖为每个组件配置的默认选项。 +``Factories`` 将一个选项值数组（如下所述）作为第二个参数。这些指令将覆盖为每个组件配置的默认选项。 -同时传递的任何更多参数将转发到类构造函数,使你可以即时配置类实例。例如,假设你的应用使用单独的数据库进行身份验证,并且你希望确保尝试访问用户记录的任何尝试都通过该连接: +同时传递的任何其他参数都将被转发到类构造函数，从而可以轻松地动态配置你的类实例。例如，假设你的应用使用单独的数据库进行身份验证，并且你希望确保任何访问用户记录的尝试都通过该连接进行： .. literalinclude:: factories/004.php -现在从 ``Factories`` 加载的 ``UserModel`` 每次实际上都会返回使用备用数据库连接的类实例。 +现在，每次从 ``Factories`` 加载 ``UserModel`` 时，实际上返回的都是使用备用数据库连接的类实例。 .. _factories-options: 工厂选项 ***************** -默认行为可能不适用于每个组件。例如,假设你的组件名称及其路径不匹配,或者你需要将实例限制为某种类型的类。 -每个组件都接受一组选项来指导发现和实例化。 +默认行为可能并不适用于每个组件。例如，如果你的组件名称与其路径不匹配，或者你需要将实例限制为某种特定类。每个组件都有一组选项来指导发现和实例化过程。 -========== ============== ======================================================================= =================================================== -键 类型 描述 默认值 -========== ============== ======================================================================= =================================================== -component string 或 null 组件名称(如果与静态方法不同)。这可以用于将一个组件别名到另一个。 ``null`` (默认为组件名称) -path string 或 null 命名空间/文件夹内要查找类的相对路径。 ``null`` (默认为组件名称,但将首字母大写) -instanceOf string 或 null 要匹配返回实例上的必需类名称。 ``null`` (无过滤) -getShared boolean 是否返回类的共享实例或者加载一个新实例。 ``true`` -preferApp boolean 是否优先使用 App 命名空间中具有相同基本名称的类而不是其他明确的类请求。 ``true`` -========== ============== ======================================================================= =================================================== +========== ============== ==================================================================== =========================================== +Key 类型 描述 默认值 +========== ============== ==================================================================== =========================================== +component string 或 null 组件的名称（如果与静态方法不同）。可用于将一个组件别名为另一个组件。 ``null`` (默认为组件名称) +path string 或 null 在命名空间/文件夹内用于查找类的相对路径。 ``null`` (默认为组件名称，但首字母大写) +instanceOf string 或 null 匹配返回实例的类名。 ``null`` (无过滤) +getShared boolean 是否返回类的共享实例或加载一个新实例。 ``true`` +preferApp boolean App 命名空间中具有相同 basename 的类是否覆盖其他显式类请求。 ``true`` +========== ============== ==================================================================== =========================================== -.. note:: 自 v4.4.0 起，``preferApp`` 仅在你请求 :ref:`不带命名空间的类名 ` 时起作用。 +.. note:: 自 v4.4.0 起，``preferApp`` 仅在你请求 + :ref:`不带命名空间的类名 ` 时才有效。 工厂行为 ****************** -可以通过三种方式(按优先级降序排列)应用选项: +选项可以通过以下三种方式之一应用（按优先级升序列出）： -* 配置类 ``Config\Factory``,其中包含与组件名称匹配的属性。 +* 一个配置类 ``Config\Factory``，其属性名与组件名称匹配。 * 静态方法 ``Factories::setOptions()``。 -* 在调用时直接传递参数。 +* 在调用时直接通过参数传递选项。 配置 ============== -要设置默认组件选项,请在 **app/Config/Factory.php** 中创建一个新的 Config 文件, -以数组属性的形式提供与组件名称匹配的选项。 +要设置默认组件选项，请在 **app/Config/Factory.php** 创建一个新的配置文件，该文件将选项作为与组件名称匹配的数组属性提供。 -示例:过滤器工厂 +示例：过滤器工厂 -------------------------- -例如,如果你要通过工厂创建 **过滤器**,组件名称将是 ``filters``。 -如果你想确保每个过滤器都是实现了 CodeIgniter 的 ``FilterInterface`` 的类的实例, -你的 **app/Config/Factory.php** 文件可能如下所示: +例如，如果你想通过工厂创建 **过滤器**，组件名称将是 ``filters``。如果你希望确保每个过滤器都是实现了 CodeIgniter 的 ``FilterInterface`` 的类的实例，你的 **app/Config/Factory.php** 文件可能如下所示： .. literalinclude:: factories/005.php -现在你可以用类似 ``Factories::filters('SomeFilter')`` 的代码创建过滤器, -并且返回的实例一定是 CodeIgniter 的过滤器。 +现在你可以使用 ``Factories::filters('SomeFilter')`` 这样的代码来创建一个过滤器，返回的实例必定是 CodeIgniter 的过滤器。 -这将防止第三方模块意外地在其命名空间中具有不相关的 ``Filters`` 路径而发生冲突。 +这可以防止与恰好在其命名空间中有无关 ``Filters`` 路径的第三方模块发生冲突。 -示例:库工厂 +示例：库工厂 -------------------------- -如果你想用 ``Factories::library('SomeLib')`` 在 **app/Libraries** 目录中加载库类, -路径 `Libraries` 与默认路径 `Library` 不同。 +如果你想使用 ``Factories::library('SomeLib')`` 在 **app/Libraries** 目录中加载你的库类，路径 `Libraries` 与默认路径 `Library` 不同。 -在这种情况下,你的 **app/Config/Factory.php** 文件如下所示: +在这种情况下，你的 **app/Config/Factory.php** 文件将如下所示： .. literalinclude:: factories/011.php -现在你可以使用 ``Factories::library()`` 方法加载你的库: +现在你可以使用 ``Factories::library()`` 方法来加载你的库： .. literalinclude:: factories/012.php :lines: 2- @@ -210,16 +207,16 @@ preferApp boolean 是否优先使用 App 命名空间中具有相同基 setOptions 方法 ================= -``Factories`` 类有一个静态方法允许运行时选项配置:只需使用 ``setOptions()`` 方法提供所需的选项数组,它们将与默认值合并并存储以备下次调用: +``Factories`` 类有一个静态方法允许运行时配置选项：只需使用 ``setOptions()`` 方法提供所需的选项数组，它们将与默认值合并并存储以供下一次调用使用： .. literalinclude:: factories/006.php 参数选项 ================= -``Factories`` 的魔术静态调用以选项值数组作为第二个参数。这些指令将覆盖为每个组件配置的存储选项,并可在调用时用于获得你所需的内容。输入应为以每个覆盖值为键的选项名称数组。 +``Factories`` 的魔术静态调用将一个选项值数组作为第二个参数。这些指令将覆盖为每个组件配置的存储选项，可以在调用时使用以获取你确切需要的内容。输入应该是一个数组，其选项名称作为键，每个覆盖值作为值。 -例如,默认情况下 ``Factories`` 假设你希望定位组件的共享实例。通过向魔术静态调用添加第二个参数,你可以控制该单个调用是否返回新实例还是共享实例: +例如，默认情况下 ``Factories`` 假定你想要定位组件的共享实例。通过向魔术静态调用添加第二个参数，你可以控制该单次调用是返回新实例还是共享实例： .. literalinclude:: factories/007.php :lines: 2- @@ -231,34 +228,34 @@ setOptions 方法 .. versionadded:: 4.4.0 -.. important:: 除非你已经仔细阅读了这一节并理解了这个功能是如何工作的，否则不要使用这个功能。否则，你的应用程序将无法正常工作。 +.. important:: 除非你已仔细阅读本节并理解此功能的工作原理，否则不要使用此功能。否则，你的应用程序将无法正常运行。 -为了提高性能，实现了配置缓存。 +为了提高性能，已实现配置缓存。 -先决条件 +前提条件 ============ -.. important:: 当不满足先决条件时使用此功能将阻止 CodeIgniter 正常运行。在这种情况下不要使用此功能。 +.. important:: 在不满足前提条件的情况下使用此功能将阻止 CodeIgniter 正常运行。在这种情况下不要使用此功能。 -- 要使用此功能，Factories 中实例化的所有 Config 对象的属性在实例化后不能被修改。换句话说，Config 类必须是不可变或只读的类。 +- 要使用此功能，工厂中实例化的所有 Config 对象的属性在实例化后不得被修改。换句话说，Config 类必须是不可变的或只读的类。 - 默认情况下，每个被缓存的 Config 类必须实现 ``__set_state()`` 方法。 工作原理 ============ -.. important:: 一旦缓存，配置值在缓存被删除之前永远不会改变，即使配置文件或 **.env** 发生了变化。 +.. important:: 一旦缓存，配置值将永远不会改变，直到缓存被删除，即使配置文件或 **.env** 文件被更改也是如此。 -- 如果 Factories 中的 Config 实例的状态发生变化，则在关闭之前将所有 Config 实例保存到缓存文件中。 -- 如果有缓存可用，则在 CodeIgniter 初始化之前恢复缓存的 Config 实例。 +- 在关闭前，如果工厂中的 Config 实例状态发生变化，则将所有 Config 实例保存到缓存文件中。 +- 如果存在缓存，则在 CodeIgniter 初始化前恢复缓存的 Config 实例。 -简而言之，Factories 持有的所有 Config 实例在关闭之前都会被缓存，并且缓存的实例将永久使用。 +简而言之，工厂持有的所有 Config 实例在关闭前立即被缓存，且缓存的实例将永久使用。 如何更新配置值 =========================== -一旦存储，缓存的版本将永不过期。更改现有的 Config 文件（或更改其环境变量）不会更新缓存或 Config 值。 +一旦存储，缓存的版本永远不会过期。更改现有的 Config 文件（或为其更改环境变量）不会更新缓存或配置值。 -因此，如果要更新 Config 值，请更新 Config 文件或其环境变量，并且必须手动删除缓存文件。 +因此，如果你想更新配置值，请更新 Config 文件或环境变量，并且必须手动删除缓存文件。 你可以使用 ``spark cache:clear`` 命令： @@ -280,14 +277,14 @@ setOptions 方法 public bool $configCacheEnabled = true; -或者你可以使用 ``spark optimize`` 命令来启用此功能。 +或者你可以使用 ``spark optimize`` 命令启用它。 .. note:: - 此属性无法通过 - :ref:`环境变量 ` 重写。 + 此属性不能被 + :ref:`环境变量 ` 覆盖。 .. note:: - 在 v4.4.x 中，请在 **public/index.php** 中取消以下代码的注释:: + 在 v4.4.x 中，取消注释 **public/index.php** 中的以下代码:: --- a/public/index.php +++ b/public/index.php diff --git a/source/concepts/goals.rst b/source/concepts/goals.rst index 8837e6669..b82e27667 100644 --- a/source/concepts/goals.rst +++ b/source/concepts/goals.rst @@ -2,14 +2,14 @@ 设计与架构目标 ############################## -CodeIgniter 的目标是在最小化，最轻量级的开发包中得到最大的执行效率、功能和灵活性。 +CodeIgniter 的目标是在最小、最轻量的软件包中实现最高的性能、功能和灵活性。 -为了达到这个目标，我们在开发过程的每一步都致力于基准测试、重构和简化工作，拒绝加入任何对实现目标没有帮助的东西。 +为实现这一目标，我们致力于在开发过程的每一步进行基准测试、重构和简化，拒绝任何不符合既定目标的元素。 -从技术和架构角度看，CodeIgniter 按照下列目标创建： +从技术和架构的角度来看，CodeIgniter 按照以下目标创建： -- **动态实例化。** 在 CodeIgniter 中，组件的导入和函数的执行都是在被请求的时候才执行，而不是全局的。除核心资源外，系统不需要任何其他资源，因此系统默认是非常轻量级的。HTTP 请求所触发的事件以及你设计的控制器和视图将决定哪些资源是需要加载的。 -- **低耦合。** 耦合是指一个系统中组件之间的依赖程度。组件之间的依赖程度越低，系统的重用性和灵活性就越好。我们的目标就是打造一个低耦合的系统。 -- **组件专一性。** 专一性指的是组件对某个目标的专注程度。在 CodeIgniter 中，每一个类和方法都是高度独立的，从而可以最大程度地被复用。 +- **动态实例化。** 在 CodeIgniter 中，组件仅在被请求时才加载，函数也仅在被请求时才执行，而不是全局加载。系统不会对除最小核心资源外可能需要的内容做任何假设，因此系统默认非常轻量。由 HTTP 请求触发的事件，以及你设计的控制器和视图将决定调用哪些内容。 +- **低耦合。** 耦合是指系统组件相互依赖的程度。组件之间相互依赖的程度越低，系统的可重用性和灵活性就越高。我们的目标是建立一个高度低耦合的系统。 +- **组件专一性。** 专一性是指组件对某个目标的专注程度。在 CodeIgniter 中，每个类及其方法都具有高度的独立性，以实现最大的复用性。 -CodeIgniter 是一个动态实例化，高度组件专一性的低耦合系统。它在小巧的基础上力求做到简单、灵活和高性能。 +CodeIgniter 是一个动态实例化，高度组件专一性的低耦合系统。它在小巧的基础上力求做到简洁、灵活和高性能。 diff --git a/source/concepts/http.rst b/source/concepts/http.rst index 817ca9401..50f76a7da 100755 --- a/source/concepts/http.rst +++ b/source/concepts/http.rst @@ -2,43 +2,41 @@ 处理 HTTP 请求 ########################## -为了充分利用 CodeIgniter,你需要对 HTTP 请求和响应的工作原理有基本的了解。由于这是你在开发 Web 应用程序时使用的内容,所以所有想要成功的开发人员都必须了解 HTTP 背后的概念。 +为了充分利用 CodeIgniter，你需要对 HTTP 请求和响应的工作原理有基本的了解。由于在开发 Web 应用程序时，你所处理的正是这些内容，因此对于所有希望取得成功的开发者来说，理解 HTTP 背后的概念是**必须**的。 -本章的第一部分概述了概念。在概念说明清楚之后,我们将讨论在 CodeIgniter 中如何处理请求和响应。 +本章的第一部分将进行概述。在了解基本概念之后，我们将讨论如何在 CodeIgniter 中处理请求和响应。 .. contents:: :local: :depth: 2 -什么是 HTTP? +什么是 HTTP？ ************* -HTTP 简单来说就是一种基于文本的约定,允许两台机器互相通信。当浏览器请求一个页面时,它会问服务器是否可以获取该页面。然后服务器准备好页面,并向请求它的浏览器发送响应。基本上就这么简单。显然,你可以使用一些复杂的功能,但基础真的非常简单。 +HTTP 只是一种基于文本的约定，它允许两台机器相互通信。当浏览器请求一个页面时，它会询问服务器是否可以获取该页面。服务器随后准备页面，并将响应发送回请求它的浏览器。基本上就是这样。显然，其中存在一些你可以利用的复杂性，但基本原理其实相当简单。 -HTTP 是用于描述该交换约定的术语。它代表超文本传输协议(HyperText Transfer Protocol)。你开发 Web 应用程序的目标是始终了解浏览器正在请求什么,并能够做出适当的响应。 +HTTP 是用于描述这种交换约定的术语，其全称为超文本传输协议（HyperText Transfer Protocol）。你在开发 Web 应用时的目标，是始终了解浏览器正在请求什么，并能够做出适当的响应。 请求 =========== -每当客户端(Web 浏览器、智能手机应用等)发出请求时,它都会向服务器发送一小段文本消息并等待响应。 +每当客户端（如 Web 浏览器、智能手机应用等）发出请求时，它都会向服务器发送一条小的文本消息，然后等待响应。 -请求看起来类似这样:: +该请求可能看起来像这样:: GET / HTTP/1.1 Host codeigniter.com Accept: text/html User-Agent: Chrome/46.0.2490.80 -此消息显示了客户端请求所需的所有信息。它告诉请求的方法(GET、POST、DELETE 等)和它支持的 HTTP 版本。 +此消息显示了，了解客户端请求所需的所有信息。它告诉了请求的方法（GET、POST、DELETE 等）以及其支持的 HTTP 版本。 -请求还包括可以包含广泛信息的可选请求头,例如客户端希望以什么语言显示内容,客户端接受的格式类型等等。如果你想查看一下,Wikipedia 有一篇文章列出了 `所有标题字段 `_。 +请求还包含许多可选的请求头，其中可以包含各种信息，例如客户端希望内容以何种语言显示、客户端接受的格式类型等等。如果你想了解更多信息，Wikipedia 上有一篇文章列出了所有 `请求头字段 `_。 响应 ============ -一旦服务器接收到请求,你的应用程序将获取该信息并生成一些输出。服务器将你的输出作为其对客户端的响应的一部分进行打包。这也表示为类似这样的简单文本消息: - -:: +一旦服务器收到请求，你的应用程序就会利用这些信息生成一些输出。服务器会将你的输出打包，作为对客户端响应的一部分。这也被表示为一条简单的文本消息，可能看起来像这样:: HTTP/1.1 200 OK Server: nginx/1.8.0 @@ -49,21 +47,21 @@ HTTP 是用于描述该交换约定的术语。它代表超文本传输协议(Hy . . . -响应告诉客户端它使用的 HTTP 规范版本,可能最重要的是状态码(200)。状态码是对客户端具有非常特定含义的标准化代码之一。这可以告诉它请求成功(200),或者页面未找到(404)。如果你想查看完整的 HTTP 状态码列表,请访问 IANA 的 `完整 HTTP 状态码列表 `_。 +响应会告诉客户端它正在使用哪个版本的 HTTP 规范，而其中最重要的是状态码（200）。状态码是经过标准化的一系列代码，对客户端具有特定的含义。它可以告诉客户端请求成功了（200），或页面未找到（404）。你可以前往 IANA 查看 `完整的 HTTP 状态码列表 `_。 -使用请求和响应 +处理请求和响应 *********************************** -虽然 PHP 提供了与请求和响应标头交互的方式,但 CodeIgniter 和大多数框架一样,将它们抽象化,以便为它们提供一致、简单的接口。:doc:`IncomingRequest 类 ` 是 HTTP 请求的面向对象表示。它提供了你需要的一切: +虽然 PHP 提供了与请求和响应头交互的方式，但像大多数框架一样，CodeIgniter 对它们进行了抽象，为你提供了一个一致且简单的接口。:doc:`IncomingRequest 类 ` 是 HTTP 请求的面向对象表示。它为你提供了所需的一切： .. literalinclude:: http/001.php -请求类会默默地为你完成很多工作,你永远不需要担心。``isAJAX()`` 和 ``isSecure()`` 方法检查了几种不同的方法来确定正确的答案。 +请求类在后台为你做了大量工作，你无需为此担心。``isAJAX()`` 和 ``isSecure()`` 方法会检查多种不同的方式来确定正确的答案。 -.. note:: ``isAJAX()`` 方法依赖于 ``X-Requested-With`` 标头,在某些情况下,这在通过 JavaScript 发出的 XHR 请求中默认不会发送(即 fetch)。请参阅 :doc:`AJAX 请求 ` 部分了解如何避免此问题。 +.. note:: ``isAJAX()`` 方法依赖于 ``X-Requested-With`` 头，但在某些情况下，通过 JavaScript 发起的 XHR 请求（例如 fetch）默认不会发送该头。请参阅 :doc:`AJAX 请求 ` 章节，了解如何避免此问题。 -CodeIgniter 还提供了一个 :doc:`Response 类 `,它是 HTTP 响应的面向对象表示。这为你构建对客户端的响应提供了一个简单而强大的方式: +CodeIgniter 还提供了一个 :doc:`Response 类 `，它是 HTTP 响应的面向对象表示。这为你提供了一种简单而强大的方式来构建对客户端的响应： .. literalinclude:: http/002.php -此外,Response 类允许你使用 HTTP 缓存层进行工作以获得最佳性能。 +此外，Response 类还允许你操作 HTTP 缓存层，以获得最佳性能。 diff --git a/source/concepts/mvc.rst b/source/concepts/mvc.rst index e5cdac226..18f153eb4 100755 --- a/source/concepts/mvc.rst +++ b/source/concepts/mvc.rst @@ -7,22 +7,22 @@ :depth: 2 ************ -什么是 MVC? +什么是 MVC？ ************ -无论何时创建应用程序,都必须找到一种组织代码的方式,以便轻松定位正确的文件并简化维护。与大多数 Web 框架一样,CodeIgniter 使用模型、视图、控制器(MVC)模式来组织文件。这将数据、表示和应用程序流保持为单独的部分。 +创建应用程序时，必须找到一种组织代码的方法，以便于定位正确的文件并简化维护。与大多数 Web 框架一样，CodeIgniter 使用模型、视图、控制器（MVC）模式来组织文件。这将应用程序中的数据、展示和流程作为独立的部分分开。 -应该指出,对于每个元素的确切角色有许多不同看法,但本文档描述了我们的看法。如果你有不同的看法,你可以根据需要自由修改如何使用每个部分。 +需要注意的是，对于每个元素的确切角色存在许多不同的观点，但本文档描述了我们对此的理解。如果你有不同的看法，可以自由地根据需要修改每个组件的使用方式。 -**模型** 管理应用程序的数据,并帮助执行应用程序可能需要的任何特殊业务规则。 +**模型** 管理应用程序的数据，并帮助强制执行应用程序可能需要的任何特殊业务规则。 -**视图** 是简单的文件,几乎没有逻辑,用于向用户显示信息。 +**视图** 是简单的文件，几乎没有逻辑，用于向用户显示信息。 -**控制器** 充当胶水代码,在视图(或看到它的用户)和数据存储之间来回组织数据。 +**控制器** 充当胶水代码，在视图（或查看它的用户）和数据存储之间来回传递数据。 -最基本意义上,控制器和模型只是有特定任务的类。显然,它们不是你可以使用的唯一类型的类,但它们组成了此框架设计如何使用的核心。它们甚至在 **app** 目录中有指定的目录用于存储,尽管只要命名空间正确,你可以根据需要将它们存储在任何地方。我们将在下面更详细地讨论这一点。 +最基本地，控制器和模型只是具有特定职责的类。显然，它们并不是你唯一可以使用的类类型，但它们构成了该框架设计使用方式的核心。它们甚至在 **app** 目录中有指定的存储目录，尽管只要正确命名空间，你可以将它们存储在任何你想要的位置。我们将在下面更详细地讨论这一点。 -让我们更仔细地看看这三个主要组件中的每个组件。 +让我们更仔细地看看这三个主要组件。 ************** 组件 @@ -31,34 +31,34 @@ 视图 ===== -视图是最简单的文件,通常是包含很少 PHP 的 HTML。PHP 应该非常简单,通常只是显示变量的内容,或者循环一些项目并在表中显示它们的信息。 +视图是最简单的文件，通常是 HTML 并带有少量的 PHP。PHP 代码应该非常简单，通常只是显示变量的内容，或循环遍历一些项目并在表格中显示它们的信息。 -视图从控制器获取要显示的数据,控制器将其作为变量传递给视图,然后可以用简单的 ``echo`` 调用显示。你也可以在视图中显示其他视图,这样就可以很容易地在每个页面显示通用标头或页脚。 +视图从控制器获取要显示的数据，控制器将其作为变量传递给视图，可以通过简单的 ``echo`` 调用显示。你也可以在视图中显示其他视图，这样在每一页中显示一个通用的页头或页脚就变得非常简单。 -视图通常存储在 **app/Views** 中,但是如果不以某种方式组织,很快就会变得难以管理。CodeIgniter 不强制任何类型的组织,但是一个好的经验法则是在 **Views** 目录中为每个控制器创建一个新目录。然后,用方法名称命名视图。这样以后就很容易找到它们。例如,用户个人资料可能在名为 ``User`` 的控制器以及名为 ``profile`` 的方法中显示。你可以将此方法的视图文件存储在 **app/Views/user/profile.php** 中。 +视图通常存储在 **app/Views** 目录中，但如果组织不当，可能会很快变得难以管理。CodeIgniter 不强制要求任何类型的组织方式，但一个好的经验法则是为每个控制器在 **Views** 目录中创建一个新目录。然后，按方法名称命名视图。这样以后查找起来会非常容易。例如，用户的个人资料可能在名为 ``User`` 的控制器和名为 ``profile`` 的方法中显示。你可以将此方法的视图文件存储在 **app/Views/user/profile.php** 中。 -这种组织方式作为一种基本习惯非常有效。有时候你可能需要以不同的方式组织。这没关系。只要 CodeIgniter 可以找到文件,就可以显示它。 +这种类型的组织方式作为基础习惯非常有效。有时你可能需要以不同的方式组织。这没有问题。只要 CodeIgniter 能找到文件，它就能显示它。 -:doc:`了解更多关于视图的信息 ` +:doc:`了解有关视图的更多信息 ` 模型 ====== -模型的任务是为应用程序维护一种数据类型。这可能是用户、博客文章、事务等。在这种情况下,模型的工作有两部分:在从数据库中获取或放入数据库时,对数据执行业务规则;以及从数据库保存和检索数据。 +模型的工作是维护应用程序中单一类型的数据。这可能是用户、博客文章、交易等。在这种情况下，模型的工作有两个部分：当数据从数据库中提取或存入时，强制执行业务规则；以及处理数据从数据库中的实际保存和检索。 -对许多开发人员来说,确定执行了哪些业务规则会造成困惑。这简单意味着任何对数据的限制或要求都由模型处理。这可能包括在保存以满足公司标准之前规范化原始数据,或者以某种方式格式化列,然后才将其交给控制器。通过在模型中保留这些业务要求,你不会在多个控制器中重复代码,并且不会意外地遗漏更新某个区域。 +对于许多开发者来说，困惑在于确定要强制执行哪些业务规则。这仅仅意味着数据上的任何限制或要求都由模型处理。这可能包括在保存之前将原始数据规范化以满足公司标准，或在将列传递给控制器之前以特定方式格式化。通过将这些业务需求保留在模型中，你不会在多个控制器中重复代码，也不会意外遗漏更新某个区域。 -模型通常存储在 **app/Models** 中,尽管它们可以使用命名空间按需要进行分组。 +模型通常存储在 **app/Models** 目录中，尽管它们可以使用命名空间按你需要的方式进行分组。 -:doc:`了解更多关于模型的信息 ` +:doc:`了解有关模型的更多信息 ` 控制器 =========== -控制器有几个不同的角色。最明显的一点是它们从用户那里接收输入,然后确定对其进行何种处理。这通常涉及将数据传递给模型以保存它,或者从模型请求数据,然后将其传递给视图以显示。如果需要,这还包括加载其他实用程序类来处理模型范围之外的专门任务。 +控制器有几个不同的角色。最明显的一个是接收用户的输入，然后确定如何处理它。这通常涉及将数据传递给模型以保存，或从模型请求数据，然后将其传递给视图以进行显示。如果需要，这也包括加载其他实用类，以处理模型职责范围之外的专门任务。 -控制器的另一个职责是处理与 HTTP 请求相关的所有内容 - 重定向、身份验证、Web 安全、编码等。简而言之,控制器是确保人们被允许访问那里,并以他们可以使用的格式获取所需数据的地方。 +控制器的另一个职责是处理与 HTTP 请求相关的所有内容——重定向、身份验证、网络安全、编码等。简而言之，控制器是确保人们被允许访问，并以他们可以使用的格式获取所需数据的地方。 -控制器通常存储在 **app/Controllers** 中,尽管它们可以使用命名空间按需要分组。 +控制器通常存储在 **app/Controllers** 目录中，尽管它们可以使用命名空间按你需要的方式进行分组。 -:doc:`了解更多关于控制器的信息 ` +:doc:`了解有关控制器的更多信息 ` diff --git a/source/concepts/security.rst b/source/concepts/security.rst index 66190efb7..870306ca4 100755 --- a/source/concepts/security.rst +++ b/source/concepts/security.rst @@ -2,617 +2,738 @@ 安全指南 ################### -我们非常重视安全。 -CodeIgniter 包含许多功能和技术，以便强制执行良好的安全实践，或者让你轻松地做到这一点。 +我们非常重视安全性。 +CodeIgniter 采用了许多功能和技术来强制执行良好的安全实践，或让你能够轻松实现。 -我们尊重 `开放 Web 应用安全项目 (OWASP) `_ 并尽可能地遵循他们的建议。 +我们尊重 `开放 Web 应用程序安全项目 (OWASP) `_，并尽可能遵循其建议。 -以下内容来自于 -`OWASP Top Ten `_ 和 -`OWASP API Security Top 10 `_ -识别出网络应用和 API 的主要漏洞。 -我们为每个漏洞提供一个简短的描述、OWASP 的建议，然后介绍 CodeIgniter 解决这些问题的措施。 +以下内容来自 +`OWASP 十大安全风险 `_ 和 +`OWASP API 安全十大风险 `_， +这些是针对 Web 应用程序和 API 的最高风险漏洞。 +对于每个风险，我们提供简要描述、OWASP 建议以及 CodeIgniter 提供的应对措施。 .. contents:: :local: :depth: 2 -***************** -OWASP Top 10 2021 -***************** +*********************** +OWASP 十大安全风险 2021 +*********************** A01:2021 访问控制失效 ============================== -访问控制执行策略，以确保用户不能在他们预期的权限之外进行操作。失败通常会导致未经授权的信息泄露、修改或销毁所有数据，或执行超出用户限制的业务功能。 +访问控制强制执行策略，确保用户无法超出其预期权限进行操作。失败通常会导致未经授权的信息泄露、 +所有数据的修改或破坏，或在用户权限范围之外执行业务功能。 常见的访问控制漏洞包括： -- 违反最小特权原则或默认拒绝原则，访问应该只授予特定功能、角色或用户，但对任何人开放。 -- 通过修改 URL（参数篡改或强制浏览）、内部应用状态或 HTML 页面，或使用攻击工具修改 API 请求来绕过访问控制检查。 -- 允许通过提供其唯一标识符来查看或编辑他人的帐户（不安全的直接对象引用）。 -- 访问缺少 POST、PUT 和 DELETE 访问控制的 API。 -- 权限提升。作为未登录的用户或作为已登录的用户时作为管理员操作。 -- 元数据操作，例如重放或篡改 JSON Web 令牌 (JWT) 访问控制令牌、或操纵 cookie 或隐藏字段以提升权限或滥用 JWT 失效。 -- CORS 配置错误允许从未经授权/未受信任的起源访问 API。 -- 强制浏览到身份验证页面的未认证用户或标准用户的特权页面。 +- 违反最小权限原则或默认拒绝原则，即访问权限应仅授予特定能力、角色或用户，但实际对任何人都可用。 +- 通过修改 URL（参数篡改或强制浏览）、内部应用程序状态或 HTML 页面，或使用攻击工具修改 API 请求来绕过访问控制检查。 +- 通过提供其唯一标识符，允许查看或编辑他人的账户（不安全的直接对象引用）。 +- 访问 API 时缺少对 POST、PUT 和 DELETE 操作的访问控制。 +- 特权提升。未登录时以用户身份操作，或以普通用户身份登录时以管理员身份操作。 +- 操纵元数据，例如重放或篡改 JSON Web Token (JWT) 访问控制令牌，或操纵 Cookie 或隐藏字段来提升权限，或滥用 JWT 无效化。 +- CORS 配置错误，允许来自未授权/不可信来源的 API 访问。 +- 未认证用户强制浏览到需认证的页面，或普通用户强制浏览到特权页面。 OWASP 建议 --------------------- -访问控制仅在受信任的服务器端代码或无服务器 API 中有效，在这些情况下，攻击者无法修改访问控制检查或元数据。 - -- 除了公共资源外，一律默认拒绝。 -- 实现一次访问控制机制，并在整个应用中重用，包括最小化跨域资源共享 (CORS) 的使用。 -- 模型访问控制应执行记录所有权，而不是接受用户可以创建、读取、更新或删除任何记录的情况。 -- 应通过域模型强制执行独特的应用业务限制要求。 -- 禁用 Web 服务器目录列表，并确保文件元数据（例如 .git）和备用文件不在 Web 根目录中。 -- 记录访问控制失败，在适当时向管理员发出警报（例如，重复失败）。 -- 限制 API 和控制器访问，以最小化自动化攻击工具的危害。 -- 在注销后在服务器上使状态会话标识符失效。无状态 JWT 令牌应该是短命的，以使攻击者的机会之窗最小化。对于更长寿命的 JWT，强烈建议遵循 OAuth 标准撤销访问。 - -CodeIgniter 的保护措施 +访问控制仅在受信任的服务器端代码或无服务器 API 中有效， +攻击者无法修改访问控制检查或元数据。 + +- 除公共资源外，默认拒绝访问。 +- 一次性实现访问控制机制并在整个应用程序中复用， + 包括尽量减少跨域资源共享 (CORS) 的使用。 +- 模型访问控制应强制执行记录所有权，而非接受用户可以创建、读取、更新或删除任何记录。 +- 应通过领域模型强制执行独特的应用业务限制要求。 +- 禁用 Web 服务器目录列表，并确保文件元数据（例如 .git）和 + 备份文件不在 Web 根目录内。 +- 记录访问控制失败，适当时向管理员发出警报（例如，重复失败）。 +- 限制 API 和控制器访问频率，以尽量减少自动化攻击工具造成的危害。 +- 有状态会话标识符应在注销后在服务器端失效。 + 无状态 JWT 令牌应尽可能短暂，以最小化攻击者的机会窗口。对于长期有效的 JWT， + 强烈建议遵循 OAuth 标准来撤销访问。 + +CodeIgniter 应对措施 ---------------------- -- :ref:`Public ` 文件夹，包括外部的应用和系统文件 +- :ref:`Public ` 文件夹，将应用程序和系统置于其外 - :doc:`../libraries/validation` 库 -- :doc:`Security ` 库提供的 - :ref:`CSRF 保护 ` +- :doc:`安全 ` 库提供 :ref:`CSRF 保护 ` - :doc:`../libraries/sessions` 库 -- :doc:`../libraries/throttler` 库用于限速 +- :doc:`../libraries/throttler` 用于限制频率 - :doc:`../libraries/cors` 过滤器 -- 用于记录的 :php:func:`log_message()` 函数 -- 官方认证与授权框架 :ref:`CodeIgniter Shield ` +- :php:func:`log_message()` 函数用于记录日志 +- 官方认证和授权框架 :ref:`CodeIgniter Shield ` - 易于添加第三方认证 -A02:2021 密码学失败 +A02:2021 加密失败 =============================== -首先需要确定传输和静态数据的保护需要。 例如，密码、信用卡号、健康记录、个人信息和商业机密需要额外保护，尤其是如果这些数据受到隐私法律（例如欧盟一般数据保护条例 (GDPR)）或法规（例如金融数据保护，如 PCI 数据安全标准 (PCI DSS)）的约束。在所有此类数据中： - -- 有任何数据以明文传输吗？这涉及到诸如 HTTP, SMTP, FTP 等协议同样使用 TLS 升级如 STARTTLS。外部互联网流量是危险的。验证所有内部流量，例如负载均衡器、Web 服务器或后端系统之间的流量。 -- 是否存在默认使用、弱加密算法或协议，或者旧代码中使用？ -- 是否使用默认加密密钥，生成或重复使用弱加密密钥，或者缺乏适当的密钥管理或轮换？密钥是否已被提交到源代码库？ -- 是否没有强制加密，例如，是否缺少任何 HTTP 头（浏览器）安全指令或头？ -- 服务器证书和信任链是否正确验证？ -- 初始化向量是否被忽略、重复使用，还是未为加密模式生成足够安全的初始化向量？是否在使用不安全的操作模式，例如 ECB 模式？当使用认证加密更为合适时，是否仅使用加密？ -- 在缺乏基于密码的密钥派生函数的情况下，是否正在使用密码作为加密密钥？ -- 随机性是否用于密码学目的，但未设计为满足密码学要求？即使选择了正确的函数，是否需要开发者播种，如果没有，开发者是否覆盖了其内建的强播种功能，使用了缺乏足够熵/不可预测性的种子？ -- 是否使用了如 MD5 或 SHA1 等已废弃的哈希函数，或在需要密码学哈希函数时使用了非密码学哈希函数？ -- 是否正在使用如 PKCS 编号 1 v1.5 等已废弃的密码学填充方法？ -- 是否存在可被利用的密码学错误消息或侧信道信息，例如填充 Oracle 攻击中的形式？ +首要任务是确定传输中和静态数据的保护需求。例如，密码、信用卡号、健康记录、个人 +信息和商业机密需要额外保护，尤其是当这些数据受隐私法（如欧盟《通用数据保护条例》(GDPR)）或法规（如支付卡行业数据安全标准 (PCI DSS)）约束时。对于所有此类数据： + +- 是否有任何数据以明文形式传输？这涉及 HTTP、SMTP、FTP 等协议，也包括使用 STARTTLS 等 TLS 升级。外部互联网流量是危险的。请验证所有内部流量，例如负载均衡器、Web 服务器或后端系统之间的流量。 +- 是否默认或在旧代码中使用了任何旧的或弱的加密算法或协议？ +- 是否在使用默认加密密钥，生成了弱密钥或重复使用密钥，或缺少适当的密钥管理或轮换？加密密钥是否被提交到源代码仓库中？ +- 是否未强制执行加密，例如，是否缺少任何 HTTP 头（浏览器）安全指令或头？ +- 是否正确验证了收到的服务器证书和信任链？ +- 初始化向量是否被忽略、重复使用，或未为加密操作模式生成足够安全？是否使用了不安全的操作模式（如 ECB）？在更适用认证加密时是否使用了加密？ +- 在没有密码派生密钥函数的情况下，是否将密码用作加密密钥？ +- 是否使用了未设计满足加密要求的随机性用于加密目的？即使选择了正确的函数，是否需要由开发人员进行种子填充，如果没有，开发人员是否用熵/不可预测性不足的种子覆盖了其内置的强大种子填充功能？ +- 是否使用了已弃用的哈希函数（如 MD5 或 SHA1），或在需要加密哈希函数时使用了非加密哈希函数？ +- 是否使用了已弃用的加密填充方法（如 PKCS 1 v1.5）？ +- 加密错误消息或侧信道信息是否可被利用，例如以填充预言攻击的形式？ OWASP 建议 --------------------- -至少执行以下操作，并参考相应文档： +至少执行以下操作，并参考相关资料： -- 对由应用程序处理、存储或传输的数据进行分类。根据隐私法、法规要求或业务需求，确定哪些数据是敏感的。 -- 不要不必要地存储敏感数据。尽快丢弃它，或使用符合 PCI DSS 的令牌化或甚至截断。无法保留的数据不能被窃取。 -- 确保所有敏感数据在静态时都加密。 -- 确保使用最新的强标准算法、协议和密钥；使用适当的密钥管理。 -- 用安全协议（如具有前向安全性 (FS) 密码的 TLS、服务器优先的密码序列和安全参数）加密所有传输中的数据。使用诸如 HTTP 严格传输安全 (HSTS) 等指令强制加密。 -- 禁用包含敏感数据的响应缓存。 +- 对应用程序处理、存储或传输的数据进行分类。根据隐私法、监管要求或业务需求识别哪些数据是敏感的。 +- 不要不必要地存储敏感数据。应尽快丢弃或使用符合 PCI DSS 的令牌化甚至截断。未保留的数据无法被窃取。 +- 确保对所有静态的敏感数据进行加密。 +- 确保使用最新且强大的标准算法、协议和密钥；使用适当的密钥管理。 +- 使用安全协议（如具有前向保密 (FS) 密码、由服务器优先选择密码和安全参数的 TLS）对所有传输中的数据进行加密。使用 HTTP 严格传输安全 (HSTS) 等指令强制执行加密。 +- 禁用包含敏感数据的响应的缓存。 - 根据数据分类应用所需的安全控制。 -- 不使用旧协议如 FTP 和 SMTP 传输敏感数据。 -- 使用具有工作因子（延迟因子）强自适应和加盐哈希函数来存储密码，例如 Argon2、scrypt、bcrypt 或 PBKDF2。 -- 初始化向量必须为操作模式选择合适的值。对于许多模式，这意味着使用 CSPRNG（密码学安全伪随机数生成器）。对于需要 nonce 的模式，初始化向量 (IV) 不需要 CSPRNG。在所有情况下，IV 不得在固定密钥的情况下重复使用。 -- 始终使用认证加密而不仅仅是加密。 -- 应密码学随机生成密钥，并以字节数组的形式存储在内存中。如果使用密码，则必须通过适当的密码基于密钥派生函数将其转换为密钥。 -- 确保在适当的情况下使用密码学随机性，且没有以可预测的方式或低熵例播种。大多数现代 API 不需要开发者播种 CSPRNG 以获得安全性。 -- 避免已弃用的密码学函数和填充方案，如 MD5、SHA1、PKCS 编号 1 v1.5。 +- 不要使用 FTP 和 SMTP 等旧版协议来传输敏感数据。 +- 使用具有工作因子（延迟因子）的强自适应和加盐哈希函数存储密码，例如 Argon2、scrypt、bcrypt 或 PBKDF2。 +- 必须为操作模式选择合适的初始化向量。 + 对于许多模式，这意味着使用 CSPRNG（密码学安全的伪随机数生成器）。对于需要 nonce 的模式，初始化向量 (IV) 不需要 CSPRNG。在所有情况下，对于固定的密钥，IV 都不应使用两次。 +- 始终使用认证加密，而不仅仅是加密。 +- 密钥应通过密码学方式随机生成，并以字节数组形式存储在内存中。如果使用了密码，则必须通过适当的密码派生密钥函数将其转换为密钥。 +- 确保在适当的地方使用密码学随机性，并且它没有以可预测的方式或低熵进行种子填充。大多数现代 API 不需要开发人员为 CSPRNG 填充种子即可获得安全性。 +- 避免使用已弃用的密码学函数和填充方案，例如 MD5、SHA1、PKCS 1 v1.5。 - 独立验证配置和设置的有效性。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- -- 全局安全访问的配置 (``Config\App::$forceGlobalSecureRequests``) +- 用于全局安全访问的配置 (``Config\App::$forceGlobalSecureRequests``) - :php:func:`force_https()` 函数 - :doc:`../libraries/encryption` -- 数据库配置中的 :ref:`数据库配置 ` (``encrypt``) -- 官方认证与授权框架 +- :ref:`数据库配置 ` (``encrypt``) +- 官方认证和授权框架 :ref:`CodeIgniter Shield ` -A03:2021 注入攻击 +A03:2021 注入 ================== -当应用程序存在以下情况时，容易遭受攻击： +当应用程序出现以下情况时，容易受到攻击： -- 用户提供的数据没有经过应用程序验证、过滤或清理。 -- 直接在解释器中使用动态查询或没有上下文感知转义的非参数化调用。 -- 使用对象关系映射（ORM）搜索参数中的恶意数据来提取额外的敏感记录。 -- 在动态查询、命令或存储过程中的结构和恶意数据直接使用或拼接恶意数据。 +- 应用程序未对用户提供的数据进行验证、过滤或净化。 +- 在解释器中直接使用动态查询或无参数化调用，且未进行上下文感知的转义。 +- 在对象关系映射 (ORM) 搜索参数中使用恶意数据以提取额外的敏感记录。 +- 直接使用或连接恶意数据。SQL 或命令在动态查询、命令或存储过程中包含结构和恶意数据。 -一些常见的注入类型包括 SQL、NoSQL、操作系统命令、对象关系映射（ORM）、LDAP 和表达式语言（EL）或对象图导航库（OGNL）注入。所有解释器中的概念都是相同的。源代码审查是检测应用程序是否易受注入攻击的最佳方法。强烈建议自动化测试所有参数、头信息、URL、Cookies、JSON、SOAP 和 XML 数据输入。组织可以将静态（SAST）、动态（DAST）和交互式（IAST）应用程序安全测试工具纳入 CI/CD 管道，以在生产部署前识别引入的注入漏洞。 +一些更常见的注入类型包括 SQL、NoSQL、操作系统命令、对象关系映射 (ORM)、LDAP，以及表达式语言 (EL) 或对象图导航库 (OGNL) 注入。所有解释器的概念都是相同的。代码审查是检测应用程序是否易受注入攻击的最佳方法。 +强烈建议对所有参数、头部、URL、Cookie、JSON、SOAP 和 XML 数据输入进行自动化测试。组织可以将静态 (SAST)、动态 (DAST) 和交互式 (IAST) 应用程序安全测试工具集成到 CI/CD 管道中，以在生产部署前识别引入的注入缺陷。 OWASP 建议 --------------------- -防止注入攻击需要将数据与命令和查询分开： +防止注入需要将数据与命令和查询分开： -- 首选选项是使用安全的 API，它完全避免使用解释器、提供参数化接口或迁移到对象关系映射工具（ORM）。 +- 首选方法是使用安全的 API，它完全避免使用解释器，提供参数化接口，或迁移到对象关系映射工具 (ORMs)。 - - 注意：即使是参数化的存储过程，如果 PL/SQL 或 T-SQL 拼接查询和数据或使用 EXECUTE IMMEDIATE 或 exec() 执行恶意数据，也可能引入 SQL 注入。 -- 使用正向服务器端输入验证。这不是一个完全的防御，因为许多应用程序需要使用特殊字符，如文本区域或移动应用程序的 API。 -- 对于任何剩余的动态查询，使用特定解释器的转义语法来转义特殊字符。 + - 注意：即使使用了参数化，如果 PL/SQL 或 T-SQL 连接查询和数据，或使用 EXECUTE IMMEDIATE 或 exec() 执行恶意数据，存储过程仍可能引入 SQL 注入。 +- 使用白名单式/肯定式服务器端输入验证。由于许多应用程序需要特殊字符（如文本区域或移动应用程序的 API），这并非完整的防御措施。 +- 对于任何剩余的动态查询，使用该解释器特定的转义语法来转义特殊字符。 - - 注意：无法转义 SQL 结构（如表名、列名等），因此用户提供的结构名是危险的。这在报告生成软件中是一个常见问题。 -- 在查询中使用 LIMIT 和其他 SQL 控制，以防止在 SQL 注入的情况下大规模披露记录。 + - 注意：表名、列名等 SQL 结构无法被转义，因此用户提供的结构名称是危险的。这是报表编写软件中的一个常见问题。 +- 在查询中使用 LIMIT 和其他 SQL 控制，以防止在发生 SQL 注入时大量泄露记录。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- - :ref:`urls-uri-security` - :ref:`invalidchars` 过滤器 - :doc:`../libraries/validation` 库 - :php:func:`esc()` 函数 -- :doc:`HTTP library <../incoming/incomingrequest>` 提供 - :ref:`input field filtering ` -- 支持 :ref:`content-security-policy` +- :doc:`HTTP 库 <../incoming/incomingrequest>` 提供 :ref:`输入字段过滤 ` +- 支持 :ref:`内容安全策略` - :doc:`../database/query_builder` -- :ref:`Database escape methods ` -- :ref:`database-queries-query-bindings` +- :ref:`数据库转义方法 ` +- :ref:`数据库查询绑定 ` -A04:2021 不安全设计 +A04:2021 不安全的设计 ======================== -不安全设计是代表不同弱点的一个广泛类别，表述为“缺失或无效的控制设计”。不安全设计不是所有其他前 10 名风险类别的来源。我们需要区分不安全设计和不安全实现，它们的根本原因和补救措施不同。 +不安全的设计是一个广泛的类别，代表不同的弱点，表现为“缺少或无效的控制设计”。不安全的设计并非所有其他十大风险类别的根源。不安全的设计与不安全的实现之间存在区别。我们之所以区分设计缺陷和实现缺陷，是因为它们有不同的根本原因和补救措施。 -一个安全的设计在实现上存在缺陷，可能会导致易于被利用的漏洞。而不安全的设计，即使有完美的实现，也无法弥补其缺陷，因为从定义上说，所需的安全控制从未被创建用于防御特定攻击。不安全设计的一个因素是缺乏在开发软件或系统时内在的业务风险评估，从而未能确定需要什么级别的安全设计。 +一个安全的设计仍可能存在导致漏洞的实现缺陷，这些漏洞可能被利用。不安全的设计无法通过完美的实现来修复，因为根据定义，必要的安全控制从未被创建以防御特定攻击。导致不安全设计的因素之一是所开发的软件或系统中固有的业务风险画像缺失， +从而导致无法确定所需的安全设计级别。 OWASP 建议 --------------------- -- 建立并使用一个安全开发生命周期，与 AppSec 专业人员合作，帮助评估和设计与安全和隐私相关的控制 -- 建立并使用一个安全设计模式库或预先准备好使用的组件 -- 使用威胁建模来针对关键的认证、访问控制、业务逻辑和关键流程 +- 建立并使用安全的开发生命周期，与应用安全 (AppSec) 专业人员合作， + 以帮助评估和设计安全与隐私相关的控制 +- 建立并使用安全设计模式库或可直接使用的组件库 +- 对关键的身份验证、访问控制、业务逻辑和关键流程使用威胁建模 - 将安全语言和控制集成到用户故事中 - 在应用程序的每一层（从前端到后端）集成合理性检查 -- 编写单元和集成测试，验证所有关键流程是否能抵御威胁模型。编写每一层的用例和错误用例。 -- 根据暴露和保护需求在系统和网络层分隔层级 -- 在所有层级中通过设计来稳固地分隔租户 -- 限制用户或服务的资源消耗 +- 编写单元和集成测试，以验证所有关键流程对威胁模型的抵抗力。为应用程序的每一层编译用例和误用例。 +- 根据暴露和保护需求，在系统和网络层上隔离各层 +- 在所有层中通过设计稳健地隔离租户 +- 按用户或服务限制资源消耗 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- -- :doc:`PHPUnit testing <../testing/overview>` -- 使用 :doc:`../libraries/throttler` 进行速率限制 -- 一个官方的身份验证和授权框架 :ref:`CodeIgniter Shield ` +- :doc:`PHPUnit 测试 <../testing/overview>` +- :doc:`../libraries/throttler` 用于限制频率 +- 官方认证和授权框架 :ref:`CodeIgniter Shield ` A05:2021 安全配置错误 ================================== -如果应用程序存在以下情况，可能会暴露于安全风险中： +如果应用程序出现以下情况，则可能易受攻击： -- 在应用程序堆栈的任何部分缺乏适当的安全加固，或云服务上配置不当的权限。 -- 启用了或安装了不必要的功能（例如，不必要的端口、服务、页面、账户或权限）。 +- 在应用程序堆栈的任何部分缺少适当的安全加固， + 或云服务上的权限配置不当。 +- 启用了不必要的功能或安装了不必要的功能（例如，不必要的端口、服务、页面、账户或权限）。 - 默认账户及其密码仍然启用且未更改。 -- 错误处理向用户透露了堆栈跟踪或其他过度详细的错误信息。 -- 对于升级系统，最新的安全功能被禁用或未安全配置。 -- 应用服务器、应用框架（如 Struts、Spring、ASP.NET）、库、数据库等的安全设置未设定为安全值。 -- 服务器没有发送安全头或指令，或它们未设定为安全值。 -- 软件过时或存在漏洞（参见 A06:2021-漏洞和过时的组件）。 +- 错误处理向用户显示堆栈跟踪或其他过于详细的信息。 +- 对于升级的系统，最新的安全功能被禁用或未安全配置。 +- 应用程序服务器、应用程序框架（例如，Struts、Spring、ASP.NET）、库、数据库等的安全设置未设置为安全值。 +- 服务器未发送安全头或指令，或未将其设置为安全值。 +- 软件已过时或存在漏洞（参见 A06:2021-易受攻击和过时的组件）。 -如果没有一个集中的、可重复的应用程序安全配置过程，系统将面临更高的风险。 +如果没有一个协调一致、可重复的应用程序安全配置流程， +系统将面临更高的风险。 OWASP 建议 --------------------- 应实施安全的安装流程，包括： -- 一个可重复的加固过程，使部署另一个适当锁定的环境变得快速且简单。开发、QA 和生产环境应全部按相同的方式配置，并在每个环境中使用不同的凭证。此过程应自动化，以尽量减少设置新安全环境所需的精力。 -- 一个最小的平台，没有任何不必要的功能、组件、文档和示例。删除或不安装未使用的功能和框架。 -- 将审查和更新配置作为补丁管理过程的一部分，适用于所有安全说明、更新和补丁（参见 A06:2021-漏洞和过时的组件）。审查云存储权限（例如 S3 存储桶权限）。 -- 一个分段的应用程序架构提供了组件或租户之间的有效且安全的分离，使用分段、容器化或云安全组（ACL）。 -- 向客户端发送安全指令，例如安全头信息。 -- 一个自动化过程，在所有环境中验证配置和设置的有效性。 - -CodeIgniter 的保护措施 +- 一个可重复的加固流程，使其能够快速轻松地部署另一个适当锁定的环境。 + 开发、QA 和生产环境应全部进行相同的安全加固配置，但在每个环境中使用不同的凭据。 + 此流程应自动化，以最小化设置新安全环境所需的工作量。 +- 一个不包含任何不必要功能、组件、文档和示例的最小化平台。 + 移除或不安装未使用的功能和框架。 +- 一项任务，即作为补丁管理流程的一部分， + 审查和更新与所有安全说明、更新和补丁相对应的配置（参见 A06:2021-易受攻击和过时的组件）。 + 审查云存储权限（例如，S3 存储桶权限）。 +- 一个分段的应用程序架构， + 通过分段、容器化或云安全组 (ACLs) 在组件或租户之间提供有效且安全的隔离。 +- 向客户端发送安全指令，例如，安全头。 +- 一个自动化流程，以验证所有环境中配置和设置的有效性。 + +CodeIgniter 应对措施 ---------------------- - :ref:`spark config:check ` 命令 - :ref:`spark phpini:check ` 命令 -- 默认情况下使用 :ref:`生产模式 ` +- 默认 :ref:`生产模式 ` - :ref:`secureheaders` 过滤器 -A06:2021 漏洞和过时的组件 +A06:2021 易受攻击和过时的组件 =========================================== -当存在以下情况时，你可能会受到漏洞的影响： +你很可能存在漏洞： -- 如果你不知道所使用的所有组件（包括客户端和服务端）的版本。这包括你直接使用的组件以及嵌套依赖项。 -- 如果软件存在漏洞、不再受支持或过期。这包括操作系统、Web/应用服务器、数据库管理系统（DBMS）、应用程序、API 以及所有组件、运行环境和库。 -- 如果你没有定期扫描漏洞并订阅与所用组件相关的安全公告。 -- 如果你没有基于风险在及时的基础上修复或升级底层平台、框架和依赖项。这在补丁管理是月度或季度任务的环境中很常见，会使组织在数天或数月内不必要地暴露于已修复的漏洞中。 +- 如果你不知道所使用的所有组件的版本（包括客户端和服务器端）。这包括你直接使用的组件以及嵌套的依赖项。 +- 如果软件存在漏洞、不受支持或已过时。这包括操作系统、Web/应用程序服务器、数据库管理系统 (DBMS)、应用程序、API 以及所有组件、运行时环境和库。 +- 如果你没有定期扫描漏洞，并订阅与所用组件相关的安全公告。 +- 如果你没有以基于风险的、及时的方式修复或升级底层平台、框架和依赖项。这在补丁是受变更控制的月度或季度任务的环境中很常见， + 使组织面临数天或数月的不必要暴露于已修复的漏洞。 - 如果软件开发人员没有测试更新、升级或打补丁的库的兼容性。 -- 如果你没有保障组件的配置安全（参见 A05:2021-安全配置错误）。 +- 如果你没有保护组件的配置（参见 A05:2021-安全配置错误）。 OWASP 建议 --------------------- -应有一个补丁管理流程，以： +应建立一个补丁管理流程，包括： -- 删除未使用的依赖项、不必要的功能、组件、文件和文档。 -- 持续清点客户端和服务端组件（如框架、库）及其依赖项的版本，使用 tools like versions、OWASP Dependency Check、retire.js 等工具。持续监控如公共漏洞和暴露（CVE）和国家漏洞数据库（NVD）等来源，以查找组件中的漏洞。使用软件组成分析工具来自动化此过程。订阅电子邮件警报，以获取与所用组件相关的安全漏洞。 -- 仅从官方来源通过安全链接获取组件。优先选择签名包以减少包含已修改的恶意组件的可能（参见 A08:2021-软件和数据完整性失败）。 -- 监控未维护或不为旧版本创建安全补丁的库和组件。如果打补丁不可能，考虑部署虚拟补丁来监控、检测或防护发现的问题。 +- 移除未使用的依赖项、不必要的功能、组件、文件和文档。 +- 使用版本、OWASP Dependency Check、retire.js 等工具， + 持续清点客户端和服务器端组件（例如，框架、库）及其依赖项的版本。 + 持续监控 Common Vulnerability and Exposures (CVE) 和 National Vulnerability Database (NVD) 等来源， + 以发现组件中的漏洞。使用软件成分分析工具来自动化该流程。 + 订阅与你所用组件相关的安全漏洞的电子邮件警报。 +- 仅通过安全链接从官方来源获取组件。优先选择签名包，以降低包含被修改的恶意组件的可能性（参见 A08:2021-软件和数据完整性失败）。 +- 监控未被维护或不为旧版本创建安全补丁的库和组件。如果无法打补丁， + 考虑部署虚拟补丁以监控、检测或保护免受已发现的问题。 每个组织必须确保有一个持续的计划，用于在应用程序或组合的生命周期内监控、分类和应用更新或配置更改。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- -- 使用 Composer :ref:`app-starter-upgrading` +- 通过 Composer 轻松 :ref:`应用启动器升级` A07:2021 身份识别和认证失败 =================================================== -确认用户身份、认证和 Session 管理对防范与认证相关的攻击至关重要。如果应用程序存在以下情况，可能存在认证弱点： +确认用户身份、认证和会话管理对防御认证相关攻击至关重要。如果应用程序： -- 允许自动攻击，例如凭证填充攻击，攻击者拥有一份有效的用户名和密码列表。 +- 允许自动化攻击，例如凭据填充（攻击者拥有一份有效的用户名和密码列表）。 - 允许暴力破解或其他自动化攻击。 -- 允许默认、弱或众所周知的密码，例如“Password1”或“admin/admin”。 -- 使用弱或无效的凭证恢复和忘记密码流程，例如不能保障安全的“基于知识的答案”。 +- 允许使用默认、弱或众所周知的密码，例如 "Password1" 或 "admin/admin"。 +- 使用弱或无效的凭据恢复和忘记密码流程， + 例如“基于知识的答案”，这些无法确保安全。 - 使用明文、加密或弱哈希的密码数据存储（参见 A02:2021-加密失败）。 -- 缺失或无效的多因素认证。 -- 在 URL 中暴露 Session 标识符。 -- 成功登录后重用 Session 标识符。 -- 未能正确使 Session ID 无效。用户 Session 或认证令牌（主要是单点登录（SSO）令牌）在注销或一段时间不活动期间未被正确使无效。 +- 缺少或多因素认证无效。 +- 在 URL 中暴露会话标识符。 +- 成功登录后重用会话标识符。 +- 未正确使会话 ID 失效。用户会话或认证令牌（主要是单点登录 (SSO) 令牌） + 在注销或一段时间不活动期间未被正确失效。 OWASP 建议 --------------------- -- 在可能的情况下，实现多因素认证，以防范自动化凭证填充、暴力破解和被盗凭证重复使用攻击。 -- 不要使用任何默认凭证进行运输或部署，特别是对于管理员用户。 -- 实施弱密码检查，例如针对最差的 10,000 个密码列表测试新或更改的密码。 -- 根据国家标准与技术研究所（NIST）800-63b 第 5.1.1 节的记忆密码或其他现代、基于证据的密码策略，调整密码长度、复杂性和轮换策略。 -- 确保注册、凭证恢复和 API 路径针对账户枚举攻击进行了加强，即对所有结果使用相同的消息。 -- 限制或逐渐延迟失败的登录尝试，但要小心不要创建拒绝服务情景。记录所有失败并在检测到凭证填充、暴力破解或其他攻击时警告管理员。 -- 使用服务器端的安全内置 Session 管理器，在登录后生成高熵的新随机 Session ID。Session 标识符不应在 URL 中出现，应安全存储，并在注销、空闲和绝对超时后使其失效。 - -CodeIgniter 的保护措施 +- 在可能的情况下，实施多因素认证， + 以防止自动化的凭据填充、暴力破解和被盗凭据重用攻击。 +- 不要使用任何默认凭据进行发布或部署，特别是管理员用户。 +- 实施弱密码检查，例如将新密码或更改的密码与最差的 10,000 个密码列表进行测试。 +- 使密码长度、复杂性和轮换策略符合美国国家标准与技术研究院 (NIST) 800-63b 第 5.1.1 节关于“记忆密钥”的指南， + 或其他现代、基于证据的密码策略。 +- 确保注册、凭据恢复和 API 路径通过为所有结果使用相同的消息来强化， + 以防御账户枚举攻击。 +- 限制或逐步延迟失败的登录尝试，但要小心不要造成拒绝服务场景。 + 记录所有失败，并在检测到凭据填充、暴力破解或其他攻击时向管理员发出警报。 +- 使用服务器端安全的内置会话管理器，在登录后生成一个高熵的随机会话 ID。 + 会话标识符不应在 URL 中，应安全存储，并在注销、空闲和绝对超时后失效。 + +CodeIgniter 应对措施 ---------------------- - :doc:`Session <../libraries/sessions>` 库 -- 官方的认证和授权框架 :ref:`CodeIgniter Shield ` +- 官方认证和授权框架 + :ref:`CodeIgniter Shield ` A08:2021 软件和数据完整性失败 ============================================= -软件和数据完整性失败涉及未能保护代码和基础设施免受完整性违反的影响。例如，当应用程序依赖来自不受信任来源、仓库和内容分发网络（CDNs）的插件、库或模块时，就可能存在问题。不安全的 CI/CD 管道可能引入未经授权的访问、恶意代码或系统泄露的潜在风险。 +软件和数据完整性失败涉及代码和基础设施， +它们无法防止完整性违规。一个例子是应用程序依赖于来自不可信来源、仓库和内容分发网络 (CDN) 的插件、库或模块。 +一个不安全的 CI/CD 管道可能导致未经授权访问、恶意代码或系统被攻陷。 -最后，许多应用程序现在包括自动更新功能，而这些更新在没有充分的完整性验证的情况下下载并应用于先前受信任的应用程序。攻击者可能会上传他们自己的更新，并分发和运行在所有安装中。 +最后，许多应用程序现在包含自动更新功能， +更新在没有充分完整性验证的情况下被下载并应用于先前受信任的应用程序。 +攻击者可能上传他们自己的更新程序， +以便在所有安装中分发和运行。 -另一个例子是，当对象或数据被编码或序列化为攻击者可以看到和修改的结构时，存在不安全的反序列化风险。 +另一个例子是对象或数据被编码或序列化为攻击者可以查看和修改的结构， +这容易受到不安全反序列化的影响。 OWASP 建议 --------------------- -- 使用数字签名或类似机制来验证软件或数据是否来自预期来源，并且未被修改。 -- 确保库和依赖项（如 npm 或 Maven）使用受信任的仓库。如果你有更高的风险配置文件，请考虑托管一个经过验证的内部已知良好仓库。 -- 确保使用软件供应链安全工具（如 OWASP Dependency Check 或 OWASP CycloneDX）来验证组件不包含已知漏洞。 -- 确保对代码和配置更改进行审查过程，以尽量减少引入恶意代码或配置到软件管道中的可能性。 -- 确保你的 CI/CD 管道具有适当的隔离、配置和访问控制，以确保代码在构建和部署过程中的完整性。 -- 确保未签名或未加密的序列化数据未发送到不受信任的客户端，而不进行某种形式的完整性检查或数字签名，以检测序列化数据的篡改或重放。 - -CodeIgniter 的保护措施 +- 使用数字签名或类似机制来验证软件或数据来自预期来源且未被篡改。 +- 确保库和依赖项（如 npm 或 Maven）从受信任的仓库获取。 + 如果你的风险状况较高，考虑托管一个经过审查的内部已知良好仓库。 +- 确保使用软件供应链安全工具（如 OWASP Dependency Check 或 OWASP CycloneDX）来验证组件是否不包含已知漏洞。 +- 确保有代码和配置变更的审查流程， + 以最小化恶意代码或配置被引入软件管道的可能性。 +- 确保你的 CI/CD 管道具有适当的隔离、配置和访问控制， + 以确保流经构建和部署过程的代码的完整性。 +- 确保未签名或未加密的序列化数据不会在没有某种完整性检查或数字签名的情况下发送给不可信客户端， + 以检测对序列化数据的篡改或重放。 + +CodeIgniter 应对措施 ---------------------- -- 不适用 +- 暂无 A09:2021 安全日志记录和监控失败 ================================================= -此类别旨在帮助检测、升级和响应活动中的入侵。如果没有日志记录和监控，入侵将无法被检测到。以下情况下发生日志记录、检测、监控和主动响应不足的情况： +此类别旨在帮助检测、上报和响应主动的入侵行为。没有日志记录和监控，就无法检测到入侵。 +每当出现以下情况时，就会发生日志记录、检测、监控和主动响应不足： -- 可审计事件（如登录、登录失败和高价值交易）未被记录。 -- 警告和错误没有生成、生成不充分或不清晰的日志消息。 +- 未记录可审计的事件，例如登录、登录失败和高价值交易。 +- 警告和错误未生成、生成了不充分或不清晰的日志消息。 - 未监控应用程序和 API 的日志以发现可疑活动。 -- 日志仅本地存储。 -- 适当的警报阈值和响应升级过程没有到位或无效。 -- 动态应用安全测试（DAST）工具（如 OWASP ZAP）的渗透测试和扫描未触发警报。 -- 应用程序无法实时或接近实时检测、升级或警报活跃攻击。 +- 日志仅存储在本地。 +- 未建立或无效的适当警报阈值和响应上报流程。 +- 渗透测试和动态应用程序安全测试 (DAST) 工具（如 OWASP ZAP）的扫描不会触发警报。 +- 应用程序无法实时或近实时地检测、上报或警报主动攻击。 如果将日志记录和警报事件暴露给用户或攻击者（参见 A01:2021-访问控制失效），你就可能会受到信息泄露的影响。 OWASP 建议 --------------------- -开发人员应根据应用程序的风险实施以下一些或所有控制： +开发人员应根据应用程序的风险实施以下部分或全部控制措施： -- 确保所有登录、访问控制和服务器端输入验证失败事件都能够记录下来，并具有足够的用户上下文以识别可疑或恶意账户，并保存足够长的时间以允许延迟的法证分析。 -- 确保生成的日志格式易于日志管理解决方案消费。 -- 确保日志数据正确编码，以防止对日志记录或监控系统的注入或攻击。 -- 确保高价值交易有完整性控制的审计追踪，以防止篡改或删除，如只追加数据库表或类似机制。 -- DevSecOps 团队应建立有效的监控和警报系统，以便快速检测和响应可疑活动。 -- 建立或采用事故响应和恢复计划，如国家标准与技术研究所（NIST）800-61r2 或更新版本。 +- 确保所有登录、访问控制和服务器端输入验证失败都能被记录， + 包含足够的用户上下文以识别可疑或恶意账户， + 并保留足够长的时间以允许延迟的取证分析。 +- 确保日志以日志管理解决方案可轻松解析/消费的格式生成。 +- 确保日志数据被正确编码，以防止对日志或监控系统进行注入或攻击。 +- 确保高价值交易具有带有完整性控制的审计跟踪， + 以防止篡改或删除，例如仅追加的数据库表或类似机制。 +- DevSecOps 团队应建立有效的监控和警报， + 以便快速检测和响应可疑活动。 +- 建立或采用事件响应和恢复计划，例如美国国家标准与技术研究院 (NIST) 800-61r2 或更高版本。 -存在商业和开源的应用保护框架，如 OWASP ModSecurity Core Rule Set，以及开源日志关联软件，如 Elasticsearch、Logstash、Kibana（ELK）堆栈，具有自定义仪表板和警报功能。 +存在商业和开源的应用保护框架，如 OWASP ModSecurity 核心规则集，以及开源日志关联软件，如 Elasticsearch、Logstash、Kibana（ELK）堆栈，具有自定义仪表板和警报功能。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- - :doc:`Logging <../general/logging>` 库 -- 官方的认证和授权框架 :ref:`CodeIgniter Shield ` +- 官方认证和授权框架 + :ref:`CodeIgniter Shield ` -A10:2021 服务器端请求伪造（SSRF） +A10:2021 服务端请求伪造 (SSRF) =========================================== -当一个 Web 应用程序在获取远程资源时未验证用户提供的 URL，就会发生 SSRF 漏洞。它允许攻击者强迫应用程序将构造的请求发送到意料之外的目的地，即使受到防火墙、VPN 或其他类型的网络访问控制列表（ACL）的保护。 +每当 Web 应用程序在未验证用户提供的 URL 的情况下获取远程资源时，就会出现 SSRF 缺陷。 +它允许攻击者强迫应用程序将精心制作的请求发送到意外的目的地， +即使受到防火墙、VPN 或其他类型的网络访问控制列表 (ACL) 保护也是如此。 -由于现代 Web 应用程序为最终用户提供了便利的功能，获取 URL 成为了常见的情况。因此，SSRF 的发生率在增加。与此同时，由于云服务和架构的复杂性，SSRF 的严重性也在增加。 +由于现代 Web 应用程序为最终用户提供便利的功能，获取 URL 已成为一种常见场景。 +因此，SSRF 的发生率正在增加。此外，由于云服务和架构的复杂性，SSRF 的严重性也在提高。 OWASP 建议 --------------------- -开发人员可以通过实施以下一些或所有的深度防御控制来预防 SSRF： +开发人员可以通过实施以下部分或全部纵深防御控制来防止 SSRF： 从网络层： -- 将远程资源访问功能划分到不同的网络中，以减少 SSRF 的影响 -- 强制执行“默认拒绝”的防火墙策略或网络访问控制规则，以阻止所有不重要的内部网络流量。 +- 将远程资源访问功能隔离在单独的网络中，以减少 SSRF 的影响 +- 强制执行“默认拒绝”的防火墙策略或网络访问控制规则， + 以阻止除必要内网流量外的所有流量。 - 提示： - * 基于应用程序建立防火墙规则的所有权和生命周期。 - * 记录防火墙上所有接受和阻止的网络流（参见 A09:2021-安全日志记录和监控失败）。 + * 基于应用程序建立防火墙规则的所有权和生命周期。 + * 在防火墙上记录所有接受和阻止的网络流 + （参见 A09:2021-安全日志记录和监控失败）。 从应用层： -- 清理和验证所有客户端提供的输入数据 -- 通过允许列表强制 URL 模式、端口和目的地 -- 不要将原始响应发送给客户端 +- 净化并验证所有客户端提供的输入数据 +- 使用白名单对 URL 协议、端口和目标进行强制规定 +- 不要向客户端发送原始响应 - 禁用 HTTP 重定向 -- 注意 URL 一致性，以避免 DNS 重新绑定和“检查时与使用时”(TOCTOU) 竞争条件等攻击 +- 注意 URL 的一致性，以避免 DNS 重绑定和“检查时间与使用时间”(TOCTOU) 竞态条件等攻击 -不要通过使用拒绝列表或正则表达式来缓解 SSRF。攻击者拥有绕过拒绝列表的有效负载列表、工具和技能。 +不要通过使用黑名单或正则表达式来缓解 SSRF。攻击者拥有有效载荷列表、工具和技能来绕过黑名单。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- - :doc:`../libraries/validation` 库 -- :doc:`HTTP 库 <../incoming/incomingrequest>` 提供了 :ref:`输入字段过滤 ` +- :doc:`HTTP 库 <../incoming/incomingrequest>` 提供 :ref:`输入字段过滤 ` ****************************** -OWASP API Security Top 10 2023 +OWASP API 安全十大风险 2023 ****************************** -API1:2023 对象级授权失效 +API1:2023 对象级别授权失效 =========================================== -API 往往会暴露处理对象标识符的端点，这样会产生广泛的对象级访问控制问题。在每个使用来自用户的 ID 访问数据源的函数中，都应考虑对象级授权检查。 +API 倾向于暴露处理对象标识符的端点， +从而创建了一个广泛的对象级访问控制问题攻击面。 +在每个使用用户提供的 ID 访问数据源的函数中，都应考虑对象级授权检查。 OWASP 建议 --------------------- -- 实施依赖于用户策略和层级的适当授权机制。 -- 使用授权机制检查登录用户是否有权在每个使用客户端输入访问数据库记录的函数中执行请求的操作。 +- 实施一个依赖于用户策略和层级的适当授权机制。 +- 在每个使用客户端输入访问数据库中记录的函数中， + 使用授权机制检查登录用户是否有权对记录执行请求的操作。 - 优先使用随机且不可预测的值作为记录 ID 的 GUID。 -- 编写测试以评估授权机制的漏洞。不要部署使测试失败的更改。 +- 编写测试以评估授权机制的漏洞。不要部署导致测试失败的更改。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- -- 官方的认证和授权框架 :ref:`CodeIgniter Shield ` +- 官方认证和授权框架 + :ref:`CodeIgniter Shield ` - :doc:`PHPUnit 测试 <../testing/overview>` API2:2023 认证失效 =============================== -认证机制常常被错误地实现，使得攻击者能够破解认证令牌或利用实现缺陷临时或永久地假冒其他用户的身份。破坏系统识别客户端/用户的能力就会破坏 API 的整体安全性。 +认证机制通常实施不当， +使攻击者能够破坏认证令牌或利用实现缺陷来临时或永久地冒充其他用户的身份。 +破坏系统识别客户端/用户的能力， +就破坏了 API 安全的整体性。 OWASP 建议 --------------------- -- 确保了解所有可能的 API 认证流程（移动应用/Web/实现单击认证的深层链接等）。询问你的工程师是否遗漏了某些流程。 -- 了解你的认证机制。确保理解它们的用途和使用方法。OAuth 不是认证，API 密钥也不是。 +- 确保你了解所有可能的 API 认证流程（例如实现一键认证的移动/Web/深度链接等）。询问你的工程师是否遗漏了什么流程。 +- 了解你的认证机制。确保你理解它们是什么以及如何使用。OAuth 不是认证，API 密钥也不是。 - 不要在认证、令牌生成或密码存储方面重新发明轮子。使用标准。 -- 凭据恢复/忘记密码端点应在防御暴力破解、速率限制和锁定保护方面与登录端点同等对待。 -- 对于敏感操作（例如更改账户所有者的电子邮件地址/两因素认证电话号码），需要重新认证。 -- 使用 OWASP 认证备忘清单。 -- 尽可能实施多因素认证。 -- 实施防暴力破解机制，以减轻凭据填充、字典攻击和针对认证端点的暴力破解攻击。此机制应比 API 上的常规速率限制机制更严格。 -- 实施账号锁定/验证码机制，以防止针对特定用户的暴力破解攻击。实施弱密码检查。 +- 凭据恢复/忘记密码端点在暴力破解、频率限制和锁定保护方面应被视为登录端点。 +- 对敏感操作要求重新认证（例如，更改账户所有者邮箱地址/2FA 电话号码）。 +- 使用 OWASP 认证速查表。 +- 在可能的情况下，实施多因素认证。 +- 实施反暴力破解机制，以缓解在认证端点上的凭据填充、字典攻击和暴力破解攻击。该机制应比 API 上的常规频率限制机制更严格。 +- 实施账户锁定/Captcha 机制以防止针对特定用户的暴力破解攻击。实施弱密码检查。 - API 密钥不应用于用户认证。它们仅应用于 API 客户端认证。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- - :doc:`../incoming/filters` - :ref:`routing-spark-routes` 命令 -- 官方的认证和授权框架 :ref:`CodeIgniter Shield ` -- 用于速率限制的 :doc:`../libraries/throttler` +- 官方认证和授权框架 + :ref:`CodeIgniter Shield ` +- :doc:`../libraries/throttler` 用于限制频率 -API3:2023 对象属性级授权失效 +API3:2023 对象属性级别授权失效 ==================================================== -这一类别结合了 API3:2019 的过度数据暴露和 API6:2019 的大量赋值问题，集中在根本原因：缺乏或不当的对象属性级授权验证。这导致了未经授权方的信息暴露或篡改。 +此类别结合了 API3:2019 过度数据暴露和 API6:2019 - 批量赋值， +聚焦于根本原因：缺少或不当的对象属性级授权验证。 +这会导致信息被未经授权的方暴露或操纵。 OWASP 建议 --------------------- -- 当通过 API 端点暴露一个对象时，始终确保用户应该访问你暴露的对象属性。 -- 避免使用诸如 to_json() 和 to_string() 之类的通用方法。相反，应选择具体的对象属性进行返回。 -- 如果可能，避免使用自动将客户端输入绑定到代码变量、内部对象或对象属性的功能（“大量赋值”）。 -- 仅允许客户端更新对象的特定属性。 -- 实施基于模式的响应验证机制作为额外的安全层。作为该机制的一部分，定义并强制执行所有 API 方法返回的数据。 -- 根据端点的业务/功能需求，将返回的数据结构保持在最低限度。 - -CodeIgniter 的保护措施 +- 当通过 API 端点暴露对象时， + 务必确保用户有权访问你暴露的对象属性。 +- 避免使用 to_json() 和 to_string() 等通用方法。 + 相反，应精确选取你明确希望返回的特定对象属性。 +- 如果可能，避免使用将客户端输入自动绑定到代码变量、内部对象或对象属性的函数（"批量赋值"）。 +- 仅允许客户端更新对象中应被其更新的属性。 +- 实施基于模式的响应验证机制作为额外的安全层。 + 作为该机制的一部分，定义并强制执行所有 API 方法返回的数据。 +- 根据端点的业务/功能需求， + 将返回的数据结构保持在最低限度。 + +CodeIgniter 应对措施 ---------------------- - 模型的 :ref:`model-allowed-fields` -- 官方的认证和授权框架 :ref:`CodeIgniter Shield ` +- 官方认证和授权框架 + :ref:`CodeIgniter Shield ` -API4:2023 不受限制的资源消耗 +API4:2023 未受限的资源消耗 =========================================== -满足 API 请求需要诸如网络带宽、CPU、内存和存储等资源。其他诸如电子邮件/SMS/电话或生物信息验证等资源由服务提供商通过 API 集成提供，并按请求付费。成功的攻击可能导致拒绝服务或运营成本增加。 +满足 API 请求需要网络带宽、CPU、内存和存储等资源。 +其他资源（如电子邮件/SMS/电话呼叫或生物识别验证） +由服务提供商通过 API 集成提供，并按请求付费。 +成功的攻击可能导致拒绝服务或运营成本增加。 OWASP 建议 --------------------- -- 使用一种可以轻松限制内存、CPU、重启次数、文件描述符和进程（如容器/无服务器代码，例如 Lambdas）的方法。 -- 定义并强制执行所有传入参数和负载数据的最大尺寸，例如字符串的最大长度、数组中的最大元素数和最大上传文件大小（无论存储在本地还是云存储中）。 -- 实施限制客户端在定义时间范围内与 API 交互频率的机制（速率限制）。 -- 速率限制应根据业务需求进行微调。某些 API 端点可能需要更严格的策略。 -- 限制/节流单个 API 客户端/用户执行单个操作的次数或频率（例如验证一次性密码，或在不访问一次性 URL 的情况下请求密码恢复）。 -- 添加适当的服务器端验证以控制查询字符串和请求体参数，尤其是那些控制响应中返回记录数量的参数。 -- 为所有服务提供商/API 集成配置消费限制。如果无法设置消费限制，应配置帐单警报。 - -CodeIgniter 的保护措施 +- 使用一种能够轻松限制内存、CPU、重启次数、文件描述符和进程（如容器/无服务器代码（例如 Lambdas））的解决方案。 +- 为所有传入参数和有效载荷定义并强制执行最大数据大小， + 例如字符串的最大长度、数组中元素的最大数量以及上传文件的最大大小（无论是在本地还是在云存储中存储）。 +- 在定义的时间范围内， + 实施对客户端与 API 交互频率的限制（频率限制）。 +- 频率限制应根据业务需求进行微调。某些 API 端点可能需要更严格的策略。 +- 限制/节流单个 API 客户端/用户执行单个操作的次数或频率 + （例如，验证一次性密码 (OTP) 或请求密码恢复而不访问一次性 URL）。 +- 为查询字符串和请求体参数添加适当的服务器端验证， + 特别是控制响应中返回记录数量的参数。 +- 为所有服务提供商/API 集成配置支出限额。当无法设置支出限额时， + 应配置账单警报。 + +CodeIgniter 应对措施 ---------------------- - :doc:`../libraries/validation` 库 -- 用于速率限制的 :doc:`../libraries/throttler` +- :doc:`../libraries/throttler` 用于限制频率 -API5:2023 功能级授权失效 +API5:2023 功能级别授权失效 ============================================= -复杂的访问控制策略，包括不同的层级、组和角色，以及行政和常规功能之间不明确的分离，往往导致授权缺陷。通过利用这些问题，攻击者可以访问其他用户的资源和/或管理功能。 +具有不同层级、组和角色的复杂访问控制策略， +以及管理功能和常规功能之间不清晰的分离， +往往会导致授权缺陷。通过利用这些问题， +攻击者可以获得对其他用户资源和/或管理功能的访问。 OWASP 建议 --------------------- -你的应用程序应有一个一致且易于分析的授权模块，该模块应从所有业务功能中调用。通常，这种保护是由应用代码外部的一个或多个组件提供的。 +你的应用程序应有一个一致且易于分析的授权模块， +该模块从所有业务功能中调用。通常， +此类保护由一个或多个应用程序代码外部的组件提供。 -- 执行机制应该默认拒绝所有访问，需要对每个功能的访问显式授予特定角色。 -- 根据功能级授权缺陷审查你的 API 端点，同时牢记应用程序的业务逻辑和组层次结构。 -- 确保所有管理控制器都继承自实现基于用户组/角色的授权检查的管理抽象控制器。 -- 确保常规控制器内的管理功能实现基于用户组和角色的授权检查。 +- 执行机制应默认拒绝所有访问， + 要求对每个功能的访问都必须明确授予特定角色。 +- 在审查 API 端点时， + 要针对功能级别授权缺陷，同时牢记应用程序的业务逻辑和组层级。 +- 确保所有管理控制器都继承自一个实现基于用户组/角色的授权检查的管理抽象控制器。 +- 确保在常规控制器内的管理功能实现基于用户组和角色的授权检查。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- - :doc:`../incoming/filters` -- 官方的认证和授权框架 :ref:`CodeIgniter Shield ` +- 官方认证和授权框架 + :ref:`CodeIgniter Shield ` -API6:2023 不受限制访问敏感业务流程 +API6:2023 对敏感业务流程的未受限访问 ========================================================= -存在这种风险的 API 暴露了某些业务流程——例如购票或发布评论——而没有考虑到这些功能如果以自动化的方式被过度使用会对业务造成怎样的损害。这并不一定来源于实现上的漏洞。 +易受此风险影响的 API 暴露了业务流程（例如购买票务或发表评论）， +而没有考虑到该功能在自动化方式下被过度使用时可能对业务造成的损害。 +这不一定源于实现缺陷。 OWASP 建议 --------------------- -缓解计划应该分两层进行： +缓解计划应在两个层面进行： -- 业务层：识别出如果过度使用可能对业务造成损害的业务流程。 -- 工程层：选择合适的保护机制来减轻业务风险。 +- 业务层面 - 识别如果被过度使用可能对业务造成损害的业务流程。 +- 工程层面 - 选择合适的保护机制来缓解业务风险。 -一些保护机制相对简单，而另一些则更复杂。以下方法通常用于减缓自动化威胁： +一些保护机制更简单，而另一些则更难实现。 +以下方法用于减缓自动化威胁： -- 设备指纹识别：拒绝意外客户端设备的服务（例如无头浏览器）往往会使威胁行为者使用更复杂的解决方案，从而增加其成本。 -- 人类检测：使用验证码或更先进的生物识别解决方案（例如输入模式）。 -- 非人类模式检测：分析用户流程以检测非人类模式（例如用户在不到一秒钟内访问了“添加到购物车”和“完成购买”功能）。 -- 考虑阻止 Tor 出站节点和知名代理的 IP 地址。 +- 设备指纹识别：拒绝向意外的客户端设备（例如无头浏览器）提供服务， + 这会促使威胁行为者使用更复杂的解决方案， + 从而增加他们的成本 +- 人类检测：使用 Captcha 或更高级的生物识别解决方案（例如打字模式） +- 非人类模式：分析用户流程以检测非人类模式 + （例如，用户在不到一秒钟内访问了“添加到购物车”和“完成购买”功能） +- 考虑阻止 Tor 出口节点和知名代理的 IP 地址 -保护并限制直接由机器使用的 API（如开发者和 B2B API）的访问。这些 API 往往是攻击者的容易目标，因为它们通常没有实现所有必要的保护机制。 +保护并限制机器直接消费的 API（例如开发者和 B2B API）的访问。 +它们往往是攻击者的易受攻击目标， +因为它们通常没有实施所有必需的保护机制。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- -- 不适用 +- 暂无 API7:2023 服务端请求伪造 ===================================== -服务端请求伪造（SSRF）漏洞可能会在 API 获取远程资源时未对用户提供的 URI 进行验证时出现。这使得攻击者能够迫使应用程序向意外的目标发送伪造的请求，即使这些目标受防火墙或 VPN 保护。 +当 API 在未验证用户提供的 URI 的情况下获取远程资源时， +可能会发生服务端请求伪造 (SSRF) 缺陷。 +这使攻击者能够强迫应用程序将精心制作的请求发送到意外的目的地， +即使受到防火墙或 VPN 保护也是如此。 OWASP 建议 --------------------- -- 在你的网络中隔离资源获取机制：通常这些功能是为了获取远程资源而不是内部资源。 -- 在可能的情况下，使用白名单： +- 在网络中隔离资源获取机制：通常这些功能旨在检索远程资源，而非内部资源。 +- 在可能的情况下，使用以下项目的白名单： - - 用户预计下载资源的远程来源（例如 Google Drive, Gravatar 等） - - URL 方案和端口 - - 给定功能的可接受媒体类型 + - 用户预期从其下载资源的远程来源（例如 Google Drive、Gravatar 等） + - URL 协议和端口 + - 特定功能接受的媒体类型 - 禁用 HTTP 重定向。 -- 使用经过良好测试和维护的 URL 解析器，以避免由于 URL 解析不一致引起的问题。 -- 验证并清理所有客户端提供的输入数据。 +- 使用经过充分测试和维护的 URL 解析器， + 以避免因 URL 解析不一致而导致的问题。 +- 验证并净化所有客户端提供的输入数据。 - 不要向客户端发送原始响应。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- - :doc:`../libraries/validation` 库 -- :doc:`HTTP library <../incoming/incomingrequest>` 提供 :ref:`输入字段过滤 ` +- :doc:`HTTP 库 <../incoming/incomingrequest>` 提供 :ref:`输入字段过滤 ` - :doc:`CURLRequest <../libraries/curlrequest>` 类 - :doc:`URI <../libraries/uri>` 类 API8:2023 安全配置错误 =================================== -API 及其支持系统通常包含复杂的配置，旨在使 API 更加可定制。软件和 DevOps 工程师可能会忽视这些配置，或在配置时未遵循安全最佳实践，从而为各种类型的攻击打开了大门。 +API 及其支持系统通常包含复杂的配置， +旨在使 API 更具可定制性。软件和 DevOps 工程师可能忽略这些配置， +或在配置时未遵循安全最佳实践， +从而为不同类型的攻击打开了大门。 OWASP 建议 --------------------- API 生命周期应包括： -- 一个可重复的强化过程，以快速轻松地部署一个适当锁定的环境。 -- 在整个 API 栈中审查和更新配置的任务。审查应包含：编排文件、API 组件和云服务（例如 S3 存储桶权限）。 -- 一个自动化过程，持续评估所有环境中配置和设置的有效性。 +- 一个可重复的加固流程， + 以实现快速轻松地部署一个适当锁定的环境 +- 一项任务，即审查和更新整个 API 堆栈的配置。 + 审查应包括：编排文件、API 组件和云服务（例如 S3 存储桶权限） +- 一个自动化流程， + 以持续评估所有环境中配置和设置的有效性 此外： -- 确保所有从客户端到 API 服务器及任何上下游组件的 API 通信都在加密通信通道（TLS）上进行，无论它是内部 API 还是公开 API。 -- 明确每个 API 可以访问的 HTTP 动词：应禁用所有其他 HTTP 动词（例如 HEAD）。 -- 预计从基于浏览器的客户端（例如，Web 应用前端）访问的 API 应至少： +- 确保从客户端到 API 服务器以及任何下游/上游组件的所有 API 通信都通过加密通信通道 (TLS) 进行， + 无论 API 是内部的还是面向公众的。 +- 明确每个 API 可以通过哪些 HTTP 动词访问：应禁用所有其他 HTTP 动词（例如 HEAD）。 +- 期望从基于浏览器的客户端（例如 WebApp 前端）访问的 API 应至少： - - 实施适当的跨域资源共享（CORS）策略 - - 包含适用的安全头 -- 将传入内容类型/数据格式限制为符合业务/功能要求的那些。 -- 确保 HTTP 服务器链中的所有服务器（例如，负载均衡器、反向和正向代理、后端服务器）以一致的方式处理传入请求，以避免反序列化问题。 -- 在适用的情况下，定义并强制执行所有 API 响应负载模式，包括错误响应，以防止异常跟踪和其他有价值的信息被返回给攻击者。 + - 实施适当的跨域资源共享 (CORS) 策略 + - 包含适用的安全头 +- 将传入的内容类型/数据格式限制为符合业务/功能要求的类型。 +- 确保 HTTP 服务器链中的所有服务器（例如负载均衡器、反向和正向代理以及后端服务器）以统一的方式处理传入请求， + 以避免不同步问题。 +- 在适用的情况下，定义并强制执行所有 API 响应有效载荷模式， + 包括错误响应，以防止异常跟踪和其他有价值的信息被发送回攻击者。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- -- 全局安全访问配置（``Config\App::$forceGlobalSecureRequests``） +- 用于全局安全访问的配置 (``Config\App::$forceGlobalSecureRequests``) - :php:func:`force_https()` 函数 - :ref:`已定义路由 ` - :ref:`auto-routing-improved` - :doc:`../libraries/cors` 过滤器 -API9:2023 不当的库存管理 +API9:2023 不当的资产管理 ======================================= -相比传统的 web 应用程序，API 往往暴露更多的端点，因此适当且更新的文档变得尤为重要。适当的主机和已部署 API 版本的库存管理也很重要，可以减轻诸如弃用 API 版本和暴露调试端点等问题。 +API 倾向于比传统 Web 应用程序暴露更多的端点， +因此正确且最新的文档变得非常重要。 +正确地对主机和已部署的 API 版本进行清点也至关重要， +以缓解诸如已弃用的 API 版本和暴露的调试端点等问题。 OWASP 建议 --------------------- -- 清点所有 API 主机并记录每个主机的重要方面，关注 API 环境（例如生产、暂存、测试、开发），谁应具有对主机的网络访问权限（例如公共、内部、合作伙伴）以及 API 版本。 -- 清点集成的服务并记录其重要方面，例如它们在系统中的角色、交换的数据（数据流）及其敏感性。 -- 记录 API 的所有方面，例如认证、错误、重定向、速率限制、跨域资源共享（CORS）策略和端点，包括它们的参数、请求和响应。 -- 通过采用开放标准自动生成文档。在你的 CI/CD 流水线中包含文档构建。 -- 仅向授权使用 API 的人提供 API 文档。 -- 对所有暴露的 API 版本使用外部保护措施（例如专门的 API 安全解决方案），而不仅限于当前的生产版本。 -- 避免在非生产 API 部署中使用生产数据。如果无法避免，这些端点应得到与生产端点相同的安全处理。 -- 当新版本的 API 包含安全改进时，进行风险分析，以通知旧版本所需的缓解措施。例如，是否可以在不破坏 API 兼容性的情况下向后移植改进，或需要迅速移除旧版本并强迫所有客户端迁移到最新版本。 - -CodeIgniter 的保护措施 +- 清点所有 API 主机，并记录每个主机的重要方面， + 重点关注 API 环境（例如生产、预发布、测试、开发）、 + 谁应拥有对主机的网络访问权限（例如公开、内部、合作伙伴）以及 API 版本。 +- 清点集成服务，并记录其重要方面， + 例如它们在系统中的角色、交换的数据（数据流）以及它们的敏感性。 +- 记录 API 的所有方面， + 例如认证、错误、重定向、频率限制、跨域资源共享 (CORS) 策略和端点， + 包括它们的参数、请求和响应。 +- 通过采用开放标准自动生成文档。将文档构建包含在你的 CI/CD 管道中。 +- 仅向有权使用 API 的人员提供 API 文档。 +- 对所有暴露的 API 版本（而不仅仅是当前生产版本）使用外部保护措施， + 例如特定的 API 安全解决方案。 +- 避免在非生产 API 部署中使用生产数据。如果无法避免， + 这些端点应获得与生产环境相同的安全待遇。 +- 当 API 的新版本包含安全改进时， + 执行风险分析以告知对旧版本所需采取的缓解措施。 + 例如，是否可以在不破坏 API 兼容性的情况下将改进回迁， + 或者你是否需要快速淘汰旧版本并强制所有客户端迁移到最新版本。 + +CodeIgniter 应对措施 ---------------------- - :ref:`routing-spark-routes` 命令 -API10:2023 不安全的 API 消费 +API10:2023 不安全地消费 API ===================================== -开发者往往比起用户输入更信任从第三方 API 接收的数据，因此更倾向于采用较弱的安全标准。为了攻击 API，攻击者更可能是针对集成的第三方服务，而不是直接尝试攻击目标 API。 +开发人员倾向于比用户输入更信任从第三方 API 接收的数据， +因此往往采用较弱的安全标准。 +为了破坏 API， +攻击者会针对集成的第三方服务，而不是直接尝试破坏目标 API。 OWASP 建议 --------------------- -- 在评估服务提供商时，评估其 API 的安全状态。 -- 确保所有 API 交互都通过安全通信通道（TLS）进行。 -- 在使用从集成 API 接收到的数据之前，始终验证并适当清理这些数据。 -- 保持一个集成 API 可能重定向到的已知位置白名单：不要盲目跟随重定向。 +- 在评估服务提供商时，评估其 API 安全态势。 +- 确保所有 API 交互都通过安全的通信通道 (TLS) 进行。 +- 在使用从集成 API 接收的数据之前， + 始终对其进行验证并正确净化。 +- 维护一个集成 API 可能将你的请求重定向到的知名位置的白名单：不要盲目地跟随重定向。 -CodeIgniter 的保护措施 +CodeIgniter 应对措施 ---------------------- - :doc:`CURLRequest <../libraries/curlrequest>` 类 diff --git a/source/concepts/services.rst b/source/concepts/services.rst index 2a07ee21d..401081444 100755 --- a/source/concepts/services.rst +++ b/source/concepts/services.rst @@ -9,130 +9,130 @@ 简介 ************ -什么是服务? +什么是服务？ ================== -CodeIgniter 4 中的 **服务** 提供了创建和共享新类实例的功能。它由 ``Config\Services`` 类实现。 +CodeIgniter 4 中的 **服务** 提供了创建和共享新类实例的功能。它通过 ``Config\Services`` 类实现。 -CodeIgniter 的所有核心类都以“服务”提供。这仅仅意味着,不是硬编码一个类名进行加载,而是在一个非常简单的配置文件中定义要调用的类。这个文件充当工厂的角色,用来创建所需类的新实例。 +CodeIgniter 内部的所有核心类都以“服务”形式提供。这仅仅意味着，与硬编码要加载的类名不同，需要调用的类被定义在一个非常简单的配置文件中。该文件充当一种工厂，用于创建所需类的新实例。 -为什么使用服务？ -================= +为什么要使用服务？ +================== -一个快速的例子可能会让事情更清晰，所以想象一下你需要引入一个 Timer 类的实例。最简单的方法可能就是直接创建这个类的一个新的实例： +一个简单的例子可能更容易理解。假设你需要引入一个 Timer 类的实例。最直接的方法就是创建该类的一个新实例： .. literalinclude:: services/001.php -这工作得很好。直到你决定用一个不同的计时器类来替代它。也许这个类有一些默认计时器不提供的高级报告功能。为了做到这一点，现在你必须找到你应用程序中使用计时器类的所有位置。由于你可能已经将它们保留下来，以持续运行应用程序的性能日志，这可能是一个耗时且容易出错的处理方式。这就是服务派上用场的地方。 +这非常有效。直到你决定要用一个不同的计时器类来替代它。也许这个类提供了一些默认计时器不具备的高级功能。为了实现这一点，你现在必须找到应用程序中所有使用了计时器类的地方。如果你为了持续记录应用程序性能而保留了这些代码，那么这种方式会非常耗时且容易出错。服务正是为了解决这个问题而设计的。 -我们不是自己创建实例，而是让一个中心类为我们创建类的实例。这个类保持非常简单。它只包含我们想要作为服务使用的每个类的方法。该方法通常返回该类的 **共享实例**，并将任何它可能具有的依赖项传递给它。然后，我们将替换我们的计时器创建代码，使用调用这个全局函数或服务类的代码： +我们不再自己创建实例，而是让一个中心类来为我们创建该类的实例。这个类非常简单，它只为每个我们想作为服务使用的类包含一个方法。该方法通常返回该类的一个 **共享实例**，并将任何可能的依赖项传递给它。然后，我们将计时器创建代码替换为调用这个全局函数或 Services 类的代码： .. literalinclude:: services/002.php -当你需要更改使用的实现时,可以修改服务配置文件,更改会自动传播到整个应用程序,而你不需要做任何事情。现在你只需要利用任何新的功能,就大功告成了。非常简单且不易出错。 +当你需要更改所使用的实现时，可以修改服务配置文件，更改会自动在整个应用程序中生效，而无需你做任何额外操作。现在你只需利用任何新功能即可。这种方式非常简单且不易出错。 -.. note:: 建议只在控制器中创建服务。其他文件,如模型和库应该通过构造函数或设置器方法传入依赖项。 +.. note:: 建议仅在控制器中创建服务。其他文件，如模型和库，应通过构造函数或 setter 方法传入依赖项。 如何获取服务 ******************** -由于许多 CodeIgniter 类作为服务提供,你可以像如下获取它们: +由于许多 CodeIgniter 类都以服务形式提供，你可以像下面这样获取它们： .. literalinclude:: services/013.php -``$timer`` 是一个 Timer 类的实例，如果你再次调用 ``service('timer')``，你将会得到完全相同的实例。 +``$timer`` 是 Timer 类的一个实例，如果你再次调用 ``service('timer')``，你将得到完全相同的实例。 -服务通常返回类的共享实例。下面的代码在首次调用时创建一个 ``CURLRequest`` 实例。第二次调用返回完全相同的实例。 +服务通常返回该类的一个 **共享实例**。以下代码在第一次调用时创建一个 ``CURLRequest`` 实例，第二次调用则返回完全相同的实例。 .. literalinclude:: services/015.php -因此, ``$client2`` 的参数 ``$options2`` 不起作用。它被忽略了。 +因此，``$client2`` 的参数 ``$options2`` 不会生效，它会被忽略。 获取新实例 ====================== -如果你想获取 Timer 类的新实例,需要向参数 ``$getShared`` 传递 ``false``: +如果你想获取 Timer 类的一个新实例，需要将参数 ``$getShared`` 设为 ``false``： .. literalinclude:: services/014.php -便利函数 +便捷函数 ===================== -提供了两个获取服务的函数。这些函数始终可用。 +提供了两个用于获取服务的函数，这些函数始终可用。 service() --------- -第一个是 ``service()``,它返回所请求服务的新实例。唯一必需的参数是服务名称。这与 Services 文件中的方法名称相同,总是返回类的一个共享实例,所以多次调用函数应该始终返回相同的实例: +第一个是 ``service()``，它返回所请求服务的一个实例。唯一必需的参数是服务名称。这与 Services 文件中的方法相同，始终返回该类的一个 **共享实例**，因此多次调用该函数应始终返回相同的实例： .. literalinclude:: services/003.php -.. note:: 自 v4.5.0 起，当你没有向服务传递参数时，推荐使用全局函数 ``service()``，因为性能有所提升。 +.. note:: 自 v4.5.0 起，当你不向服务传递参数时，由于性能提升，推荐使用全局函数 ``service()``。 -如果创建方法需要其他参数,可以在服务名称后传入: +如果创建方法需要额外的参数，可以在服务名称后传递它们： .. literalinclude:: services/004.php single_service() ---------------- -第二个函数 ``single_service()`` 的工作方式与 ``service()`` 相同,但返回类的新实例: +第二个函数 ``single_service()`` 的工作方式与 ``service()`` 类似，但返回一个新实例： .. literalinclude:: services/005.php 定义服务 ***************** -为了使服务能够良好地工作,你必须能够依赖于每个类具有一个恒定的 API 或 `接口 `_ 来使用它。CodeIgniter 的几乎所有类都提供了它们要遵守的接口。当你想扩展或替换核心类时,你只需要确保满足接口的要求,你就会知道这些类是兼容的。 +为了使服务正常工作，你必须能够依赖每个类都具有一个稳定的 API 或 `接口 `_。CodeIgniter 的几乎所有类都提供了一个它们遵循的接口。当你想要扩展或替换核心类时，你只需确保满足该接口的要求，就能知道这些类是兼容的。 -例如, ``RouteCollection`` 类实现了 ``RouteCollectionInterface``。当你想要创建一个提供不同路由创建方式的替代类时,你只需要创建一个实现 ``RouteCollectionInterface`` 的新类: +例如，``RouteCollection`` 类实现了 ``RouteCollectionInterface``。当你想要创建一个提供不同路由创建方式的替代类时，你只需创建一个实现 ``RouteCollectionInterface`` 的新类： .. literalinclude:: services/006.php -最后,在 **app/Config/Services.php** 中添加 ``routes()`` 方法,以创建 ``MyRouteCollection`` 的新实例,而不是 ``CodeIgniter\Router\RouteCollection``: +最后，将 ``routes()`` 方法添加到 **app/Config/Services.php** 中，以创建 ``MyRouteCollection`` 的新实例，而非 ``CodeIgniter\Router\RouteCollection``： .. literalinclude:: services/007.php -允许参数 +允许传入参数 =================== -在某些情况下,你会希望在实例化时有选择地向类传递设置。由于 services 文件是一个非常简单的类,因此很容易实现这一点。 +在某些情况下，你可能希望在实例化类时传入一个设置。由于服务文件是一个非常简单的类，实现这一点很容易。 -一个很好的例子是 ``renderer`` 服务。默认情况下,我们希望这个类能够在 ``APPPATH . 'views/'`` 中找到视图。我们希望开发人员有可能更改该路径,但如果他们的需求需要的话。所以该类接受 ``$viewPath`` 作为构造函数参数。服务方法如下所示: +一个很好的例子是 ``renderer`` 服务。默认情况下，我们希望该类能在 ``APPPATH . 'views/'`` 找到视图。但我们希望开发者能够根据需要更改该路径。因此，该类接受 ``$viewPath`` 作为构造函数参数。服务方法如下所示： .. literalinclude:: services/008.php -这会在构造函数中设置默认路径,但允许轻松更改它使用的路径: +这在构造函数方法中设置了默认路径，但也允许轻松更改所使用的路径： .. literalinclude:: services/009.php 共享类 ============== -有时候你需要要求只创建服务的单个实例。这可以通过在工厂方法中调用的 ``getSharedInstance()`` 方法轻松处理。这会处理检查实例是否已在类中创建和保存,如果没有,则创建一个新实例。所有工厂方法都提供 ``$getShared = true`` 作为最后一个参数。你也应该坚持使用该方法: +有时你需要确保只创建一个服务的实例。这可以通过工厂方法内部调用的 ``getSharedInstance()`` 方法轻松处理。该方法会检查该实例是否已在服务类中被创建并保存，如果没有，则创建一个新实例。所有的工厂方法都提供 ``$getShared = true`` 作为最后一个参数。你也应该遵循这种方法： .. literalinclude:: services/010.php 服务发现 ***************** -CodeIgniter 可以自动发现你可能在任何定义的命名空间中创建的任何 **Config/Services.php** 文件。这允许简单使用任何模块的 Services 文件。为了发现自定义 Services 文件,它们必须满足以下要求: +CodeIgniter 可以自动发现你在任何已定义的命名空间内创建的 **Config/Services.php** 文件。这使得可以轻松地使用任何模块的服务文件。为了使自定义服务文件被发现，它们必须满足以下要求： - 其命名空间必须在 **app/Config/Autoload.php** 中定义 -- 在命名空间内,该文件必须位于 **Config/Services.php** -- 它必须扩展 ``CodeIgniter\Config\BaseService`` +- 在命名空间内，该文件必须位于 **Config/Services.php** +- 它必须继承 ``CodeIgniter\Config\BaseService`` -一个小例子应该澄清这一点。 +一个小例子可以阐明这一点。 -假设在项目的根目录中创建了一个新目录 **Blog**。这将保存带有控制器、模型等的 **Blog 模块**,你想将其中一些类作为服务提供。第一步是创建一个新文件:**Blog/Config/Services.php**。该文件框架应该是: +假设你在项目根目录下创建了一个名为 **Blog** 的新目录。这将包含一个带有控制器、模型等的 **博客模块**，并且你希望将其中的一些类作为服务提供。第一步是创建一个新文件：**Blog/Config/Services.php**。该文件的骨架如下： .. literalinclude:: services/011.php -现在你可以像上面描述的那样使用此文件。当你想从任何控制器获取文章服务时,只需使用框架的 ``Config\Services`` 类获取你的服务: +现在你可以像上面描述的那样使用这个文件。当你想从任何控制器获取文章服务时，只需使用框架的 ``Config\Services`` 类来获取你的服务： .. literalinclude:: services/012.php -.. note:: 如果多个 Services 文件具有相同的方法名,则返回找到的第一个实例。 +.. note:: 如果多个服务文件具有相同的方法名，将返回找到的第一个实例。 .. _resetting-services-cache: @@ -141,8 +141,8 @@ CodeIgniter 可以自动发现你可能在任何定义的命名空间中创建 .. versionadded:: 4.6.0 -当 Services 类在框架初始化过程的早期首次被调用时，通过自动发现找到的 Services 类会被缓存到一个属性中，并且后续不会更新。 +当在框架初始化过程早期首次调用 Services 类时，通过自动发现找到的服务类会被缓存在一个类属性中，并且不会被更新。 -如果后续动态加载了模块，且这些模块中包含 Services 类，则必须更新缓存。 +如果稍后动态加载了模块，并且这些模块中有服务，那么必须更新缓存。 -可以通过运行 ``Config\Services::resetServicesCache()`` 来实现。这将清除缓存，并在需要时强制重新进行服务发现。 +这可以通过运行 ``Config\Services::resetServicesCache()`` 来实现。这将清除缓存，并在需要时强制重新进行服务发现。 diff --git a/source/concepts/structure.rst b/source/concepts/structure.rst index 9d74df5bd..ce0b5f99b 100755 --- a/source/concepts/structure.rst +++ b/source/concepts/structure.rst @@ -2,7 +2,7 @@ 应用程序结构 ##################### -为了充分利用 CodeIgniter,你需要了解默认情况下应用程序的结构,以及可以更改什么来满足应用程序的需要。 +要充分使用 CodeIgniter，你需要了解应用程序的默认结构，以及可以根据你的应用需求进行哪些更改。 .. contents:: :local: @@ -11,7 +11,7 @@ 默认目录 ******************* -一个全新安装有 5 个目录： +一个全新的安装包含五个目录： - **app** - **public** @@ -24,67 +24,67 @@ app === -**app** 目录是所有应用程序代码的存放位置。它具有默认的目录结构，适用于许多应用程序。 +**app** 目录是应用程序代码存放的地方。它自带一个默认的目录结构，适用于大多数应用程序。 -以下文件夹组成基本内容： +以下目录构成了其基本内容： .. code-block:: none app/ Config/ 存储配置文件 - Controllers/ 控制器确定程序流程 - Database/ 存储数据库迁移和种子文件 - Filters/ 存储可以在控制器之前和之后运行的过滤器类 + Controllers/ 控制器决定程序流程 + Database/ 存储数据库迁移和数据填充文件 + Filters/ 存储可在控制器前后运行的过滤器类 Helpers/ 辅助函数存储独立函数的集合 - Language/ 支持多语言会从这里读取语言字符串 - Libraries/ 不适合其他类别的有用类 - Models/ 模型与数据库一起工作来表示业务实体 - ThirdParty/ 应用程序中可以使用的第三方库 - Views/ 视图组成向客户端显示的 HTML + Language/ 多语言支持从这里读取语言字符串 + Libraries/ 存放不适合其他类别的有用类 + Models/ 模型与数据库交互，代表业务实体 + ThirdParty/ 可在应用中使用的第三方库 + Views/ 视图组成要向客户端显示的 HTML -由于 **app** 目录已经有了命名空间，你可以随意修改此目录的结构以适应应用程序的需要。 +因为 **app** 目录已经具备命名空间，你可以根据应用程序的需要自由修改此目录的结构。 -例如，你可能决定开始使用存储库模式和实体模型来处理数据。在这种情况下，你可以将 **Models** 目录重命名为 **Repositories**，并添加一个新的 **Entities** 目录。 +例如，你可能决定开始使用 Repository 模式和实体（Entities）来处理数据。在这种情况下，你可以将 **Models** 目录重命名为 **Repositories**，并添加一个新的 **Entities** 目录。 -此目录下的所有文件都位于 ``App`` 命名空间下，尽管你可以在 **app/Config/Constants.php** 中自由更改命名空间。 +此目录中的所有文件都位于 ``App`` 命名空间下，尽管你可以通过修改 **app/Config/Constants.php** 来更改它。 system ====== -.. note:: 如果使用 Composer 安装 CodeIgniter，**system** 位于 **vendor/codeigniter4/framework/system**。 +.. note:: 如果你使用 Composer 安装 CodeIgniter，则 **system** 目录位于 **vendor/codeigniter4/framework/system**。 -此目录存储构成框架本身的文件。虽然你在如何使用应用程序目录方面有很大的灵活性,但是不应修改 system 目录中的文件。相反,你应该扩展类或创建新类以提供所需的功能。 +此目录存储了构成框架本身的文件。虽然你对如何使用应用程序目录有很高的灵活性，但绝不应修改 system 目录中的文件。相反，你应该通过扩展类或创建新类来提供所需的功能。 -此目录下的所有文件位于 ``CodeIgniter`` 命名空间下。 +此目录中的所有文件都位于 ``CodeIgniter`` 命名空间下。 .. _application-structure-public: public ====== -**public** 文件夹包含 web 应用程序的面向浏览器的部分,防止直接访问源代码。 +**public** 目录存放了 Web 应用程序中可被浏览器访问的部分，防止对源代码的直接访问。 -它包含主要的 **.htaccess** 文件、**index.php** 以及你添加的任何应用程序资源,如 CSS、JavaScript 或图片。 +它包含主 **.htaccess** 文件、**index.php** 以及你添加的任何应用程序资源，如 CSS、JavaScript 或图片。 -此文件夹旨在成为站点的“网页根目录”,你的 web 服务器会配置为指向它。 +此目录旨在作为你网站的 "web root"，你的 Web 服务器将被配置为指向它。 writable ======== -此目录包含在应用程序生命周期中可能需要写入的任何目录。这包括用于缓存文件、日志和用户上传的任何目录。 +此目录用于存放应用程序在其生命周期中可能需要写入的任何目录。这包括用于存储缓存文件、日志以及用户可能上传的文件的目录。 -你应该在这里添加应用程序需要写入的任何其他目录。这使你可以保持其他主目录不可写,作为额外的安全措施。 +你应该将应用程序需要写入的其他任何目录都添加到这里。这允许你将其他主要目录保持为不可写状态，作为一种附加的安全措施。 tests ===== -此目录设置为保存测试文件。**_support** 目录包含可在编写测试时使用的各种模拟类和其他实用程序。 +此目录用于存放你的测试文件。**_support** 目录存放了各种模拟类和你在编写测试时可以使用的其他工具。 -此目录不需要传输到生产服务器。 +此目录无需转移到你的生产服务器上。 修改目录位置 ***************************** -如果你已重新定位任何主目录,可以在 **app/Config/Paths.php** 内更改配置设置。 +如果你已经移动了任何主要目录，可以在 **app/Config/Paths.php** 内更改配置设置。 请阅读 :doc:`管理你的应用程序 <../general/managing_apps>`。 From 707828cb5c4226630191d24a890ee574b5a5ad95 Mon Sep 17 00:00:00 2001 From: Hex Date: Sun, 11 Jan 2026 23:16:46 +0800 Subject: [PATCH 2/3] Enhance CodeIgniter documentation and translation process - Updated installation instructions in `index.rst` for clarity and consistency. - Revised credits section in `credits.rst` to improve readability and accuracy. - Improved PSR compatibility documentation in `psr.rst` with clearer language. - Clarified PHP requirements and optional extensions in `requirements.rst`. - Added a new command for translating CodeIgniter documentation from English to Chinese, including backup and guard processes. - Implemented hooks to protect files during translation and prevent dangerous Bash commands. - Created scripts for backing up files and guarding RST structure during translation. - Added summary generation for completed translation tasks. --- .../codeigniter-translation-reviewer.md | 243 +++++-- .claude/agents/codeigniter-translator.md | 282 +++----- .claude/commands/ci-translate.md | 126 ++++ .claude/commands/translate.md | 42 -- .claude/hooks/ci_translate_bash_guard.py | 46 ++ .claude/hooks/ci_translate_file_protect.py | 103 +++ .claude/hooks/ci_translate_stop_summary.py | 73 ++ .gitignore | 3 + .../codeigniter-translation-reviewer.md | 61 -- .iflow/agents/codeigniter-translator.md | 188 ----- .kilocodemodes | 52 -- .vscode/settings.json | 3 +- IFLOW.md | 130 ---- scripts/ci_backup.py | 36 + scripts/ci_rst_guard.py | 75 ++ source/cli/cli_generators.rst | 24 +- source/concepts/http.rst | 2 +- source/database/call_function.rst | 11 +- source/database/configuration.rst | 156 ++-- source/database/connecting.rst | 38 +- source/database/events.rst | 6 +- source/database/examples.rst | 41 +- source/database/helpers.rst | 24 +- source/database/index.rst | 18 +- source/database/metadata.rst | 77 +- source/database/queries.rst | 120 ++-- source/database/query_builder.rst | 667 ++++++++++-------- source/database/results.rst | 203 +++--- source/dbmgmt/db_commands.rst | 28 +- source/dbmgmt/forge.rst | 279 ++++---- source/dbmgmt/migration.rst | 158 ++--- source/dbmgmt/seeds.rst | 28 +- source/extending/authentication.rst | 15 +- source/extending/basecontroller.rst | 17 +- source/extending/common.rst | 4 +- source/extending/composer_packages.rst | 69 +- source/extending/contributing.rst | 4 +- source/extending/core_classes.rst | 34 +- source/extending/events.rst | 40 +- source/extending/index.rst | 2 +- source/general/ajax.rst | 48 +- source/general/caching.rst | 42 +- source/general/common_functions.rst | 286 ++++---- source/general/configuration.rst | 160 +++-- source/general/environments.rst | 67 +- source/general/errors.rst | 187 +++-- source/general/helpers.rst | 132 ++-- source/general/logging.rst | 65 +- source/general/managing_apps.rst | 24 +- source/general/modules.rst | 141 ++-- source/general/urls.rst | 94 +-- source/helpers/array_helper.rst | 74 +- source/helpers/cookie_helper.rst | 75 +- source/helpers/date_helper.rst | 30 +- source/helpers/filesystem_helper.rst | 113 +-- source/helpers/form_helper.rst | 307 ++++---- source/helpers/html_helper.rst | 169 ++--- source/helpers/inflector_helper.rst | 68 +- source/helpers/number_helper.rst | 45 +- source/helpers/security_helper.rst | 24 +- source/helpers/test_helper.rst | 20 +- source/helpers/text_helper.rst | 192 ++--- source/helpers/url_helper.rst | 288 ++++---- source/helpers/xml_helper.rst | 26 +- source/incoming/auto_routing_improved.rst | 176 ++--- source/incoming/content_negotiation.rst | 82 +-- source/incoming/controllers.rst | 156 ++-- source/incoming/filters.rst | 170 +++-- source/incoming/incomingrequest.rst | 319 +++++---- source/incoming/message.rst | 95 +-- source/incoming/methodspoofing.rst | 18 +- source/incoming/request.rst | 69 +- source/incoming/restful.rst | 100 +-- source/incoming/routing.rst | 440 ++++++------ .../backward_compatibility_notes.rst | 18 +- source/installation/deployment.rst | 99 +-- source/installation/index.rst | 27 +- source/intro/credits.rst | 15 +- source/intro/psr.rst | 36 +- source/intro/requirements.rst | 82 +-- 80 files changed, 4375 insertions(+), 3732 deletions(-) create mode 100644 .claude/commands/ci-translate.md delete mode 100644 .claude/commands/translate.md create mode 100755 .claude/hooks/ci_translate_bash_guard.py create mode 100755 .claude/hooks/ci_translate_file_protect.py create mode 100755 .claude/hooks/ci_translate_stop_summary.py delete mode 100644 .iflow/agents/codeigniter-translation-reviewer.md delete mode 100644 .iflow/agents/codeigniter-translator.md delete mode 100644 .kilocodemodes delete mode 100644 IFLOW.md create mode 100644 scripts/ci_backup.py create mode 100644 scripts/ci_rst_guard.py mode change 100755 => 100644 source/incoming/routing.rst mode change 100755 => 100644 source/intro/credits.rst diff --git a/.claude/agents/codeigniter-translation-reviewer.md b/.claude/agents/codeigniter-translation-reviewer.md index 42c48e71b..a2444a42a 100644 --- a/.claude/agents/codeigniter-translation-reviewer.md +++ b/.claude/agents/codeigniter-translation-reviewer.md @@ -1,57 +1,198 @@ --- name: codeigniter-translation-reviewer -description: 当需要对 CodeIgniter 4 文档英译中翻译进行质量保证时使用此代理。应在 codeigniter-translator 代理完成翻译后调用此代理，以确保准确性、一致性和遵守中文文案标准。 +description: CodeIgniter（Sphinx/reST）英译中译文发布前 QA：信息点对账确保零信息丢失，支持意义驱动重写的可读性优化建议，严格保证 reST 结构与代码字面量不被破坏。应在 codeigniter-translator 初稿后调用。 model: sonnet color: red --- -你是专精 CodeIgniter 4 文档翻译的中文技术文档审查专家。你的职责是对英译中翻译进行全面质量保证，确保它们达到准确性、一致性和可读性的最高标准。 - -你的职责包括： - -**翻译准确性审查：** -- 验证所有技术概念都被正确翻译并保持其原始含义 -- 检查 CodeIgniter 特定术语是否根据既定惯例一致翻译 -- 确保代码示例、函数名称和 API 引用保持不变并正确格式化 -- 验证所有 ReStructuredText 标记和 Sphinx 指令完全保留 - -**语言质量评估：** -- 应用项目 translation-guide.md 中定义的中文文案标准 -- 确保自然、流畅的中文表达同时保持技术精度 -- 检查中文标点符号、间距和格式惯例的正确使用 -- 验证整个文档中术语使用的一致性 - -**结构和格式验证：** -- 确认所有 RST 标记结构完好无损（标题、列表、代码块、交叉引用） -- 验证 Sphinx 指令正确运作（.. note::、.. warning::、.. code-block::） -- 检查内部链接和交叉引用是否正常工作 -- 确保一致的缩进和格式模式 - -**技术准确性验证：** -- 验证 PHP 代码示例保持语法正确 -- 确认配置示例和文件路径准确无误 -- 检查版本特定信息是否正确翻译 -- 确保兼容性说明和警告清楚传达 - -**审查流程：** -1. 通读整个翻译文档以检查整体流程和连贯性 -2. 将关键技术部分与原始英文对比以验证准确性 -3. 检查与之前翻译部分和既定术语的一致性 -4. 验证所有标记和格式元素 -5. 通过确保文档可被 Sphinx 处理来测试构建兼容性 - -**输出格式：** -提供结构化审查报告，包括： -- 总体评估（通过/需要修订/重大问题） -- 发现的具体问题及行号或章节引用 -- 术语一致性说明 -- 格式或标记问题 -- 改进建议 -- 后续步骤的最终建议 - -如果发现问题，将其分类为： -- **严重**：改变含义或破坏功能的翻译错误 -- **重要**：术语不一致或重要语言问题 -- **轻微**：风格改进或小的格式调整 - -你应该彻底但具有建设性，提供具体、可操作的反馈，帮助提高翻译质量，同时尊重翻译者的工作。 +你是 CodeIgniter 用户指南（Sphinx + reStructuredText）的中文译文审查专家。你审查的译文允许“意义驱动重写”（为提升可读性而调整语序/拆句/重组段落），但必须做到：不删减任何信息、不新增任何信息、技术强度不变、reST 结构零破坏。 + +# 输入 + +- 英文原文（reST） +- 中文译文（reST） + +# 输出（只输出审查报告；不要输出重译全文；不要附加无关解释） + +- 使用指定的 Markdown 报告结构 +- 每个问题必须包含：位置、原文摘录、译文摘录、问题说明、建议改法 + +# 核心审查方法：信息点对账 + 可读性重写建议（必须执行） + +## 1) 信息点对账（Accuracy without loss） + +对每个段落（或每个列表项/说明块）： + +- 从英文中提取“信息点”（事实/条件/限制/步骤/例外/警告/原因/结果/术语定义）。 +- 核对中文是否逐条覆盖：不漏、不多、不改含义；must/should/only/except 等语气强度必须一致。 +- 若发现遗漏/增添/弱化/强化：按 Critical/Major 分类，并给出“保留全部信息点”的修订建议。 + +## 2) 可读性与结构审查（Meaning-first rewrite quality） + +当中文“绕/难读”时，你必须提出“意义驱动重写”建议： + +- 允许：调整语序、拆分长句、合并同类项、主结论前置、主动语态、动词化表达、段落重组（不破坏 reST 结构前提下）。 +- 禁止：删除任何信息点；禁止添加原文没有的解释性内容。 +- 你的建议改写必须显式保留原段所有信息点，并尽量更清晰。 + +可读性常见问题类型（用于定位与给建议）： + +- 主语缺失或指代不明（“它/这/该”无法定位） +- 从句堆叠导致逻辑链过长（建议拆为 2–3 句） +- 名词化/介词化过度（“进行…的…的…”） +- 被动语态过多（可改主动表达但不改变语义责任主体） +- 信息顺序不符合中文阅读习惯（先结论/用途，后细节/原因/注意事项） +- 并列结构不对称、列表句式不统一 + +# 格式与技术硬约束（任何破坏都算严重问题） + +## reST/Sphinx 结构零破坏（Critical） + +以下内容不得翻译、不得改写、不得改动目标/参数、不得随意改空格或缩进： + +- directives 及其选项：`.. note::`、`.. warning::`、`.. code-block::`、`.. literalinclude::`、`.. toctree::`、`.. include::` 等 +- 交叉引用角色与目标：`:doc:` `:ref:` `:class:` `:meth:` `:func:` `:term:` 等 +- 显式目标/锚点/替换标识符：`.. _label:`、`|substitution|`、脚注标记 +- 行内标记与转义：`*em*`、`**strong**`、``literal``、反斜杠转义 +- 表格/列表/代码块缩进与对齐（不要“格式化”） + +## 标题装饰线规则（Critical） + +- 标题文本需要翻译 +- 装饰符号（`=` `-` `~` 等）必须保持同一种符号 +- 装饰线长度必须 ≥ 标题文本长度；中文标题更长时允许加长（优先只增不减） + +## 代码与字面量零翻译（Critical） + +以下内容一律保持英文原样： + +- 代码块、命令行、配置片段、输出日志 +- 行内字面量（``...``）内的内容 +- 类名/方法名/常量/配置键/路径/URL/HTTP 头字段名/状态码/参数名 + +# 术语一致性（必须与 translator 对齐；以 CI 中文用户指南用法为准） + +| 英文 | 标准中文译法 | 上下文 | +|------|--------------|--------| +| helper | 辅助函数 | | +| library | 类 | | +| controller | 控制器 | | +| model | 模型 | | +| view | 视图 | | +| route/routing | 路由 | | +| filter(s) | 过滤器 | CI4 语境 | +| migration(s) | 迁移 | +| seeder(s) | 数据库填充/数据填充 | 按上下文选择 | +| validation | 验证 | +| HTTP header | HTTP 标头 | +| HTTP verb / method | HTTP 方法 | HTTP 语境 | +| Auto Routing (Improved) | 自动路由（改进版） | | +| Auto Routing (Legacy) | 自动路由（传统版） | | + +**CodeIgniter 类名、方法名、常量、配置键一律保留英文原样** + +# 中文文案排版检查要点（机械项也要抓） + +- 中英文/数字之间加半角空格（例：CodeIgniter 4、HTTP 请求） +- 数字与单位不加空格（例：50ms、512MB） +- 中文句子用全角标点（，。！？；：），不重复标点 +- 专有名词大小写正确（GitHub、MySQL、API） + +# 问题分级 +- Critical：会导致构建失败/误导技术理解/破坏代码与字面量/破坏 reST 结构/遗漏关键限制与安全提示 +- Major：术语不一致、明显翻译腔影响理解、排版错误较多、逻辑关系不清 +- Minor：可读性与风格微调（不影响理解但可更清晰） + +# 报告输出格式（必须严格遵守） + +以 Markdown 输出： + +```markdown +# CodeIgniter 文档译文审查报告 + +## 1. 总体结论 +- **质量等级**：[✅ 可发布 / ⚠️ 需修订后发布 / 🚫 阻断发布] +- **分项评分**（1-5）：准确性 X/5 | 术语一致性 X/5 | 中文可读性 X/5 | 格式合规 X/5 +- **最重要的 3 个风险点**（若有）： + 1. ... + 2. ... + 3. ... + +## 2. Critical（阻断发布） +> ✅ **未发现阻断性问题** - 译文可安全构建和发布 +> +> 或 +> +> 🚫 **发现 X 处阻断性问题**（必须修复） + +每条按模板： + +### [C-编号] 简短标题 +- **位置**：章节/小节 + 可定位的译文片段 +- **原文**：`...` +- **译文**：`...` +- **问题**：... +- **建议**：`...`（给出可直接替换的中文或格式修复方式） +- **影响**：构建失败/误导理解/安全风险/示例不可用 等 + +## 3. Major（建议发布前修） +> ⚠️ **发现 X 处建议修复的问题** +> +> 或 +> +> ✅ **未发现 Major 级别问题** + +（同上模板，编号前缀改为 M-） + +## 4. Minor（可选优化） +> 💡 **发现 X 处优化建议**（可延后处理） +> +> 或 +> +> ✅ **未发现 Minor 级别问题** + +（同上模板，编号前缀改为 m-，可略简） + +## 5. 术语一致性快照（只列出"有问题的术语"） +> ✅ **术语使用一致** - 未发现术语混用问题 +> +> 或 + +| 英文术语 | 标准译法 | 当前译法（位置） | 结论 | +|---------|---------|----------------|------| +| helper | 辅助函数 | "帮助函数"（第 3 章）| ❌ 需统一 | +| ... | ... | ... | ... | + +## 6. 格式与排版扫描摘要 +- **reST 指令/交叉引用/锚点**：✅ 全部保留正确 / ⚠️ 发现 X 处问题（详见 Critical/Major） +- **标题装饰线**：✅ 全部符合规则 / ⚠️ 发现 X 处长度不足 +- **空格/标点/大小写**：✅ 符合规范 / ⚠️ 发现约 X 处需调整（典型示例：...） + +## 7. 审查覆盖率统计 +- 检查的 reST 指令数：X 个 ✅ +- 检查的代码块数：Y 个 ✅ +- 检查的交叉引用数：Z 个 ✅ +- 检查的术语出现次数：N 个 +- 发现问题的段落占比：M% + +## 8. 快速修复建议（可选，仅适用于机械性错误） + +以下问题可通过批量替换修复： + +\`\`\`bash +# 修复术语不一致（示例） +sed -i 's/帮助函数/辅助函数/g' translated.rst + +# 修复空格问题（示例） +sed -i 's/CodeIgniter4/CodeIgniter 4/g' translated.rst +\`\`\` + +**⚠️ 警告**：执行前请备份文件！复杂问题仍需手工修复。 +``` + +# 审查边界（防止编造） + +- 你只做"静态审查"。**不要声称**"已构建/已运行/已验证可执行" +- 若某点需要运行验证，请写成"**建议在本地 sphinx-build 或运行示例确认**"，并说明要验证什么 +- 不要编造问题或夸大严重程度 +- 遇到不确定的情况，标注为"**需人工复核**" diff --git a/.claude/agents/codeigniter-translator.md b/.claude/agents/codeigniter-translator.md index a69a5f56b..ea0af360a 100644 --- a/.claude/agents/codeigniter-translator.md +++ b/.claude/agents/codeigniter-translator.md @@ -1,184 +1,110 @@ --- name: codeigniter-translator -description: 专业的 CodeIgniter 4 文档英译中代理，专精 ReStructuredText 格式保持和技术准确性。严格遵循中文文案标准和 CodeIgniter 术语一致性，为读者提供最佳体验。 +description: 出版级 CodeIgniter 文档英译中代理（Sphinx/reST）。严格保持 reST 结构零破坏、代码零翻译、术语与现有中文用户指南一致，并输出自然专业的中文技术文案。 model: sonnet color: blue --- -你是一名资深技术文档翻译专家，在 PHP 框架 CodeIgniter 和中文技术写作方面都有深厚的专业知识。你的使命是提供出版级质量的中文翻译，完美平衡技术准确性与读者理解，同时保持对 ReStructuredText 格式的绝对忠实。 - -## 核心翻译理念 - -### 读者为中心的方法 -- **主要目标**：让中文技术读者能够高效准确地学习 CodeIgniter -- **易读性**：在不牺牲精确性的前提下让复杂技术概念易于理解 -- **一致性**：在所有文档中保持统一的术语和风格 -- **专业性**：提供与原创中文技术文档无法区分的翻译质量 - -### 技术卓越标准 -- **零信息丢失**：必须保留每个技术细节、示例和微妙差别 -- **格式完整性**：ReStructuredText 结构必须完全保持不变 -- **代码保留**：所有代码元素保持原始英文 -- **上下文准确性**：翻译反映对 CodeIgniter 架构和 PHP 概念的深度理解 - -## 翻译规范 - -### 1. 中文语言标准 - -#### 代词使用 -- **始终**使用非正式的"你"和"你的"（绝不使用正式的"您/您的"） -- 保持技术文档开发者期望的直接、专业语调 - -#### 中文表达优化（反机器翻译） -- **消除冗余代词**：避免不必要的"你"、"你的"、"这"，它们会让句子冗长 -- **自然流畅**：删除上下文中隐含的代词以获得更流畅的阅读体验 -- **避免机器翻译模式**：将机械翻译转换为自然的中文表达 -- **使用主动语态**：在适当时优先使用直接陈述而非被动结构 -- **上下文适应**：根据中文技术写作惯例调整句型 -- 示例： - - ✅ 推荐："使用 Session 库存储用户数据"（直接、简洁） - - ❌ 避免："你可以使用 Session 库来存储你的用户数据"（冗余代词） - - ✅ 推荐："配置文件位于 `app/Config/` 目录"（清晰、直接） - - ❌ 避免："你的配置文件位于 `app/Config/` 这个目录中"（不必要的词汇） - - ✅ 推荐："数据库连接失败时会抛出异常"（自然的中文） - - ❌ 避免："当数据库连接失败的时候，系统将会抛出一个异常"（冗长、机器式） - - ✅ 推荐："支持多种缓存驱动"（简洁） - - ❌ 避免："它支持多种不同的缓存驱动程序"（冗余词汇） - -#### 排版标准（严格遵守要求） -- **中英文间距**：中文字符与英文单词之间添加半角空格 - - ✅ 正确："在 CodeIgniter 框架中使用 Session 库" - - ❌ 错误："在CodeIgniter框架中使用Session库" -- **中文数字间距**：中文字符与数字之间添加半角空格 - - ✅ 正确："数据库连接池支持 100 个并发连接" - - ❌ 错误："数据库连接池支持100个并发连接" -- **单位格式**：数字与单位（MB、KB、ms 等）之间不添加空格 - - ✅ 正确："内存占用为 512MB，响应时间低于 50ms" - - ❌ 错误："内存占用为 512 MB，响应时间低于 50 ms" -- **中文标点**：中文句子使用全角标点符号（，。！？；：） - - ✅ 正确："请注意，这个功能在生产环境中非常重要。" - - ❌ 错误："请注意,这个功能在生产环境中非常重要." -- **英文标点**：中文文本中的英文短语使用半角标点符号 -- **品牌/技术术语大小写**：保持正确的大小写 - - ✅ 正确："使用 GitHub、MySQL、CodeIgniter、API 等技术" - - ❌ 错误："使用 github、mysql、codeigniter、api 等技术" -- **不重复标点**：绝不为了强调而重复标点符号 - - ✅ 正确："这个功能非常重要！" - - ❌ 错误："这个功能非常重要！！！" - -### 2. ReStructuredText 格式保留（关键） - -#### 指令保留 -- **绝不**翻译或修改 RST 指令： - - `.. note::`、`.. warning::`、`.. important::`、`.. tip::` - - `.. literalinclude::`、`.. code-block::`、`.. contents::` - - `.. versionadded::`、`.. versionchanged::`、`.. deprecated::` - - 句尾的双冒号(::) - - 所有自定义 CodeIgniter 指令 -- **保持不变**：缩进、空格、间距 -- **维护结构**：代码块、表格、列表、交叉引用 - -#### 需要特别注意的格式元素 -- **代码块**：绝不翻译内容，精确保留缩进 -- **行内代码**：保持所有用反引号包装的代码为英文 -- **交叉引用**：保持 `:doc:`、`:meth:`、`:class:` 链接目标为英文 -- **表格结构**：保留列对齐和 RST 表格语法 -- **列表格式**：保持项目符号、编号列表、定义列表 -- **节标题**：翻译内容但保留并保持下划线字符及其数量（=、-、~） - -### 3. CodeIgniter 特定翻译标准 - -#### 核心术语（使用英文 - 绝不翻译） -- 框架组件名称：`Session`、`Email` -- 类名：`BaseController`、`Model`、`Entity`、`Config` -- 方法/属性名称：`insert()`、`find()`、`where()`、`join()` -- 常量：`ENVIRONMENT`、`APPPATH`、`ROOTPATH` -- 配置键：`database.default.hostname` - -#### 标准中文翻译 -- "helper" → "辅助函数" -- "library" → "库" -- "model" → "模型" -- "controller" → "控制器" -- "view" → "视图" -- "route/routing" → "路由" -- "middleware" → "中间件" -- "filter" → "过滤器" -- "validation" → "验证" -- "migration" → "迁移" -- "seeder" → "数据填充" -- "cookie" → "Cookie" -- "cookies" → "Cookie" -- "constant" → "常量" -- "query builder" → "查询构建器" - -#### 上下文相关术语 -- "method" → "方法"（类方法）/"方式"（方法、途径） -- "property" → "属性"（类属性）/"特性"（特征） -- "parameter" → "参数"（函数参数）/"设置"（配置设置） -- "return" → "返回"（函数返回）/"回到"（导航） - -### 4. 翻译质量保证 - -#### 翻译前分析 -- **文档结构映射**：开始前识别所有 RST 元素 -- **术语提取**：列出所有技术术语以进行一致性检查 -- **代码块识别**：标记所有代码部分以避免翻译 - -#### 翻译执行 -- **段落级翻译**：保持逻辑流程和上下文 -- **技术准确性验证**：确保所有概念正确传达 -- **交叉引用验证**：验证所有内部链接保持功能 -- **示例一致性**：确保翻译文本与代码示例匹配 -- **流畅度优化**：重写翻译使其在中文中读起来自然和专业 -- **反翻译标记**：删除明显的机器翻译痕迹（过多的"的"、尴尬的句子结构） -- **母语者验证**：确保输出读起来像是由母语中文技术作者编写的 - -#### 翻译后审查 -- **格式验证**：确认 RST 结构与原文相同 -- **排版检查**：应用所有中文文案标准 -- **术语一致性**：验证整个文档中术语使用的统一性 -- **可读性评估**：确保流畅、自然的中文表达 -- **技术正确性**：验证所有技术信息的准确性 - -## 高级翻译技巧 - -### 自然中文表达 -- **句子结构优化**：在保留意义的同时适应中文阅读模式 -- **逻辑流程增强**：使用中文过渡短语以便更好理解 -- **读者指导**：以有助于中文学习者的方式构建信息 -- **习惯用语表达**：在适当的地方使用自然的中文习惯用语和表达 -- **节奏和韵律**：确保翻译具有自然的中文阅读节奏，使用合理断句避免超长句子 -- **避免直译**：将英文思维模式转换为中文逻辑流程 - -### 上下文感知翻译 -- **跨文档一致性**：在整个用户指南中保持术语一致性 -- **渐进复杂度**：考虑读者通过文档的学习过程 -- **文化适应**：解释中国开发者可能不熟悉的概念 -- **最佳实践强调**：为中国开发团队清楚地突出重要实践 - -## 输出要求 - -### 格式合规 -- **无解释性注释**：绝不添加翻译评论或解释 -- **精确格式**：精确匹配原始缩进、间距和结构 -- **完整内容**：包含源文档中的每个元素 - -### 质量标准 -- **专业级别**：适合官方技术文档的翻译质量 -- **零错误**：零格式错误、术语不一致或翻译错误 -- **读者优化**：为中国 PHP 开发者的理解而优化 -- **可维护性**：一致的风格使未来更新和修订变得容易 - -## 严格的性能要求 - -你必须展示： -- **深度 CodeIgniter 专业知识**：对框架概念和架构的全面理解 -- **高级中文技术写作**：母语级别的中文技术文档技能 -- **RST 精通**：专家级 ReStructuredText 格式和 Sphinx 文档系统知识 -- **质量强迫症**：对产生完美技术翻译的坚定承诺 -- **读者同理心**：清楚理解中国开发者的学习需求和偏好 - -**最终提醒**：你的翻译将被成千上万的中国开发者用来学习 CodeIgniter。每个词、格式元素和技术细节都必须完美。对错误、不一致或格式问题零容忍。 - -**质量基准**：你的翻译应该与有经验的中文技术作者原创内容无法区分。避免任何"翻译味"的痕迹 - 文本必须在中文中读起来自然流畅，同时保持完整的技术准确性。 +你是资深技术文档译者，专注 CodeIgniter 用户指南（Sphinx + reStructuredText）。你的输出用于正式发布：必须技术准确、中文自然、且 reST 结构可直接构建。 + +# 任务输入/输出 + +- 输入：英文 .rst 内容（可能包含 Sphinx 指令、交叉引用、代码块、表格、列表等） +- 输出：对应的中文 .rst 全文（只输出译文，不要附加解释/点评/对照表） + +# 绝对硬约束（违反即视为错误） + +## A. reST/Sphinx 结构零破坏 + +以下内容不得翻译、不得改写、不得改动目标/参数、不得增删空格或缩进（除非规则明确允许）： + +1. 指令与块标记：以 `.. ` 开头的 directive 行及其选项（如 `.. note::`、`.. warning::`、`.. code-block::`、`.. literalinclude::`、`.. toctree::`、`.. contents::`、`.. include::` 等） +2. 交叉引用与角色：`:doc:` `:ref:` `:class:` `:meth:` `:func:` `:term:` 等角色名与目标保持英文原样，仅翻译可见文本（若存在） +3. 行内标记与转义：`*emphasis*`、`**strong**`、``literal`` 的定界符必须保留；若英文原文用了反斜杠转义（如 `\*`），必须原样保留 +4. 显式目标/锚点/替换：`.. _label:`、`|substitution|`、脚注与引用标记等，标识符不得翻译 +5. 缩进与空行：不要“顺手格式化”。段落、列表、代码块、表格的对齐必须保持 + +## B. 代码与字面量零翻译 + +以下内容一律保持英文原样（仅可在周边解释性文字中翻译）： + +- 代码块、命令行示例、配置片段、输出日志 +- 行内字面量（``like this``）中的内容 +- 类名/命名空间/方法/属性/常量/配置键/文件路径/URL/HTTP 头字段名/状态码/参数名 + +## C. 标题装饰线规则（允许“只为防错而改”） + +- 章节标题文本需要翻译 +- 标题装饰符号（`=` `-` `~` 等）必须保持同一种符号 +- 装饰线长度必须 ≥ 标题文本长度；若中文标题更长导致不够长，允许把装饰线加长（优先只增不减） + +# 术语与译名（以现有中文用户指南用法为准） + +## 1) 固定不翻译（永远保留英文） + +- 框架组件/类/接口/特性名：`Session`、`Email`、`Model`、`Entity`、`Config` 等 +- 方法/函数/属性/常量/配置键：`find()`、`where()`、`APPPATH`、`database.default.hostname` 等 + +## 2) 标准译法（强制一致） + +| 英文 | 中文 | 上下文 | +|------|------|--------| +| helper | 辅助函数 | | +| library | 类 | | +| controller | 控制器 | | +| model | 模型 | | +| view | 视图 | | +| route/routing | 路由 | | +| filter(s) | 过滤器 | | +| migration(s) | 迁移 | | +| seeder(s) | 数据库填充 / 数据填充 | 按上下文选择 | +| validation | 验证 | | +| HTTP header | HTTP 标头 | | +| HTTP verb / method | HTTP 方法 | HTTP 语境 | +| Auto Routing (Improved) | 自动路由（改进版） | | +| Auto Routing (Legacy) | 自动路由（传统版） | | + +# 中文技术文案规范 + +1. **中英文间距**：中文与英文/数字之间加空格 + - ✅ "CodeIgniter 4"、"HTTP 请求" + - ❌ "CodeIgniter4"、"HTTP请求" + +2. **单位格式**：数字与单位不加空格 + - ✅ "10Gbps"、"50ms" + - ❌ "10 Gbps"、"50 ms" + +3. **中文标点**：中文句子使用全角标点（，。！？；：），不重复标点 + +4. **避免机器翻译腔**： + - 删冗余"你可以/我们/实际上/为了去…" + - 优先直接陈述、动词化表达 + - 必要时拆长句 + +5. **代词策略**：默认使用"你/你的"，但能省则省，保持简洁专业 + +# 可读性增强：意义驱动重写（必须执行） + +在不删减任何信息、不新增任何信息的前提下，允许对句子与段落进行“意义驱动的中文重写”，以提升可读性： +- 允许：调整语序、拆分长句、合并短句、把名词化表达改为动词表达、把主结论前置、用更清晰的因果/转折连接词。 +- 禁止：省略限定条件/前提/例外/步骤/警告/数值/版本/参数类型/返回值；禁止添加原文没有的解释性内容。 + +## 内部四步法（不对外输出过程） +1) 信息点提取：把每段英文拆成若干信息点（事实/条件/步骤/原因/结果/警告）。 +2) 中文重组表达：用更自然直接的中文组织这些信息点（优先主动语态、短句、每句一个要点）。 +3) 覆盖核对：逐条确认每个英文信息点在中文中都有对应表达（零遗漏、零增添、零篡改）。 +4) 术语与格式复核：术语库一致；RST 指令/角色/锚点/缩进/表格对齐不变；代码与字面量零翻译。 + +## 可读性目标（不降低技术精度） +- 优先使用清晰直接的表达与主动语态（必要时保留被动语态以符合语义）。 +- 避免多个从句串联；超过约 30 词的英文长句，优先拆成 2–3 句中文。 +- 一段一个中心意思，先说“做什么/结论”，再说“为什么/怎么做”。 + +# 输出前自检（必须执行） + +- **完整性**：不漏译、不多译，技术细节保持一致 +- **格式**：指令、角色、锚点、缩进、空行、表格对齐、代码块缩进全部保留 +- **标题**：符号不变，装饰线长度 ≥ 标题长度 +- **术语**：同一概念全篇一致 +- **信息点对账**：对每段英文至少做一次“要点清单→中文逐条对应”的核对（内部进行，不输出清单）。 +- **细节哨兵**：凡出现 must/should/only/except/required/not allowed/注意事项、以及数值/版本/参数/返回值，中文必须逐一出现且语气强度匹配。 diff --git a/.claude/commands/ci-translate.md b/.claude/commands/ci-translate.md new file mode 100644 index 000000000..98df78ad3 --- /dev/null +++ b/.claude/commands/ci-translate.md @@ -0,0 +1,126 @@ +--- +description: CodeIgniter RST 英译中（备份→翻译→guard→审查报告→按报告修订→guard→覆盖），出版级质量，RST 保真（hooks 护栏） +argument-hint: [--dry-run] [file2.rst ...] +allowed-tools: + - Read + - Write + - Edit + - Bash(mkdir:*) + - Bash(python scripts/*:*) + - Bash(git status:*) + - Bash(git diff:*) + - Bash(ls:*) +hooks: + PreToolUse: + - matcher: "Write|Edit" + hooks: + - type: command + command: "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/ci_translate_file_protect.py" + - matcher: "Bash" + hooks: + - type: command + command: "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/ci_translate_bash_guard.py" + Stop: + - hooks: + - type: command + command: "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/ci_translate_stop_summary.py" +--- + +# 任务：CodeIgniter 文档英译中（逐文件串行，禁止并行） + +目标文件：$ARGUMENTS + +## 安全不变量（必须遵守） +1. 未成功备份前，绝不覆盖任何源文件。 +2. 翻译初稿与修订终稿都必须写到 `.ci-translation-tmp/` 下；禁止直接写源 `.rst`。 +3. 覆盖前必须 guard 通过：`python scripts/ci_rst_guard.py `；失败就停止并修复，不得覆盖。 +4. 对每个文件：每个 guard 阶段最多允许 2 次“定点修复”重跑；仍失败则停止并报告具体违规点。 +5. **原子性保证**：任一文件失败，立即停止处理后续文件 + +> hooks 护栏：Write/Edit 触及仓库内 `.rst` 源文件时，将强制检查 backup_ts 与备份存在性；不满足会直接阻止写入。 + +## 预检查（先做完再进入翻译） +- 若用户未传入至少 1 个文件路径：要求补充并停止。 +- 对每个路径：确认存在且为普通文件（建议校验 `.rst` 后缀）。 +- 创建目录（存在则忽略）： + - `.ci-translation-backups/` + - `.ci-translation-tmp/` +- 生成本次会话唯一 backup_ts，写入： + - `.ci-translation-tmp/.ci-translate-meta.json` + 格式：`{"backup_ts":"YYYYMMDD-HHMMSS"}` +- **参数解析**：检查是否包含 --dry-run 参数 + - 如果包含：设置 DRY_RUN=true，从参数列表移除 + - 写入 .ci-translate-meta.json：{"backup_ts": "...", "dry_run": true} + +## 子代理委派契约（必须遵守） +- 翻译初稿：使用显式句式 + - `Use the codeigniter-translator agent to ...` +- 审查：使用显式句式 + - `Use the codeigniter-translation-reviewer agent to ...` +- 若显式句式未触发委派，才允许使用 Task 工具兜底（不要手写 Task JSON）。 + +## 执行流程（逐文件处理） +对每个 FILE（按用户给出的顺序）： + +### 1) 备份（强制使用本次 backup_ts） +- 从 `.ci-translation-tmp/.ci-translate-meta.json` 读取 backup_ts +- 运行： + `python scripts/ci_backup.py --out .ci-translation-backups --timestamp -- FILE` +- 确认备份目录 `.ci-translation-backups//` 已创建；否则停止。 + +### 2) 翻译初稿（写入 TMP） +- 读取 FILE 英文全文 +- 计算 `TMP = .ci-translation-tmp/<与 FILE 相同的相对路径>`，确保父目录存在 +- 委派 translator agent（使用自然语言描述，让 AI 自主执行）： + "Use the codeigniter-translator agent to translate this CodeIgniter documentation from English to Chinese: + + [FILE 的完整英文内容] + + Note: This is an initial draft for guard validation." +- 将输出写入 TMP + +### 3) Guard 校验（初稿） +- 运行：`python scripts/ci_rst_guard.py FILE TMP` +- 若失败：最多 2 次循环修复： + - 把 guard 错误输出 + TMP 当前内容交给 translator + - 要求“仅修复 guard 指出的违规点”，输出完整 RST + - 重新写回 TMP 并重跑 guard +- 仍失败：停止并报告（不得覆盖源文件） + +### 4) 审查（输出审查报告，不改文件） +- 委派审查： + `Use the codeigniter-translation-reviewer agent to review the English source (FILE) and Chinese draft (TMP). Output ONLY a review report with actionable fixes.` +- 将报告保存为：`.ci-translation-tmp/.review.md` + +### 5) 按审查报告修订（写回 TMP） +- 把：英文源全文 + TMP 当前中文全文 + 审查报告全文 交给 translator +- 要求：仅按报告逐条修订；保持 reST 结构零破坏；输出“最终修订后的完整 RST 内容” +- 将输出覆盖写回 TMP + +### 6) Guard 校验（终稿） +- 运行：`python scripts/ci_rst_guard.py FILE TMP` +- 若失败：最多 2 次循环修复（同第 3 步，但这次也把 guard 错误 + 当前 TMP 给 translator 定点修复） +- 仍失败：停止并报告（不得覆盖源文件） + +### 7) 覆盖源文件（条件执行） +- 读取 .ci-translate-meta.json 中的 dry_run 标志 +- 如果 DRY_RUN=true： + [输出] ⊘ [干运行模式] 跳过覆盖 +- 否则：用 TMP 覆盖 FILE + [输出] ✓ 覆盖完成 + +### 8) 写入成功标记（仅当全部文件都成功覆盖后） +- 写入：`.ci-translation-tmp/.ci-translate-result.json` +- 示例： + { + "status": "success", + "backup_ts": "", + "backup_dir": ".ci-translation-backups//", + "tmp_dir": ".ci-translation-tmp/", + "files": [ ...按处理顺序... ] + } +> 中途任何文件失败并停止：不要创建该文件。 + +## 收尾输出（中文） +- 输出本次处理的文件列表 +- 输出备份根目录：`.ci-translation-backups//` diff --git a/.claude/commands/translate.md b/.claude/commands/translate.md deleted file mode 100644 index d7c89197e..000000000 --- a/.claude/commands/translate.md +++ /dev/null @@ -1,42 +0,0 @@ -# CodeIgniter 4 文档翻译工作流 - -执行 CodeIgniter 4 文档的英译中翻译任务，包含翻译和质量审查两个关键步骤。 - -## 工作流程 - -### 第一步：执行翻译 -**必须且只能** 使用 @agent-codeigniter-translator 翻译 @$1 - -翻译要求： -- 严格遵循 ReStructuredText 格式规范 -- 保持代码块、类名、方法名不变 -- 遵循中文文案排版指北 -- 确保术语一致性 - -### 第二步：质量审查 -翻译完成后，**必须** 使用 @agent-codeigniter-translation-reviewer 对翻译结果进行全面审查，原始英文文档在 @$2 - -审查内容： -- 翻译准确性验证 -- 术语一致性检查 -- RestructuredText 格式完整性 -- 中文排版标准合规性 -- 技术准确性验证 - -### 第三步：最终确认 -基于审查结果： -- 如有问题，修正后重新审查 -- 审查通过后，确认翻译完成 - -## 质量标准 - -- **零格式错误**：RST 标记必须完整保留 -- **术语统一**：使用项目既定的中文术语表 -- **技术准确**：所有技术概念正确传达 -- **自然表达**：避免机器翻译痕迹，确保中文表达自然流畅 - -## 注意事项 - -- 使用中文与我交流 -- 严格按照工作流程执行，不可跳过审查步骤 -- 发现问题及时修正，确保最终输出质量 diff --git a/.claude/hooks/ci_translate_bash_guard.py b/.claude/hooks/ci_translate_bash_guard.py new file mode 100755 index 000000000..15943d3b3 --- /dev/null +++ b/.claude/hooks/ci_translate_bash_guard.py @@ -0,0 +1,46 @@ +#!/usr/bin/env python3 +import json +import re +import sys + +DANGEROUS = [ + (r"\brm\s+-rf\b", "禁止 rm -rf（翻译流程不需要）"), + (r"\bgit\s+reset\s+--hard\b", "禁止 git reset --hard（高风险破坏性操作）"), + (r"\bgit\s+clean\s+-f", "禁止 git clean -f（高风险删除文件）"), + (r"\bcurl\b.*\|\s*(sh|bash)\b", "禁止 curl|bash（供应链风险）"), + (r"\bwget\b.*\|\s*(sh|bash)\b", "禁止 wget|bash（供应链风险）"), + (r"\bsudo\b", "禁止 sudo（翻译流程不应需要提权）"), +] + +def eprint(msg: str) -> None: + print(msg, file=sys.stderr) + +def main() -> int: + try: + data = json.load(sys.stdin) + except Exception as e: + eprint(f"[hook] Invalid JSON input: {e}") + return 1 + + if data.get("tool_name") != "Bash": + return 0 + + tool_input = data.get("tool_input", {}) or {} + cmd = tool_input.get("command", "") or "" + if not cmd.strip(): + return 0 + + for pattern, reason in DANGEROUS: + if re.search(pattern, cmd, flags=re.IGNORECASE | re.DOTALL): + eprint( + "[ci-translate hook] 已阻止危险 Bash 命令：\n" + f" {cmd}\n" + f"原因：{reason}\n" + "请改用更安全的替代方式，或仅运行本流程所需命令（mkdir/python/git diff/status）。" + ) + return 2 + + return 0 + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/.claude/hooks/ci_translate_file_protect.py b/.claude/hooks/ci_translate_file_protect.py new file mode 100755 index 000000000..da7dc9b6e --- /dev/null +++ b/.claude/hooks/ci_translate_file_protect.py @@ -0,0 +1,103 @@ +#!/usr/bin/env python3 +import json +import os +import sys +from pathlib import Path + +def eprint(msg: str) -> None: + print(msg, file=sys.stderr) + +def main() -> int: + try: + data = json.load(sys.stdin) + except Exception as e: + eprint(f"[hook] Invalid JSON input: {e}") + return 1 + + tool = data.get("tool_name", "") + tool_input = data.get("tool_input", {}) or {} + file_path = tool_input.get("file_path") + + if tool not in ("Write", "Edit"): + return 0 + if not file_path: + return 0 + + project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())).resolve() + p = Path(file_path) + abs_p = (project_dir / p).resolve() if not p.is_absolute() else p.resolve() + + # 项目外一律阻止 + try: + abs_p.relative_to(project_dir) + except ValueError: + eprint( + "[ci-translate hook] 拒绝写入项目外路径：\n" + f" {abs_p}\n" + "请仅修改仓库内文件。" + ) + return 2 + + rel = abs_p.relative_to(project_dir) + + # 永远允许写入工作目录 + if str(rel).startswith(".ci-translation-tmp") or str(rel).startswith(".ci-translation-backups"): + return 0 + + # 永远禁止触碰敏感路径 + if str(rel).startswith(".git") or rel.name in (".env",): + eprint( + "[ci-translate hook] 拒绝写入敏感路径：\n" + f" {rel}\n" + "这类文件不应在翻译流程中被修改。" + ) + return 2 + + # 只对 .rst 源文档做保护 + if rel.suffix.lower() != ".rst": + return 0 + + meta = project_dir / ".ci-translation-tmp" / ".ci-translate-meta.json" + if not meta.exists(): + eprint( + "[ci-translate hook] 未找到本次会话 meta 文件：\n" + f" {meta}\n" + "请先按命令的“预检查”步骤生成 backup_ts。" + ) + return 2 + + try: + meta_obj = json.loads(meta.read_text(encoding="utf-8")) + backup_ts = meta_obj.get("backup_ts") + except Exception as e: + eprint(f"[ci-translate hook] 读取 meta 失败：{e}") + return 2 + + if not backup_ts: + eprint("[ci-translate hook] meta 中缺少 backup_ts，无法确认备份目录。") + return 2 + + backup_root = project_dir / ".ci-translation-backups" / backup_ts + if not backup_root.exists(): + eprint( + "[ci-translate hook] 未找到备份目录（禁止覆盖源 .rst）：\n" + f" {backup_root}\n" + "请先成功执行备份步骤。" + ) + return 2 + + # 进一步：检查该文件的备份是否存在（按相对路径保存的前提） + backup_file = backup_root / rel + if not backup_file.exists(): + eprint( + "[ci-translate hook] 未找到该文件对应备份（禁止覆盖源 .rst）：\n" + f" 目标：{rel}\n" + f" 期望备份：{backup_file}\n" + "请确认 ci_backup.py 按相对路径保存，或调整 hook 以匹配实际备份布局。" + ) + return 2 + + return 0 + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/.claude/hooks/ci_translate_stop_summary.py b/.claude/hooks/ci_translate_stop_summary.py new file mode 100755 index 000000000..842f724f9 --- /dev/null +++ b/.claude/hooks/ci_translate_stop_summary.py @@ -0,0 +1,73 @@ +#!/usr/bin/env python3 +import json +import os +import shutil +import sys +from pathlib import Path + +def safe_rmtree(path: Path, project_dir: Path): + path = path.resolve() + project_dir = project_dir.resolve() + if project_dir not in path.parents: + raise RuntimeError(f"Refuse to delete outside project: {path}") + if path.name != ".ci-translation-tmp": + raise RuntimeError(f"Refuse to delete non-tmp dir: {path}") + if path.exists(): + shutil.rmtree(path) + +def main(): + raw = sys.stdin.read().strip() or "{}" + hook_input = json.loads(raw) + + if hook_input.get("stop_hook_active") is True: + print(json.dumps({"decision": "approve", "suppressOutput": True}, ensure_ascii=False)) + return + + project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())) + tmp_dir = project_dir / ".ci-translation-tmp" + result_path = tmp_dir / ".ci-translate-result.json" + + if not result_path.exists(): + print(json.dumps({"decision": "approve", "suppressOutput": True}, ensure_ascii=False)) + return + + result = json.loads(result_path.read_text(encoding="utf-8")) + if result.get("status") != "success": + print(json.dumps({"decision": "approve", "suppressOutput": True}, ensure_ascii=False)) + return + + backup_dir = project_dir / result["backup_dir"] + files = result.get("files", []) + + backup_dir.mkdir(parents=True, exist_ok=True) + + summary_path = backup_dir / ".ci-translate-summary.md" + summary_md = ( + "# 收尾总结\n\n" + "## 1) ✅ 本次处理文件\n" + + "".join([f"- {f}\n" for f in files]) + "\n" + "## 2) 📦 备份位置\n" + f"- 备份目录：`{backup_dir}`\n" + f"- 临时目录：`{tmp_dir}`（已在成功后清理）\n\n" + "## 3) 🧾 差异检查建议\n" + "- `git status`\n" + "- `git diff -- `（逐个查看）\n\n" + "## 4) 🔧 后续建议\n" + "- 如项目有 Sphinx 构建：运行最轻量构建验证（尽量启用 warnings-as-errors）\n" + "- 如需提交：建议按文件拆分 commit，便于 review\n" + ) + summary_path.write_text(summary_md, encoding="utf-8") + + safe_rmtree(tmp_dir, project_dir) + tmp_dir.mkdir(parents=True, exist_ok=True) + + print(json.dumps({ + "decision": "block", + "reason": ( + "请继续一步：读取并原样输出以下文件内容（中文 Markdown）作为“收尾总结”，然后再停止：\n" + f"{summary_path.as_posix()}" + ) + }, ensure_ascii=False)) + +if __name__ == "__main__": + main() diff --git a/.gitignore b/.gitignore index 2d879f703..8d73d2268 100644 --- a/.gitignore +++ b/.gitignore @@ -97,3 +97,6 @@ nb-configuration.xml /results/ /source/_build + +.ci-translation-backups/ +.ci-translation-tmp/ diff --git a/.iflow/agents/codeigniter-translation-reviewer.md b/.iflow/agents/codeigniter-translation-reviewer.md deleted file mode 100644 index df0aa345f..000000000 --- a/.iflow/agents/codeigniter-translation-reviewer.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -agent-type: codeigniter-translation-reviewer -name: codeigniter-translation-reviewer -description: 用于审查 CodeIgniter 4 中文翻译文档的准确性、一致性和质量。包括验证技术概念、CodeIgniter 特定术语、代码示例、ReStructuredText 标记、语言质量、文档结构和格式。在翻译完成后使用此代理确保符合项目标准后再合并。示例：翻译 CLI 文档的新章节后，使用此代理审查翻译是否符合项目指南和技术准确性。 -when-to-use: 当你需要审查 CodeIgniter 4 中文翻译文档的准确性、一致性和质量时使用此代理。包括验证技术概念、CodeIgniter 特定术语、代码示例、ReStructuredText 标记、语言质量、文档结构和格式。在翻译完成后使用此代理确保符合项目标准后再合并。示例：翻译 CLI 文档的新章节后，使用此代理审查翻译是否符合项目指南和技术准确性。 -allowed-tools: glob, list_directory, multi_edit, read_file, read_many_files, replace, run_shell_command, search_file_content, todo_read, todo_write, web_fetch, web_search, write_file -inherit-tools: true -inherit-mcps: true -color: blue ---- - -你是一个专门负责审查 CodeIgniter 4 文档中文翻译的代理。你的职责是对英文到中文的翻译进行全面的质量保证，确保翻译在准确性、一致性和可读性方面达到最高标准。 - -**核心职责：** - -**翻译准确性审查：** -- 验证所有技术概念是否正确翻译并保持原意 -- 检查 CodeIgniter 特定术语是否根据既定规范一致翻译 -- 确保代码示例、函数名和 API 引用保持不变且格式正确 -- 验证所有 ReStructuredText 标记和 Sphinx 指令完全保留 - -**语言质量评估：** -- 应用项目 translation-guide.md 中定义的中文文案标准 -- 确保自然流畅的中文表达同时保持技术精确性 -- 检查中文标点符号、间距和格式规范的正确使用 -- 验证整个文档中术语使用的一致性 - -**结构和格式验证：** -- 确认所有 RST 标记结构完整（标题、列表、代码块、交叉引用） -- 验证 Sphinx 指令功能正确（.. note::, .. warning::, .. code-block::） -- 检查内部链接和交叉引用是否正常工作 -- 确保缩进和格式模式一致 - -**技术准确性验证：** -- 验证 PHP 代码示例保持正确的语法 -- 确认配置示例和文件路径准确 -- 检查版本特定信息是否正确翻译 -- 确保兼容性说明和警告清晰传达 - -**审查流程：** -1. 通读整个翻译文档，检查整体流畅性和连贯性 -2. 对比关键技术人员与原始英文版本验证准确性 -3. 检查与之前翻译和既定术语的一致性 -4. 验证所有标记和格式元素 -5. 通过确保文档可以被 Sphinx 处理来测试构建兼容性 - -**输出格式：** -提供结构化审查报告，包括： -- 总体评估（通过/需要修订/重大问题） -- 发现的具体问题及行号或章节引用 -- 术语一致性说明 -- 格式或标记问题 -- 改进建议 -- 下一步行动的最终建议 - -在识别问题时，将其分类为： -- **严重**：改变含义或破坏功能的翻译错误 -- **重要**：术语不一致或重要的语言问题 -- **轻微**：风格改进或小的格式调整 - -你应该既彻底又建设性，提供具体、可操作的反馈，帮助提高翻译质量，同时尊重译者的工作。始终参考项目的 .iflow/agents/codeigniter-translator.md 获取特定的规范和要求。专注于被审查文档的内容，除非偏离 RST 标准，否则避免评论文档结构本身。 diff --git a/.iflow/agents/codeigniter-translator.md b/.iflow/agents/codeigniter-translator.md deleted file mode 100644 index 8d8c55058..000000000 --- a/.iflow/agents/codeigniter-translator.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -agent-type: codeigniter-translator -name: codeigniter-translator -description: 用于将英文 CodeIgniter 文档翻译为中文，同时保持 ReStructuredText 格式。当你需要为中文 PHP 开发者提供出版级技术翻译，平衡准确性和可读性时，请使用此代理。示例：将 CodeIgniter 用户指南的新章节从英文翻译为中文，或更新现有翻译文档以匹配新的英文内容。 -when-to-use: 用于将英文 CodeIgniter 文档翻译为中文，同时保持 ReStructuredText 格式。当你需要为中文 PHP 开发者提供出版级技术翻译，平衡准确性和可读性时，请使用此代理。示例：将 CodeIgniter 用户指南的新章节从英文翻译为中文，或更新现有翻译文档以匹配新的英文内容。 -allowed-tools: glob, list_directory, multi_edit, read_file, read_many_files, replace, run_shell_command, search_file_content, todo_read, todo_write, web_fetch, web_search, write_file -inherit-tools: true -inherit-mcps: true -color: purple ---- - -你是具备深厚 PHP 框架 CodeIgniter 和中文技术写作专业知识的高级技术文档翻译专家。你的使命是提供出版级质量的中文翻译，在保持 ReStructuredText 格式绝对一致的同时，完美平衡技术准确性和读者理解性。 - -## 核心翻译理念 - -### 以读者为中心的方法 -- **主要目标**：让中文技术读者能够高效准确地学习 CodeIgniter -- **可读性**：使复杂的技术概念易于理解而不牺牲精确性 -- **一致性**：在所有文档中保持术语和风格的统一 -- **专业性**：提供与原始中文技术文档无法区分的翻译质量 - -### 技术卓越标准 -- **零信息丢失**：每个技术细节、示例和细微差别都必须保留 -- **格式完整性**：ReStructuredText 结构必须完全不变 -- **代码保护**：所有代码元素保持原始英文 -- **上下文准确性**：翻译反映对 CodeIgniter 架构和 PHP 概念的深入理解 - -## 翻译指南 - -### 1. 中文语言标准 - -#### 代词使用 -- **始终**使用非正式的"你"和"你的"（从不使用正式的"您/您的"） -- 保持开发者在技术文档中期望的直接、专业语调 - -#### 中文表达优化（反机器翻译） -- **消除冗余代词**：避免不必要的"你"、"你的"、"这"，这些会使句子冗长 -- **自然流畅**：移除上下文中暗示的代词以获得更流畅的阅读体验 -- **避免机器翻译模式**：将机械翻译转换为自然的中文表达 -- **使用主动语态**：在适当时优先使用直接陈述而非被动结构 -- **上下文适应**：根据中文技术写作惯例调整句子结构 -- 示例： - - ✅ 推荐："使用 Session 库存储用户数据"（直接、简洁） - - ❌ 避免："你可以使用 Session 库来存储你的用户数据"（冗余代词） - - ✅ 推荐："配置文件位于 `app/Config/` 目录"（清晰、直接） - - ❌ 避免："你的配置文件位于 `app/Config/` 这个目录中"（不必要的词语） - - ✅ 推荐："数据库连接失败时会抛出异常"（自然中文） - - ❌ 避免："当数据库连接失败的时候，系统将会抛出一个异常"（冗长、机器化） - - ✅ 推荐："支持多种缓存驱动"（简洁） - - ❌ 避免："它支持多种不同的缓存驱动程序"（冗余词语） - -#### 排版标准（严格遵守） -- **中英间距**：在中文字符和英文单词之间添加半角空格 - - ✅ 正确："在 CodeIgniter 框架中使用 Session 库" - - ❌ 错误："在CodeIgniter框架中使用Session库" -- **中数间距**：在中文字符和数字之间添加半角空格 - - ✅ 正确："数据库连接池支持 100 个并发连接" - - ❌ 错误："数据库连接池支持100个并发连接" -- **单位格式**：数字和单位之间不加空格（MB, KB, ms 等） - - ✅ 正确："内存占用为 512MB，响应时间低于 50ms" - - ❌ 错误："内存占用为 512 MB，响应时间低于 50 ms" -- **中文标点**：中文句子使用全角标点符号（，。！？；：） - - ✅ 正确："请注意，这个功能在生产环境中非常重要。" - - ❌ 错误："请注意,这个功能在生产环境中非常重要." -- **英文标点**：中文文本中的英文短语使用半角标点符号 -- **品牌/技术术语大写**：保持适当的大写 - - ✅ 正确："使用 GitHub、MySQL、CodeIgniter、API 等技术" - - ❌ 错误："使用 github、mysql、codeigniter、api 等技术" -- **不重复标点**：从不重复标点符号以示强调 - - ✅ 正确："这个功能非常重要！" - - ❌ 错误："这个功能非常重要！！！" - -### 2. ReStructuredText 格式保护（关键） - -#### 指令保护 -- **从不**翻译或修改 RST 指令： - - `.. note::`, `.. warning::`, `.. important::`, `.. tip::` - - `.. literalinclude::`, `.. code-block::`, `.. contents::` - - `.. versionadded::`, `.. versionchanged::`, `.. deprecated::` - - 句尾的双冒号(::) - - 所有自定义 CodeIgniter 指令 -- **保持不变**：缩进、空格、间距 -- **维护结构**：代码块、表格、列表、交叉引用 - -#### 需要特别注意的格式元素 -- **代码块**：从不翻译内容，精确保持缩进 -- **行内代码**：保持所有反引号包装的代码为英文 -- **交叉引用**：保持 `:doc:`、`:meth:`、`:class:` 链接目标为英文 -- **表格结构**：保持列对齐和 RST 表格语法 -- **列表格式**：保持项目符号、编号列表、定义列表 -- **章节标题**：翻译内容但保持并维护下划线字符及其数量（=, -, ~） - -### 3. CodeIgniter 特定翻译标准 - -#### 核心术语（使用英文 - 从不翻译） -- 框架组件名称：`Session`、`Email` -- 类名：`BaseController`、`Model`、`Entity`、`Config` -- 方法/属性名：`insert()`、`find()`、`where()`、`join()` -- 常量：`ENVIRONMENT`、`APPPATH`、`ROOTPATH` -- 配置键：`database.default.hostname` - -#### 标准中文翻译 -- "helper" → "辅助函数" -- "library" → "库" -- "model" → "模型" -- "controller" → "控制器" -- "view" → "视图" -- "route/routing" → "路由" -- "middleware" → "中间件" -- "filter" → "过滤器" -- "validation" → "验证" -- "migration" → "迁移" -- "seeder" → "数据填充" -- "cookie" → "Cookie" -- "cookies" → "Cookie" -- "constant" → "常量" -- "query builder" → "查询构建器" - -#### 上下文相关术语 -- "method" → "方法"（类方法）/ "方式"（方法、途径） -- "property" → "属性"（类属性）/ "特性"（特征） -- "parameter" → "参数"（函数参数）/ "设置"（配置设置） -- "return" → "返回"（函数返回）/ "回到"（导航） - -### 4. 翻译质量保证 - -#### 翻译前分析 -- **文档结构映射**：开始前识别所有 RST 元素 -- **术语提取**：列出所有技术术语以进行一致性检查 -- **代码块识别**：标记所有代码部分以避免翻译 - -#### 翻译执行 -- **段落级翻译**：保持逻辑流程和上下文 -- **技术准确性验证**：确保所有概念都正确传达 -- **交叉引用验证**：验证所有内部链接保持功能正常 -- **示例一致性**：确保翻译文本与代码示例匹配 -- **流畅性优化**：重写翻译以使其在中文中自然专业地阅读 -- **反翻译标记**：移除明显的机器翻译痕迹（过多的"的"、别扭的句子结构） -- **母语者验证**：确保输出读起来像由母语中文技术作者编写 - -#### 翻译后审查 -- **格式验证**：确认 RST 结构与原始匹配 -- **排版检查**：应用所有中文排版标准 -- **术语一致性**：验证整个文档中术语使用的一致性 -- **可读性评估**：确保流畅、自然的中文表达 -- **技术正确性**：验证所有技术信息的准确性 - -## 高级翻译技术 - -### 自然中文表达 -- **句子结构优化**：适应中文阅读模式同时保持含义 -- **逻辑流程增强**：使用中文过渡短语以更好理解 -- **读者引导**：以帮助中文学习者的方式组织信息 -- **习语表达**：在适当时使用自然的中文习语和表达 -- **节奏和韵律**：确保翻译具有自然的中文阅读节奏，使用合理的句子断句以避免过长句子 -- **避免直译**：将英文思维模式转换为中文逻辑流程 - -### 上下文感知翻译 -- **跨文档一致性**：在整个用户指南中保持术语一致性 -- **渐进复杂性**：考虑读者通过文档的学习过程 -- **文化适应**：解释中文开发者不熟悉的概念 -- **最佳实践强调**：清楚地突出中文开发团队的重要实践 - -## 输出要求 - -### 格式合规性 -- **无解释性注释**：从不添加翻译注释或解释 -- **精确格式化**：完全匹配原始缩进、间距和结构 -- **完整内容**：包含源文档的每个元素 - -### 质量标准 -- **专业级别**：适合官方技术文档的翻译质量 -- **零错误**：零格式错误、术语不一致或翻译错误 -- **读者优化**：为中文 PHP 开发者理解而优化 -- **可维护性**：一致的风格使未来更新和修订变得容易 - -## 严格性能要求 - -你必须展示： -- **深度 CodeIgniter 专业知识**：对框架概念和架构的全面理解 -- **高级中文技术写作**：母语级中文技术文档技能 -- **RST 精通**：专家级 ReStructuredText 格式和 Sphinx 文档系统知识 -- **质量执着**：对制作完美技术翻译的坚定承诺 -- **读者同理心**：清楚了解中文开发者的学习需求和偏好 - -**最终提醒**：你的翻译将被数千名中文开发者用于学习 CodeIgniter。每个词、格式元素和技术细节都必须完美。对错误、不一致或格式问题零容忍。 - -**质量基准**：你的翻译应该与经验丰富的中文技术作者的原创内容无法区分。避免任何"翻译味"的痕迹 - 文本必须在保持完整技术准确性的同时，在中文中自然流畅地阅读。 diff --git a/.kilocodemodes b/.kilocodemodes deleted file mode 100644 index 80f8477ac..000000000 --- a/.kilocodemodes +++ /dev/null @@ -1,52 +0,0 @@ -customModes: - - slug: ci-translator - name: CI 文档翻译 - description: CI 文档翻译 - roleDefinition: |- - # 角色 - - 你是一位资深计算机技术文档翻译专家，尤其精通英文 PHP 框架 CodeIgniter 用户手册到简体中文的精准翻译。你以严谨细致的专业精神著称，追求译文在语言和格式上均完美匹配原文，最终交付最高质量的技术文档。 - - ## 专业技能 - - ### 技能 1：卓越的英中技术翻译能力 - - - 英文人称代词 “you”、“your” 务必对应翻译为中文 “你”、“你的”，保持技术文档的直接性和专业性，禁用敬语 “您”。 - - 熟练应用中英文排版规范，中文与英文、中文与数字间自觉添加半角空格，除需保持原文的内容以外，标点符号使用全角标点符号，优化文档可读性。 - - 具备出色的上下文理解力，从全文把握技术概念和语境，确保译文在术语和逻辑上高度准确且一致。 - - 保持原文段落结构。 - - 杜绝任何原文内容遗漏。 - - ### 技能 2：精确还原 ReStructuredText 源文件格式 - - - 对格式高度敏感，精确识别并完整保留 ReStructuredText 格式，严禁任何形式的修改或调整。 - - 精通 ReStructuredText 标记语言，熟练运用其规范进行翻译，确保文档结构与原文完全一致。 - - **务必** 原样保留 ReStructuredText 指令，如 “.. note::”、“.. warning::”、“.. important::”、“.. literalinclude::”、“.. contents::”、“.. versionadded::”，包括原始大小写和拼写，**禁止翻译或改动**。 - - **特别注意** 保留段落结尾的双冒号 (::) 和句首连续空格，它们是 ReStructuredText 语法组成部分，并非错误。 - - 不得增删任何格式符号或指令。 - - 保留原文换行。 - - ### 技能 3：精准处理技术术语与代码 - - - 严格遵守既定术语规范。 存在明确中文约定的术语直接采用；无约定术语，依据行业惯例和上下文专业判断翻译，不可生搬硬造。 - - 代码与文本内容界限清晰。 代码块、代码示例、类名、函数名、变量名等代码元素 **一律不可翻译**，必须完整保留英文原文。 - - 提及 CodeIgniter 框架 Session 类库时，**始终使用英文原文 “Session”**，确保术语统一性和专业性。 - - helper 原则上翻译成辅助函数 - - ### 技能 4：精湛的译文审校与优化能力 - - - 从中文技术文档读者角度审视译文，充分考虑中文阅读习惯和理解方式，确保语句流畅自然、逻辑清晰易懂，避免任何生硬、晦涩或机器翻译痕迹。 - - 在绝对忠于原文和不丢失格式等内容的前提下，允许并鼓励采用更符合中文表达习惯的方式进行翻译，提升文档学习效率和用户体验，最终有效传递技术知识。 - - ## 严格约束 - - - 坚守最高翻译质量标准，严格执行所有上述规范。 - - 鉴于文档技术深度，你 **必须** 扎实掌握计算机科学领域及 PHP 框架 CodeIgniter 的基础知识和深入理解，熟悉核心概念、技术原理和常用术语，这是保证译文质量的根本前提。 - - 不能编造原文不存在的内容，也不能丢失任何知识点。 - groups: - - read - - edit - - browser - - command - - mcp - source: project diff --git a/.vscode/settings.json b/.vscode/settings.json index 3aaf448e6..6e92f5a69 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,5 +1,6 @@ { "editor.tabSize": 4, - "esbonio.sphinx.confDir": "${workspaceFolder}/source", "editor.fontFamily": "Iosevka Fixed", + "restructuredtext.pythonRecommendation.disabled": true, + "claudeCode.useTerminal": true, } diff --git a/IFLOW.md b/IFLOW.md deleted file mode 100644 index 8eb776939..000000000 --- a/IFLOW.md +++ /dev/null @@ -1,130 +0,0 @@ -# CodeIgniter 4 中文用户指南项目 - -## 项目概述 - -这是一个 CodeIgniter 4 中文用户指南的翻译项目，旨在为中文开发者提供完整的 CodeIgniter 4 框架文档。该项目使用 Sphinx 文档系统构建，生成 HTML、PDF 等多种格式的文档。 - -项目托管在 GitHub 上，使用 GitHub Actions 自动构建和部署到 GitHub Pages。 - -## 项目类型 - -这是一个技术文档翻译项目，基于 ReStructuredText (RST) 格式的文档源文件，使用 Sphinx 构建系统生成最终文档。 - -## 目录结构 - -``` -. -├── source/ # 文档源文件目录 -│ ├── index.rst # 主页文档 -│ ├── intro/ # 介绍部分 -│ ├── installation/ # 安装指南 -│ ├── tutorial/ # 教程 -│ ├── concepts/ # 概念说明 -│ ├── general/ # 通用主题 -│ ├── incoming/ # 请求处理 -│ ├── outgoing/ # 响应处理 -│ ├── database/ # 数据库相关 -│ ├── models/ # 模型相关 -│ ├── dbmgmt/ # 数据库管理 -│ ├── libraries/ # 库文档 -│ ├── helpers/ # 辅助函数 -│ ├── testing/ # 测试相关 -│ ├── cli/ # 命令行接口 -│ ├── extending/ # 扩展框架 -│ └── changelogs/ # 更新日志 -├── build/ # 构建输出目录 -│ ├── html/ # HTML 输出 -│ └── latex/ # LaTeX 输出 -├── _static/ # 静态资源文件 -├── _templates/ # 模板文件 -├── requirements.txt # Python 依赖项 -├── conf.py # Sphinx 配置文件 -├── Makefile # 构建脚本 -├── Dockerfile # Docker 配置 -└── README.md # 项目说明 -``` - -## 构建和运行 - -### 依赖安装 - -```bash -# 安装 Python 依赖 -pip install -r requirements.txt -``` - -### 本地构建 - -```bash -# 构建 HTML 文档 -make html - -# 构建 PDF 文档 -make latexpdf -``` - -### Docker 构建 - -```bash -# 构建 Docker 镜像 -docker build -t ci4 . - -# 运行构建 -docker run -t --rm -v $(pwd):/ci ci4 -``` - -## 开发规范 - -### 翻译规范 - -1. 严格遵循[中文文案排版指北](http://mazhuang.org/wiki/chinese-copywriting-guidelines/) -2. 遵循项目特定的[文档翻译指南](translation-guide.md) -3. 使用"你"而非"您" -4. 保持技术术语的一致性 -5. 保留 ReStructuredText 格式结构 - -### ReStructuredText 格式要求 - -1. 保留所有 RST 指令（如 `.. note::`, `.. warning::` 等） -2. 保持代码块内容为英文 -3. 保持交叉引用链接为英文 -4. 保留表格和列表结构 - -### 术语翻译标准 - -- "helper" → "辅助函数" -- "library" → "库" -- "model" → "模型" -- "controller" → "控制器" -- "view" → "视图" -- "route/routing" → "路由" - -## 贡献指南 - -1. Fork 主仓库 -2. 翻译完成后自己 Review 两遍 -3. 提交 PR 并使用 --signoff 签名 -4. 遵循中文文案排版规范 - -## 自动化流程 - -- 使用 GitHub Actions 自动构建文档 -- 构建结果部署到 GitHub Pages -- 生成 HTML 和 PDF 两种格式 - -## 配置文件说明 - -- `conf.py`: Sphinx 配置文件，包含主题、语言、扩展等设置 -- `requirements.txt`: Python 依赖项列表 -- `Makefile`: 构建脚本 -- `Dockerfile`: Docker 构建配置 - -## 构建环境要求 - -- Python 3.7+ -- Sphinx 5.3.0+ -- TeXLive (用于生成 PDF) - -## 预览地址 - -[在线预览最新文档](https://codeigniter-chinese.github.io/codeigniter4-user-guide/) diff --git a/scripts/ci_backup.py b/scripts/ci_backup.py new file mode 100644 index 000000000..8d8d2a5db --- /dev/null +++ b/scripts/ci_backup.py @@ -0,0 +1,36 @@ +import argparse +import os +import shutil +import sys +from pathlib import Path + +def main(): + parser = argparse.ArgumentParser(description='Backup files with timestamp.') + parser.add_argument('--out', required=True, help='Output directory for backups') + parser.add_argument('--timestamp', required=True, help='Timestamp string') + parser.add_argument('file', help='File to backup') + + args = parser.parse_args() + + src_file = Path(args.file) + if not src_file.exists(): + print(f"Error: Source file {src_file} does not exist.") + sys.exit(1) + + # Structure: out_dir/timestamp/original_path_structure + # e.g. .ci-translation-backups/20231010-120000/source/intro/psr.rst + + dest_dir = Path(args.out) / args.timestamp / src_file.parent + dest_dir.mkdir(parents=True, exist_ok=True) + + dest_file = dest_dir / src_file.name + + try: + shutil.copy2(src_file, dest_file) + print(f"Backed up {src_file} to {dest_file}") + except Exception as e: + print(f"Error backing up file: {e}") + sys.exit(1) + +if __name__ == "__main__": + main() diff --git a/scripts/ci_rst_guard.py b/scripts/ci_rst_guard.py new file mode 100644 index 000000000..6af44d1ae --- /dev/null +++ b/scripts/ci_rst_guard.py @@ -0,0 +1,75 @@ +import argparse +import sys +import re +from pathlib import Path + +def extract_code_blocks(content): + # Basic regex to find code blocks. + # This is a simplified check. In a real scenario, we might use docutils. + # Pattern looks for :: followed by indented block or .. code-block:: + + # We will strictly check for '.. code-block::' and '.. literalinclude::' + # and maybe '::' at the end of paragraphs if used for code. + + # For this guard, let's focus on explicit directives which are most critical to preserve. + directives = re.findall(r'\.\.\s+(code-block|literalinclude|php:class|php:method|php:function)::.*?', content, re.MULTILINE) + return directives + +def main(): + parser = argparse.ArgumentParser(description='Guard RST file structure.') + parser.add_argument('src', help='Original source file') + parser.add_argument('tmp', help='Translated temporary file') + + args = parser.parse_args() + + src_path = Path(args.src) + tmp_path = Path(args.tmp) + + if not src_path.exists(): + print(f"Error: Source file {src_path} does not exist.") + sys.exit(1) + + if not tmp_path.exists(): + print(f"Error: Temp file {tmp_path} does not exist.") + sys.exit(1) + + try: + src_content = src_path.read_text(encoding='utf-8') + tmp_content = tmp_path.read_text(encoding='utf-8') + except Exception as e: + print(f"Error reading files: {e}") + sys.exit(1) + + # Check 1: File is not empty + if not tmp_content.strip(): + print("Error: Translated file is empty.") + sys.exit(1) + + # Check 2: Basic directive counts (lax check to allow some changes but warn on drastic ones) + # Actually, the instructions say "绝不翻译代码块", so we expect code blocks to remain. + # But content might change slightly if arguments change (unlikely for strict translation). + + src_blocks = extract_code_blocks(src_content) + tmp_blocks = extract_code_blocks(tmp_content) + + # It is hard to compare exactly without parsing, but we can check counts. + # If source has code blocks, temp should likely have them too. + + if len(src_blocks) != len(tmp_blocks): + print(f"Warning: Mismatch in directive count. Source: {len(src_blocks)}, Translated: {len(tmp_blocks)}") + # We won't fail hard on this simplistic check unless strictly required, + # but the prompt implies "Guard 校验... 若失败". + # Let's be strict about total loss of structure. + if len(src_blocks) > 0 and len(tmp_blocks) == 0: + print("Failure: All code blocks/directives lost in translation.") + sys.exit(1) + + # Check 3: Preserved specific patterns + # e.g. php:class, php:method etc should likely be preserved. + + # If we are good, exit 0 + print("Guard check passed.") + sys.exit(0) + +if __name__ == "__main__": + main() diff --git a/source/cli/cli_generators.rst b/source/cli/cli_generators.rst index ab44a7bbf..bb724cedd 100644 --- a/source/cli/cli_generators.rst +++ b/source/cli/cli_generators.rst @@ -47,7 +47,7 @@ make:cell 参数： ========= -* ``name``：Cell 类的名称。应该使用 PascalCase。 **[必需] ** +* ``name``：Cell 类的名称。应该使用 PascalCase。**[必需]** 选项： ======== @@ -67,13 +67,13 @@ make:command 参数： ========= -* ``name``：命令类的名称。 **[必需] ** +* ``name``：命令类的名称。**[必需]** 选项： ======== * ``--command``：在 spark 中运行的命令名称。默认为 ``command:name``。 * ``--group``：命令的组/命名空间。基本命令默认为 ``App``，生成器命令默认为 ``Generators``。 -* ``--type``：命令的类型，可以是 ``basic``（基本）命令或 ``generator``（生成器）命令。默认为 ``basic``。 +* ``--type``：命令的类型，可以是 ``basic`` （基本）命令或 ``generator`` （生成器）命令。默认为 ``basic``。 * ``--namespace``：设置根命名空间。默认为 ``APP_NAMESPACE`` 的值。 * ``--suffix``：将组件后缀附加到生成的类名上。 * ``--force``：设置此标志以覆盖目标位置的现有文件。 @@ -91,7 +91,7 @@ make:config 参数： ========= -* ``name``：配置类的名称。 **[必需] ** +* ``name``：配置类的名称。**[必需]** 选项： ======== @@ -112,7 +112,7 @@ make:controller 参数： ========= -* ``name``：控制器类的名称。 **[必需] ** +* ``name``：控制器类的名称。**[必需]** 选项： ======== @@ -137,7 +137,7 @@ make:entity 参数： ========= -* ``name``：实体类的名称。 **[必需] ** +* ``name``：实体类的名称。**[必需]** 选项： ======== @@ -158,7 +158,7 @@ make:filter 参数： ========= -* ``name``：过滤器类的名称。 **[必需] ** +* ``name``：过滤器类的名称。**[必需]** 选项： ======== @@ -179,7 +179,7 @@ make:model 参数： ========= -* ``name``：模型类的名称。 **[必需] ** +* ``name``：模型类的名称。**[必需]** 选项： ======== @@ -203,7 +203,7 @@ make:seeder 参数： ========= -* ``name``：数据填充类的名称。 **[必需] ** +* ``name``：数据填充类的名称。**[必需]** 选项： ======== @@ -228,7 +228,7 @@ make:test 参数： ========= -* ``name``：测试类的名称。 **[必需] ** +* ``name``：测试类的名称。**[必需]** 选项： ======== @@ -248,7 +248,7 @@ make:migration 参数： ========= -* ``name``：迁移类的名称。 **[必需] ** +* ``name``：迁移类的名称。**[必需]** 选项： ======== @@ -272,7 +272,7 @@ make:validation 参数： ========= -* ``name``：验证类的名称。 **[必需] ** +* ``name``：验证类的名称。**[必需]** 选项： ======== diff --git a/source/concepts/http.rst b/source/concepts/http.rst index 50f76a7da..a0443f8ca 100755 --- a/source/concepts/http.rst +++ b/source/concepts/http.rst @@ -56,7 +56,7 @@ HTTP 是用于描述这种交换约定的术语，其全称为超文本传输协 .. literalinclude:: http/001.php -请求类在后台为你做了大量工作，你无需为此担心。``isAJAX()`` 和 ``isSecure()`` 方法会检查多种不同的方式来确定正确的答案。 +Request 类在后台为你做了大量工作，你无需为此担心。``isAJAX()`` 和 ``isSecure()`` 方法会检查多种不同的方式来确定正确的答案。 .. note:: ``isAJAX()`` 方法依赖于 ``X-Requested-With`` 头，但在某些情况下，通过 JavaScript 发起的 XHR 请求（例如 fetch）默认不会发送该头。请参阅 :doc:`AJAX 请求 ` 章节，了解如何避免此问题。 diff --git a/source/database/call_function.rst b/source/database/call_function.rst index 546bb692a..9cb61ae24 100755 --- a/source/database/call_function.rst +++ b/source/database/call_function.rst @@ -9,21 +9,20 @@ $db->callFunction() =================== -此函数使你可以以与平台无关的方式调用 PHP 数据库函数,这些函数不是 CodeIgniter 原生支持的。 -例如,假设你想调用 ``mysql_get_client_info()`` 函数,CodeIgniter 原生不支持此函数。你可以这样做: +此函数允许你以独立于平台的方式调用 CodeIgniter 未原生支持的 PHP 数据库函数。例如，假设你想调用 CodeIgniter **未原生支持** 的 ``mysql_get_client_info()`` 函数，你可以这样做： .. literalinclude:: call_function/001.php -你必须在第一个参数中提供函数名称,不带 ``mysql_`` 前缀。前缀会根据当前使用的数据库驱动自动添加。这允许你在不同的数据库平台上运行相同的函数。显然,并非所有函数调用在所有平台上都是相同的,所以就可移植性而言,此函数的用途有限。 +在第一个参数中，你必须提供函数名称，但**不需要**包含 ``mysql_`` 前缀。前缀会根据当前使用的数据库驱动程序自动添加。这允许你在不同的数据库平台上运行相同的函数。显然，并非所有函数调用在不同平台之间都是相同的，因此该函数在可移植性方面的有用性是有限的。 -被调用函数需要的任何参数都将添加到第二个参数中。 +你调用的函数所需的任何参数都将添加到第二个参数中。 .. literalinclude:: call_function/002.php -你通常需要提供数据库连接 ID 或数据库结果 ID。可以使用以下方式访问连接 ID: +通常，你需要提供数据库连接 ID 或数据库结果 ID。连接 ID 可以通过以下方式访问： .. literalinclude:: call_function/003.php -可以从结果对象内部访问结果 ID,如下所示: +结果 ID 可以从结果对象中访问，如下所示： .. literalinclude:: call_function/004.php diff --git a/source/database/configuration.rst b/source/database/configuration.rst index f9db62489..69d2bcdee 100755 --- a/source/database/configuration.rst +++ b/source/database/configuration.rst @@ -7,44 +7,47 @@ :depth: 3 .. note:: - 请参阅 :ref:`requirements-supported-databases` 以获取当前支持的数据库驱动。 + 有关当前支持的数据库驱动，请参阅 :ref:`requirements-supported-databases`。 *********** 配置文件 *********** -CodeIgniter 有一个配置文件,可让你存储数据库连接值(用户名、密码、数据库名称等)。配置文件位于 **app/Config/Database.php**。你也可以在 **.env** 文件中设置数据库连接值。下面详细介绍。 +CodeIgniter 提供了一个配置文件，用于存储你的数据库连接信息（用户名、密码、数据库名等）。该配置文件位于 **app/Config/Database.php**。你也可以在 **.env** 文件中设置数据库连接值。更多详细信息，请参见下文。 设置默认数据库 ======================== -配置设置存储在一个类属性中,该属性是一个数组,原型如下: +配置设置存储在一个类属性中，该属性是一个具有以下原型的数组： .. literalinclude:: configuration/001.php -类属性的名称是连接名称,在连接时可以用作指定组名。 +类属性的名称即为连接名，可以在连接时使用该名称来指定组名。 -.. note:: SQLite3 数据库的默认位置是 **writable** 文件夹。如果要更改位置，则必须设置新文件夹（例如，'database' => WRITEPATH . 'db/database_name.db'）的完整路径。 +.. note:: SQLite3 数据库的默认位置是 **writable** 目录。 + 如果要更改位置，必须设置新目录的完整路径（例如，'database' => WRITEPATH . 'db/database_name.db'）。 DSN --- -某些数据库驱动程序（如 Postgre、OCI8）需要完整的 DSN（Data Source Name）字符串才能连接。但是，如果你没有为需要 DSN 字符串的驱动程序指定 DSN 字符串，CodeIgniter 将尝试使用其余提供的设置来构建它。 +某些数据库驱动（如 Postgre、OCI8）需要完整的 DSN（数据源名称）字符串才能连接。 +但如果对于需要 DSN 的驱动你未指定 DSN 字符串，CodeIgniter 将尝试使用其余提供的设置来构建它。 -如果指定了 DSN,你应该使用 ``'DSN'`` 配置设置,就像你正在使用驱动程序的底层原生 PHP 扩展一样,如下所示: +如果指定了 DSN，你应该使用 ``'DSN'`` 配置设置，就像使用驱动程序底层的原生 PHP 扩展一样，如下所示： .. literalinclude:: configuration/002.php :lines: 11-15 -通用方式的 DSN +通用 DSN 格式 ^^^^^^^^^^^^^^^^^^^^^^^ -你还可以以通用方式(URL 格式)设置 DSN。在这种情况下,DSN 必须具有以下原型: +你也可以以通用格式（类似 URL）设置 DSN。在这种情况下，DSN 必须具有以下原型： .. literalinclude:: configuration/003.php :lines: 11-14 -要使用 DSN 字符串的通用版本覆盖默认配置值,请将配置变量作为查询字符串添加: +使用通用版本的 DSN 字符串连接时，若要覆盖默认的配置值， +请将配置变量作为查询字符串添加： .. literalinclude:: configuration/004.php :lines: 11-15 @@ -52,117 +55,129 @@ DSN .. literalinclude:: configuration/010.php :lines: 11-15 -.. note:: 如果你提供了一个 DSN 字符串,但缺少配置字段中存在的一些有效设置(例如数据库字符集),CodeIgniter 将会追加它们。 +.. note:: 如果你提供了 DSN 字符串但缺少某些有效设置（例如，数据库字符集），而这些设置存在于其余的配置字段中，CodeIgniter 将会追加它们。 故障转移 --------- -你还可以针对主连接由于某些原因无法连接的情况指定故障转移。可以通过像这样为连接设置故障转移来指定故障转移: +你也可以指定故障转移，以应对主连接因某种原因无法连接的情况。 +这些故障转移可以通过为连接设置 failover 来指定，如下所示： .. literalinclude:: configuration/005.php -你可以指定任意多个故障转移。 +你可以根据需要指定任意数量的故障转移。 设置多个数据库 ========================== -你可以可选地存储多个连接值集。例如,如果你在单个安装下运行多个环境(开发、生产、测试等),则可以为每个环境设置一个连接组,然后根据需要在组之间切换。例如,要设置“测试”环境,你可以这样做: +你可以选择性地存储多组连接值。 +例如，如果你在单个安装下运行多个环境（开发、生产、测试等）， +可以为每个环境设置一个连接组，然后根据需要在各组之间切换。例如，要设置一个“test”环境，你可以这样做： .. literalinclude:: configuration/006.php -然后,要在全局范围内告诉系统使用该组,请设置配置文件中的此变量: +然后，要全局告知系统使用该组，你需要设置配置文件中的这个变量： .. literalinclude:: configuration/007.php -.. note:: 名称 ``test`` 任意的。它可以是你想要的任何内容。默认情况下,我们已经将主连接的名称设置为 ``default``,但它也可以重命名为与项目更相关的名称。 +.. note:: 名称 ``test`` 是任意的，你可以将其设置为任何名称。 + 默认情况下，我们为主连接使用了 ``default`` 这个词， + 但它也可以根据你的项目需求重命名为更相关的名称。 -自动更改数据库 +自动切换数据库 ================================ -你可以修改配置文件以检测环境并自动更新 ``defaultGroup`` 值为正确的值,方法是在类构造函数中添加所需的逻辑: +你可以修改配置文件，通过在类的构造函数中添加必要的逻辑来检测环境，并自动将 ``defaultGroup`` 的值更新为正确的组： .. literalinclude:: configuration/008.php .. _database-config-with-env-file: ************************** -使用 .env 文件配置 +使用 .env 文件进行配置 ************************** -你还可以在 **.env** 文件中保存你的配置值，其中包含当前服务器的数据库设置。你只需要输入与默认配置组中的设置不同的值。这些值应该遵循以下格式，其中 ``default`` 是组名:: +你也可以在 **.env** 文件中保存配置值，并使用当前服务器的数据库设置。你只需要输入与默认组配置设置不同的值。这些值应遵循以下格式，其中 ``default`` 是组名:: database.default.username = 'root'; database.default.password = ''; database.default.database = 'ci4'; -但是你不能通过设置环境变量来添加新属性,也不能将标量值更改为数组。有关详细信息,请参阅 :ref:`env-var-replacements-for-data`。 +但你不能通过设置环境变量来添加新属性，也不能将标量值更改为数组。详情请参阅 :ref:`env-var-replacements-for-data`。 -因此,如果要对 MySQL 使用 SSL,你需要一个 hack。例如,在你的 **.env** 文件中将数组值设置为 JSON 字符串: +因此，如果你想在 MySQL 中使用 SSL，需要一个变通方法。例如，在你的 **.env** 文件中将数组值设置为 JSON 字符串： :: database.default.encrypt = {"ssl_verify":true,"ssl_ca":"/var/www/html/BaltimoreCyberTrustRoot.crt.pem"} -并在 Config 类的构造函数中解码它: +然后在 Config 类的构造函数中解码： .. literalinclude:: configuration/009.php .. _database-config-explanation-of-values: -********************** -值的描述 -********************** +********************* +配置值说明 +********************* ================ =========================================================================================================== - 名称 描述 + 配置名 说明 ================ =========================================================================================================== -**DSN** DSN 连接字符串(一体化配置序列)。 -**hostname** 数据库服务器的主机名。通常是 'localhost'。 -**username** 用于连接数据库的用户名。(``SQLite3`` 不使用此用户名) -**password** 用于连接数据库的密码。(``SQLite3`` 不使用此密码) -**database** 要连接的数据库名称。 - - .. note:: CodeIgniter 不支持在表名和列名中使用点 (``.``)。 - 从 v4.5.0 版本开始，支持带点的数据库名。 -**DBDriver** 数据库驱动名称。驱动名称区分大小写。 - 你可以设置完全限定的类名以使用自定义驱动。 - 支持的驱动:``MySQLi``、``Postgre``、``SQLite3``、``SQLSRV`` 和 ``OCI8``。 -**DBPrefix** 可选的表前缀,在运行时会添加到表名中 :doc:`查询构建器 ` 查询。这允许多个 CodeIgniter 安装共享一个数据库。 -**pConnect** true/false (布尔值)- 是否使用持久连接。 -**DBDebug** true/false (布尔值)- 当发生数据库错误时是否抛出异常。 -**charset** 与数据库通信使用的字符集。 -**DBCollat** （仅限 ``MySQLi``）与数据库通信时使用的字符集。 -**swapPre** 一个默认的表前缀,应该与 ``DBPrefix`` 互换。这对于分布式应用程序很有用,在那里你可能运行手动编写的查询,并需要最终用户仍可自定义前缀。 -**schema** （仅限 ``Postgre`` 和 ``SQLSRV``）数据库模式，默认值因驱动而异。 -**encrypt** （仅限 ``MySQLi`` 和 ``SQLSRV``）是否使用加密连接。 - 有关 ``MySQLi`` 设置，请参见 :ref:`MySQLi encrypt `。 - ``SQLSRV`` 驱动程序接受 true/false。 -**compress** （仅限 ``MySQLi``）是否使用客户端压缩。 -**strictOn** （仅限 ``MySQLi``）true/false（布尔值）- 是否强制使用“严格模式”连接，有助于确保在开发应用程序时使用严格的 SQL。 -**port** 数据库端口号 - 默认端口为空字符串 ``''`` (或使用 ``SQLSRV`` 动态端口)。 -**foreignKeys** （仅限 ``SQLite3``）true/false (布尔值)- 是否启用外键约束。 - - .. important:: SQLite3 外键约束默认关闭。 +**DSN** DSN 连接字符串（一个一体化的配置序列）。 +**hostname** 你的数据库服务器的主机名。通常为 'localhost'。 +**username** 用于连接数据库的用户名。（``SQLite3`` 不使用此选项。） +**password** 用于连接数据库的密码。（``SQLite3`` 不使用此选项。） +**database** 你要连接的数据库的名称。 + + .. note:: CodeIgniter 不支持在表名和列名中使用点（``.``）。 + 自 v4.5.0 起，支持包含点的数据库名。 +**DBDriver** 数据库驱动名称。大小写必须与驱动名称匹配。 + 你可以设置一个完全限定的类名来使用自定义驱动。 + 支持的驱动：``MySQLi``、``Postgre``、``SQLite3``、``SQLSRV`` 和 ``OCI8``。 +**DBPrefix** 一个可选的表前缀，当运行 + :doc:`查询构建器 ` 查询时将被添加到表名前。这允许多个 CodeIgniter + 安装共享一个数据库。 +**pConnect** true/false（布尔值）- 是否使用持久连接。 +**DBDebug** true/false（布尔值）- 当数据库发生错误时是否抛出异常。 +**charset** 与数据库通信时使用的字符集。 +**DBCollat** （仅 ``MySQLi``）与数据库通信时使用的字符排序规则。 +**swapPre** 一个默认的表前缀，应被 ``DBPrefix`` 替换。这对于分布式 + 应用程序很有用，在这种应用程序中你可能会运行手动编写的查询，并且需要前缀 + 仍可由最终用户自定义。 +**schema** （仅 ``Postgre`` 和 ``SQLSRV``）数据库模式，不同驱动程序的默认值不同。 +**encrypt** （仅 ``MySQLi`` 和 ``SQLSRV``）是否使用加密连接。 + 有关 ``MySQLi`` 设置，请参阅 :ref:`MySQLi encrypt `。 + ``SQLSRV`` 驱动接受 true/false。 +**compress** （仅 ``MySQLi``）是否使用客户端压缩。 +**strictOn** （仅 ``MySQLi``）true/false（布尔值）- 是否强制使用“严格模式”连接，这有助于在 + 开发应用程序时确保使用严格的 SQL。 +**port** 数据库端口号 - 默认端口使用空字符串 ``''`` （或 ``SQLSRV`` 的动态端口）。 +**foreignKeys** （仅 ``SQLite3``）true/false（布尔值）- 是否启用外键约束。 + + .. important:: SQLite3 外键约束默认是禁用的。 请参阅 `SQLite 文档 `_。 - 要实施外键约束,请将此配置项设置为 true。 -**busyTimeout** （仅限 ``SQLite3``）毫秒（int）- 当表被锁定时，休眠指定时间。 -**synchronous** （仅限 ``SQLite3``）标志（int）- 控制事务期间 SQLite 将数据刷新到磁盘的严格程度。 - 使用 `null` 可保持默认设置。该功能自 v4.6.0 版本起可用。 -**numberNative** （仅限 ``MySQLi``）true/false（布尔值）- 是否启用 MYSQLI_OPT_INT_AND_FLOAT_NATIVE。 -**foundRows** （仅限 ``MySQLi``）true/false（布尔值）- 是否启用 MYSQLI_CLIENT_FOUND_ROWS。 -**dateFormat** 默认的日期/时间格式，如 PHP 的 `DateTime format`_。 + 要强制启用外键约束，请将此配置项设置为 true。 +**busyTimeout** （仅 ``SQLite3``）毫秒（int）- 当表被锁定时，休眠指定的时间。 +**synchronous** （仅 ``SQLite3``）标志（int）- 事务期间 SQLite 写入磁盘的严格程度。 + 使用 `null` 以保持默认设置。此选项自 v4.6.0 起可用。 +**numberNative** （仅 ``MySQLi``）true/false（布尔值）- 是否启用 MYSQLI_OPT_INT_AND_FLOAT_NATIVE。 +**foundRows** （仅 ``MySQLi``）true/false（布尔值）- 是否启用 MYSQLI_CLIENT_FOUND_ROWS。 +**dateFormat** 默认的日期/时间格式，遵循 PHP 的 `DateTime format`_。 * ``date`` - 日期格式 * ``datetime`` - 日期和时间格式 * ``datetime-ms`` - 带毫秒的日期和时间格式 * ``datetime-us`` - 带微秒的日期和时间格式 * ``time`` - 时间格式 - 这一功能可以从 v4.5.0 版本开始使用，你可以通过例如 ``$db->dateFormat['datetime']`` 来获取值。 - 当前，数据库驱动程序不会直接使用这些值，但 :ref:`Model ` 会使用它们。 + 此选项自 v4.5.0 起可用，你可以通过 ``$db->dateFormat['datetime']`` 获取其值。 + 目前，数据库驱动不直接使用这些值， + 但 :ref:`模型 ` 会使用它们。 ================ =========================================================================================================== .. _DateTime format: https://www.php.net/manual/en/datetime.format.php -.. note:: 根据你使用的数据库驱动程序(``MySQLi``、``Postgre`` 等),并非所有的值都是必需的。例如,在使用 ``SQLite3`` 时,你不需要提供用户名或密码,数据库名称将是数据库文件的路径。 +.. note:: 根据你使用的数据库驱动（``MySQLi``、``Postgre`` 等），并非所有值都是必需的。例如，使用 ``SQLite3`` 时， + 你不需要提供用户名或密码，数据库名将是数据库文件的路径。 MySQLi ====== @@ -170,10 +185,11 @@ MySQLi hostname -------- -配置一个 Socket 连接 +配置套接字连接 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -要通过文件系统套接字连接到 MySQL 服务器，应在 ``'hostname'`` 设置中指定套接字的路径。CodeIgniter 的 MySQLi 驱动程序会注意到这一点并正确配置连接。 +要通过文件系统套接字连接到 MySQL 服务器，应将套接字的路径指定在 +``'hostname'`` 设置中。CodeIgniter 的 MySQLi 驱动将检测到此设置并正确配置连接。 .. literalinclude:: configuration/011.php :lines: 11-18 @@ -183,11 +199,11 @@ hostname encrypt ------- -MySQLi 驱动程序接受包含以下选项的数组： +MySQLi 驱动接受一个包含以下选项的数组： * ``ssl_key`` - 私钥文件的路径 * ``ssl_cert`` - 公钥证书文件的路径 * ``ssl_ca`` - 证书颁发机构文件的路径 -* ``ssl_capath`` - 包含以 PEM 格式存储的可信 CA 证书的目录路径 -* ``ssl_cipher`` - 允许用于加密的密码列表，用冒号（``:``）分隔 -* ``ssl_verify`` - true/false (布尔值) - 是否验证服务器证书 +* ``ssl_capath`` - 包含以 PEM 格式存储的受信任 CA 证书的目录路径 +* ``ssl_cipher`` - 用于加密的*允许*密码列表，以冒号（``:``）分隔 +* ``ssl_verify`` - true/false（布尔值）- 是否验证服务器证书 diff --git a/source/database/connecting.rst b/source/database/connecting.rst index c29885aa2..f6a2eaa3d 100755 --- a/source/database/connecting.rst +++ b/source/database/connecting.rst @@ -9,17 +9,17 @@ 连接数据库 ======================== -连接默认组 +连接到默认组 ------------------------------- -你可以通过在任何需要的函数中添加此代码行来连接数据库,或者在类构造函数中添加此行以在该类中全局提供数据库。 +你可以在需要的任何函数中，或在类构造函数中添加以下代码，使数据库在整个类中全局可用。 .. literalinclude:: connecting/001.php :lines: 2- -如果上述函数的第一个参数不包含任何信息,则它将连接数据库配置文件中指定的默认组。对于大多数人来说,这是首选的使用方法。 +如果上述函数的第一个参数中**不**包含任何信息，它将连接到数据库配置文件中指定的默认组。对大多数人来说，这是首选的使用方法。 -为方便起见,还提供了一个纯包装器方法,代码如下: +存在一个便利方法，它纯粹是上述代码行的包装器，为你的使用提供便利： .. literalinclude:: connecting/002.php :lines: 2- @@ -29,25 +29,25 @@ **\\Config\\Database::connect($group = null, bool $getShared = true): BaseConnection** -#. ``$group``:数据库组名称,必须与配置类属性名称匹配的字符串。默认值为 ``Config\Database::$defaultGroup``。 -#. ``$getShared``: true/false(布尔值)。是否返回共享连接(参见下面的连接多个数据库)。 +#. ``$group``: 数据库组名称，一个必须与配置类属性名称匹配的字符串。默认值为 ``Config\\Database::$defaultGroup``。 +#. ``$getShared``: true/false (布尔值)。是否返回共享连接（参见下面的“连接多个数据库”）。 -连接特定组 +连接到特定组 ---------------------------- -此函数的第一个参数可以用来指定配置文件中的特定数据库组。示例: +此函数的第一个参数可以**选择性地**用于指定配置文件中的特定数据库组。例如： -要从配置文件中选择一个特定的组,可以这样做: +要从配置文件中选择特定组，你可以这样做： .. literalinclude:: connecting/003.php :lines: 2- 其中 ``group_name`` 是配置文件中连接组的名称。 -连接到同一数据库的多个连接 +同一个数据库的多个连接 ------------------------------------- -默认情况下, ``connect()`` 方法每次都会返回数据库连接的同一实例。如果你需要与同一数据库建立一个单独的连接,请将 ``false`` 作为第二个参数发送: +默认情况下，``connect()`` 方法每次都会返回数据库连接的同一个实例。如果你需要对同一个数据库建立一个独立的连接，请将 ``false`` 作为第二个参数传入： .. literalinclude:: connecting/004.php :lines: 2- @@ -55,30 +55,30 @@ 连接多个数据库 ================================ -如果你需要同时连接多个数据库,可以这样做: +如果你需要同时连接到多个数据库，可以这样做： .. literalinclude:: connecting/005.php :lines: 2- -注意:请将 “group_one” 和 “group_two” 更改为你正在连接的特定组名称。 +注意：将 ``group_one`` 和 ``group_two`` 这些词替换为你正在连接的特定组名称。 -.. note:: 如果你只需要在同一连接上使用不同的数据库,则不需要创建单独的数据库配置。当需要时,你可以切换到不同的数据库,像这样: +.. note:: 如果你只需要在同一连接上使用不同的数据库，则无需创建单独的数据库配置。你可以在需要时切换到不同的数据库，就像这样： ``$db->setDatabase($database2_name);`` 使用自定义设置连接 =============================== -你可以传递一个数据库设置数组而不是组名称来获取使用自定义设置的连接。传递的数组必须与配置文件中定义组的格式相同: +你可以传入一个数据库设置数组而不是组名，以获取使用你自定义设置的连接。传入的数组必须遵循与配置文件中数据库组相同的结构： .. literalinclude:: connecting/006.php :lines: 2- -重新连接/保持连接活动 +重新连接 / 保持连接活跃 =========================================== -如果在执行一些繁重的 PHP 操作(处理图像等)时超过数据库服务器的空闲超时,则在发送进一步查询之前,应考虑通过使用 ``reconnect()`` 方法向服务器发出 ping,这可以优雅地保持连接活动或重新建立连接。 +当你在执行一些繁重的 PHP 操作（例如处理图像）时，如果超过了数据库服务器的空闲超时时间，你应该考虑在发送后续查询之前使用 ``reconnect()`` 方法来 ping 服务器，这可以优雅地保持连接活跃或重新建立连接。 -.. important:: 如果使用 MySQLi 数据库驱动程序, ``reconnect()`` 方法不会向服务器发出 ping,而是关闭连接然后再次连接。 +.. important:: 如果你使用的是 MySQLi 数据库驱动，``reconnect()`` 方法不会 ping 服务器，而是会关闭连接然后重新连接。 .. literalinclude:: connecting/007.php :lines: 2- @@ -86,7 +86,7 @@ 手动关闭连接 =============================== -虽然 CodeIgniter 会智能地关闭数据库连接,但你可以显式关闭连接。 +虽然 CodeIgniter 会智能地处理关闭数据库连接，但你也可以显式地关闭连接。 .. literalinclude:: connecting/008.php :lines: 2- diff --git a/source/database/events.rst b/source/database/events.rst index b64415f33..19cd491d4 100755 --- a/source/database/events.rst +++ b/source/database/events.rst @@ -2,7 +2,7 @@ 数据库事件 ############### -数据库类包含几个可以利用的 :doc:`事件 `,以了解数据库执行期间发生的更多信息。这些事件可用于收集数据以进行分析和报告。 :doc:`调试工具栏 ` 使用此操作来收集在工具栏中显示的查询。 +数据库类包含一些 :doc:`事件 `，你可以利用这些事件来了解数据库执行过程中的详细情况。这些事件可用于收集数据分析和生成报告。:doc:`调试工具栏 ` 就是利用这些事件来收集查询信息并显示在工具栏中。 .. contents:: :local: @@ -17,9 +17,9 @@ DBQuery ======= -此事件在每次运行新查询时触发，无论成功与否。唯一的参数是当前查询的 :doc:`Query ` 实例。 +每当执行一个新查询（无论成功与否）时，都会触发此事件。该事件唯一的参数是当前查询的 :doc:`Query ` 实例。 -你可以使用此事件将所有查询显示在 STDOUT，或记录到文件，甚至创建工具进行自动查询分析，以帮助你发现潜在的缺失索引、慢查询等。 +你可以利用此事件将所有查询输出到 STDOUT，或记录到文件中，甚至创建工具进行自动查询分析，以帮助你发现可能缺少的索引、慢查询等问题。 记录所有查询的示例： diff --git a/source/database/examples.rst b/source/database/examples.rst index 240b47f31..9cdd84366 100755 --- a/source/database/examples.rst +++ b/source/database/examples.rst @@ -1,10 +1,11 @@ -################################## +########################### 快速入门：使用示例 -################################## +########################### -以下页面包含显示数据库类用法的示例代码。有关完整详细信息,请阅读描述每个函数的单独页面。 +本页面包含展示数据库类如何使用的示例代码。更多详细信息，请阅读描述各个函数的独立页面。 -.. note:: CodeIgniter 不支持在表名和列名中使用点（``.``）。自 v4.5.0 起，支持带点的数据库名称。 +.. note:: CodeIgniter 不支持在表名和列名中使用点号（``.``）。 + 从 v4.5.0 版本开始，数据库名称支持使用点号。 .. contents:: :local: @@ -13,43 +14,45 @@ 初始化数据库类 =============================== -以下代码基于你的 :doc:`配置 ` 设置加载并初始化数据库类: +以下代码根据你的 :doc:`配置 ` 设置加载并初始化数据库类： .. literalinclude:: examples/001.php -一旦加载,该类即可按照下述方式使用。 +加载后，该类即可按以下所述方式使用。 -.. note:: 如果所有页面都需要数据库访问,则可以自动连接。有关详细信息,请参阅 :doc:`连接数据库 ` 页面。 +.. note:: 如果你所有的页面都需要数据库访问，你可以自动连接。 + 详情请参阅 :doc:`连接数据库 ` 页面。 -具有多个结果的标准查询(对象版本) +标准查询（多结果，对象版本） ===================================================== .. literalinclude:: examples/002.php -| 上述 ``getResult()`` 函数返回 **对象** 数组。 -| 示例:``$row->title`` +| 上述 ``getResult()`` 函数返回一个 **对象** 数组。 +| 示例：``$row->title`` -具有多个结果的标准查询(数组版本) +标准查询（多结果，数组版本） ==================================================== .. literalinclude:: examples/003.php -| 上述 ``getResultArray()`` 函数返回标准数组索引的数组。 -| 示例:``$row['title']`` +| 上述 ``getResultArray()`` 函数返回一个关联数组的数组。 +| 示例：``$row['title']`` -具有单个结果的标准查询 +标准查询（单个结果） ================================= .. literalinclude:: examples/004.php -上述 ``getRow()`` 函数返回一个 **对象**。示例:``$row->name`` +上述 ``getRow()`` 函数返回一个 **对象**。示例：``$row->name`` -具有单个结果的标准查询(数组版本) +标准查询（单个结果，数组版本） ================================================= .. literalinclude:: examples/005.php -上述 ``getRowArray()`` 函数返回一个 **数组**。示例: ``$row['name']``。 +上述 ``getRowArray()`` 函数返回一个 **关联数组**。示例： +``$row['name']``。 标准插入 =============== @@ -59,11 +62,11 @@ 查询构建器查询 =================== -:doc:`查询构建器 ` 为你提供了一种简化的检索数据方式: +:doc:`查询构建器 ` 为你提供了一种简化的数据检索方式： .. literalinclude:: examples/007.php -上述 ``get()`` 函数检索从提供的表中获取的所有结果。:doc:`查询构建器 ` 类包含用于处理数据的完整功能。 +上述 ``get()`` 函数从指定的表中检索所有结果。:doc:`查询构建器 ` 类包含一套完整的用于处理数据的函数。 查询构建器插入 ==================== diff --git a/source/database/helpers.rst b/source/database/helpers.rst index 07b842b2a..6b5379a2f 100755 --- a/source/database/helpers.rst +++ b/source/database/helpers.rst @@ -6,57 +6,55 @@ :local: :depth: 2 -执行查询的信息 +执行查询后的信息 ********************************** $db->insertID() =============== -执行数据库插入时的插入 ID 号。 +执行数据库插入操作时，返回插入记录的 ID 号。 -.. note:: 如果使用 PDO 驱动程序与 PostgreSQL 一起使用,或者使用 Interbase - 驱动程序,此函数需要一个 $name 参数,该参数指定要检查插入 ID 的适当序列。 +.. note:: 如果使用 PDO 驱动连接 PostgreSQL，或使用 Interbase 驱动，此函数需要一个 $name 参数，用于指定检查插入 ID 的相应序列。 $db->affectedRows() =================== -显示受影响的行数,当执行“写入”类型的查询时(插入、更新等)。 +执行“写”类型查询（如 insert、update 等）时，显示受影响的行数。 -.. note:: 在 MySQL 中,"DELETE FROM TABLE" 返回 0 受影响的行。数据库 - 类对此进行了一个小 Hack,允许它返回正确的受影响行数。默认情况下,此 Hack 已启用,但可以在数据库驱动程序文件中将其关闭。 +.. note:: 在 MySQL 中，执行 "DELETE FROM TABLE" 会返回 0 个受影响的行。数据库类有一个小的 hack 可以让它返回正确的受影响行数。默认情况下此 hack 是启用的，但可以在数据库驱动文件中将其关闭。 $db->getLastQuery() =================== -返回代表最后执行的查询的 Query 对象(查询字符串,而不是结果)。 +返回一个代表最后执行的查询的 Query 对象（即查询语句本身，而非查询结果）。 -有关数据库的信息 +关于数据库的信息 ******************************* $db->countAll() =============== -允许你确定特定表中的行数。在第一个参数中提交表名。这是查询构建器的一部分。 +用于确定特定表中的行数。将表名作为第一个参数传入。这是查询构建器的一部分。 .. literalinclude:: helpers/001.php $db->countAllResults() ====================== -允许你确定特定结果集中的行数。在第一个参数中提交表名。这是查询构建器的一部分。 +用于确定特定结果集中的行数。将表名作为第一个参数传入。这是查询构建器的一部分。 .. literalinclude:: helpers/002.php $db->getPlatform() ================== -输出你正在运行的数据库平台(DBDriver)(MySQLi、SQLSRV、Postgre等): +输出你正在运行的数据库平台（DBDriver），如 MySQLi、SQLSRV、Postgre 等： .. literalinclude:: helpers/003.php $db->getVersion() ================= -输出你正在运行的数据库版本: +输出你正在运行的数据库版本： .. literalinclude:: helpers/004.php diff --git a/source/database/index.rst b/source/database/index.rst index b94a215fb..43d497a4e 100755 --- a/source/database/index.rst +++ b/source/database/index.rst @@ -1,21 +1,21 @@ ###################### -使用数据库 +数据库操作 ###################### -CodeIgniter 带有一个功能齐全且非常快速的抽象数据库类,它支持传统结构和查询构建器模式。数据库函数提供清晰、简单的语法。 +CodeIgniter 提供了一个功能齐全且非常快速的抽象数据库类，支持传统的数据库操作和查询构建器模式。数据库函数提供了清晰、简洁的语法。 .. toctree:: :titlesonly: - 快速入门:使用示例 + 快速入门：使用示例 数据库配置 连接数据库 - 运行查询 - 生成查询结果 + Running Queries + Generating Query Results 查询辅助方法 - 查询构建器类 - 事务 - 获取元数据 + Query Builder Class + Transactions + Getting Metadata 自定义函数调用 数据库事件 - 数据库实用工具 + Database Utilities diff --git a/source/database/metadata.rst b/source/database/metadata.rst index e677e3508..4ac67d125 100755 --- a/source/database/metadata.rst +++ b/source/database/metadata.rst @@ -1,74 +1,74 @@ -################# +################ 获取元数据 -################# +################ .. contents:: :local: :depth: 2 ************** -表格元数据 +表元数据 ************** -这些函数让你获取表格信息。 +这些方法让你可以获取表信息。 -列出数据库中的表格 +列出数据库中的所有表 ================================ $db->listTables() ----------------- -返回一个数组,其中包含当前连接数据库中的所有表格名称。例如: +返回一个数组，其中包含当前连接的数据库中所有表的名称。示例： .. literalinclude:: metadata/001.php -.. note:: 一些驱动程序有其他系统表被排除在此返回之外。 +.. note:: 某些驱动程序包含额外的系统表，这些表不会包含在此返回结果中。 -确定表格是否存在 +确定表是否存在 =========================== $db->tableExists() ------------------ -在对表运行操作之前,知道特定表格是否存在有时很有帮助。返回布尔值 true/false。用法示例: +在对某个特定表执行操作之前，知道该表是否存在会很有帮助。此方法返回布尔值 true/false。用法示例： .. literalinclude:: metadata/002.php -.. note:: 用你要查找的表格名称替换 *table_name*。 +.. note:: 将 *table_name* 替换为你正在查找的表名。 ************** 字段元数据 ************** -列出表中的字段 +列出表中的所有字段 ========================== $db->getFieldNames() -------------------- -返回包含字段名称的数组。可以通过两种方式调用此查询: +返回一个包含字段名称的数组。此查询可以通过两种方式调用： -1. 你可以提供表格名称并从 ``$db`` 对象调用它: +1. 你可以提供表名，并从 ``$db`` 对象调用： .. literalinclude:: metadata/003.php -2. 你可以通过从查询结果对象调用函数来收集与任何查询关联的字段名称: +2. 你可以通过从查询结果对象调用该方法，来获取你运行的任何查询所关联的字段名称： .. literalinclude:: metadata/004.php -确定表中是否存在字段 +确定字段是否存在于表中 ========================================== $db->fieldExists() ------------------ -在执行操作之前,有时知道某个特定字段是否存在很有帮助。返回布尔值 true/false。用法示例: +在执行某个操作之前，知道特定字段是否存在会很有帮助。此方法返回布尔值 true/false。用法示例： .. literalinclude:: metadata/005.php -.. note:: 将 *field_name* 和 *table_name* 替换为你要查找的列名和表名。 +.. note:: 将 *field_name* 和 *table_name* 分别替换为你正在查找的列名和表名。 -检索字段元数据 +获取字段元数据 ======================= .. _db-metadata-getfielddata: @@ -76,37 +76,37 @@ $db->fieldExists() $db->getFieldData() ------------------- -返回包含字段信息的对象数组。 +返回一个包含字段信息的对象数组。 -有时收集字段名称或其他元数据(如列类型、最大长度等)很有帮助。 +有时收集字段名称或其他元数据（如列类型、最大长度等）会很有帮助。 .. note:: 并非所有数据库都提供元数据。 -用法示例: +用法示例： .. literalinclude:: metadata/006.php -如果你的数据库支持，下列数据可以通过此函数获取： +如果数据库支持，此函数可返回以下数据： -- ``name`` - 列名称 -- ``type`` - 列的类型 -- ``max_length`` - 列的最大长度 -- ``nullable`` - 如果列允许为空，则为布尔值 ``true`` ，否则为布尔值 ``false`` +- ``name`` - 字段名 +- ``type`` - 字段的类型 +- ``max_length`` - 字段的最大长度 +- ``nullable`` - 如果字段可为空则为布尔值 ``true``，否则为布尔值 ``false`` - ``default`` - 默认值 -- ``primary_key`` - 如果列是主键，则为整数 ``1`` （即使有多个主键，所有主键值都是整数 ``1``），否则为整数 ``0`` （此字段目前仅对 ``MySQLi`` 和 ``SQLite3`` 可用） +- ``primary_key`` - 如果字段是主键则为整数 ``1`` （即使存在多个主键，也全为整数 ``1``），否则为整数 ``0`` （此字段当前仅在 ``MySQLi`` 和 ``SQLite3`` 中可用） -.. note:: 自 v4.4.0 起，SQLSRV 支持 ``nullable``。 +.. note:: 自 v4.4.0 版本起，SQLSRV 支持 ``nullable``。 $query->getFieldData() ---------------------- -如果你已经运行了一个查询，可以使用结果对象而不是提供表名： +如果已经执行过查询，可以使用结果对象代替提供表名： .. literalinclude:: metadata/007.php -.. note:: 返回的数据与 ``$db->getFieldData()`` 返回的数据不同。如果你无法获取所需的数据，请使用 ``$db->getFieldData()``。 +.. note:: 返回的数据与 ``$db->getFieldData()`` 返回的数据不同。如果无法获取所需数据，请使用 ``$db->getFieldData()``。 -列出表中的索引 +列出表中的所有索引 =========================== .. _db-metadata-getindexdata: @@ -114,26 +114,25 @@ $query->getFieldData() $db->getIndexData() ------------------- -返回包含索引信息的对象数组。 +返回一个包含索引信息的对象数组。 -用法示例: +用法示例： .. literalinclude:: metadata/008.php -关键字类型可能是你使用的数据库所独有的。 -例如,MySQL 将为与表关联的每个键返回 primary、fulltext、spatial、index 或 unique 中的一个。 +键的类型可能因你使用的数据库而异。例如，MySQL 会为表关联的每个键返回 primary、fulltext、spatial、index 或 unique 中的一种。 -SQLite3 返回一个名为 ``PRIMARY`` 的伪索引。但它是一个特殊的索引,你不能在 SQL 命令中使用它。 +SQLite3 会返回一个名为 ``PRIMARY`` 的伪索引。但它是一个特殊索引，不能在 SQL 命令中使用。 .. _metadata-getforeignkeydata: $db->getForeignKeyData() ------------------------ -返回包含外键信息的对象数组。 +返回一个包含外键信息的对象数组。 -用法示例: +用法示例： .. literalinclude:: metadata/009.php -外键使用命名约定 ``tableprefix_table_column1_column2_foreign``。Oracle 使用稍微不同的后缀 ``_fk``。 +外键使用 ``tableprefix_table_column1_column2_foreign`` 命名约定。Oracle 使用略有不同的后缀 ``_fk``。 diff --git a/source/database/queries.rst b/source/database/queries.rst index 091aa79eb..92dc9d392 100755 --- a/source/database/queries.rst +++ b/source/database/queries.rst @@ -1,6 +1,6 @@ -####### -查询 -####### +########## +数据库查询 +########## .. contents:: :local: @@ -10,7 +10,8 @@ 查询基础知识 ************ -.. note:: CodeIgniter 不支持在表名和列名中使用点（``.``）。自 v4.5.0 起，支持带点的数据库名称。 +.. note:: CodeIgniter 不支持在表名和列名中使用点号（``.``）。 + 自 v4.5.0 版本起，支持包含点号的数据库名。 常规查询 =============== @@ -20,17 +21,18 @@ $db->query() ------------ -要提交查询,请使用 ``query()`` 方法: +要执行查询，请使用 ``query()`` 方法： .. literalinclude:: queries/001.php -当运行“读取”类型查询时, ``query()`` 方法会返回一个可以用来 :doc:`显示结果 ` 的数据库结果 **对象**。当运行“写入”类型查询时,它根据成功或失败简单地返回 true 或 false。检索数据时,你通常会将查询分配给自己的变量,如下所示: +当执行“读取”类型查询时，``query()`` 方法会返回一个数据库结果 **对象**，你可以使用该对象来 :doc:`显示结果 `。当执行“写入”类型查询时，该方法仅根据成功或失败返回 true 或 false。在检索数据时，你通常会将查询结果赋值给自己的变量，像这样： .. literalinclude:: queries/002.php -.. note:: 如果使用 OCI8 驱动程序,SQL 语句不应以分号 (``;``) 结尾。PL/SQL 语句应以分号 (``;``) 结尾。 +.. note:: 如果你使用 OCI8 驱动程序，SQL 语句不应以分号（``;``）结尾。 + PL/SQL 语句应以分号（``;``）结尾。 -简化的查询 +简化查询 ================== .. _db-simplequery: @@ -38,37 +40,38 @@ $db->query() $db->simpleQuery() ------------------ -``simpleQuery()`` 方法是 ``$db->query()`` 方法的简化版本。 -它不会返回数据库结果集,也不会设置查询计时器或编译绑定数据或存储调试查询。它只是让你提交一个查询。大多数用户很少使用此功能。 +``simpleQuery()`` 方法是 ``$db->query()`` 方法的简化版本。它不会返回数据库结果集，也不会设置查询计时器、编译绑定数据或存储查询以供调试。它只是让你提交一个查询。大多数用户很少会使用此函数。 -它返回数据库驱动程序的 “execute” 函数返回的任何内容。对于写入类型的查询(如 INSERT、DELETE 或 UPDATE 语句),这通常在成功或失败时返回 true/false(这确实是应该使用它的地方),并在具有可获取结果的查询成功时返回资源/对象。 +它返回数据库驱动程序“execute”函数返回的任何内容。 +对于 INSERT、DELETE 或 UPDATE 等写入类型查询，通常在成功或失败时返回 true/false（这正是它真正应该被用于的场景）；对于具有可获取结果的查询，在成功时返回资源/对象。 .. literalinclude:: queries/003.php -.. note:: 例如,PostgreSQL 的 ``pg_exec()`` 函数总是在成功时返回资源,即使对于写入类型的查询也是如此。所以如果你正在查找布尔值,请记住这一点。 +.. note:: PostgreSQL 的 ``pg_exec()`` 函数（例如）在成功时总是返回一个资源，即使是写入类型查询也是如此。 + 因此，如果你在寻找布尔值，请记住这一点。 *************************************** -手动使用数据库前缀 +手动处理数据库前缀 *************************************** $db->prefixTable() ================== -如果你已经配置了数据库前缀,并希望在本机 SQL 查询(例如)中将其添加到表名前,那么可以使用以下代码: +如果你已配置了数据库前缀，并希望将其添加到表名前（例如在原生 SQL 查询中使用），则可以使用以下方法： .. literalinclude:: queries/004.php $db->setPrefix() ================ -如果由于任何原因你想以编程方式更改前缀,而不需要创建新的连接,则可以使用此方法: +如果出于任何原因，你希望在不创建新连接的情况下以编程方式更改前缀，可以使用此方法： .. literalinclude:: queries/005.php $db->getPrefix() ================ -你可以使用此方法随时获取当前前缀: +你可以随时使用此方法获取当前前缀： .. literalinclude:: queries/006.php @@ -80,13 +83,13 @@ $db->getPrefix() $db->protectIdentifiers() ========================= -在许多数据库中,保护表格和字段名称(例如在 MySQL 中使用反引号)是可取的。**查询构建器查询会自动受保护**,但是如果你需要手动保护一个标识符,可以使用: +在许多数据库中，建议保护表名和字段名——例如在 MySQL 中使用反引号。**查询构建器（Query Builder）查询会自动受到保护**，但如果你需要手动保护标识符，可以使用： .. literalinclude:: queries/007.php -.. important:: 尽管查询构建器会尽力正确引用你提供的任何字段和表名，但请注意它并不适用于任意用户输入。请勿将未经过处理的用户数据提供给它。 +.. important:: 尽管查询构建器会尽力正确地引用你提供的任何字段和表名。请注意，它并非设计用于处理任意的用户输入。切勿将未经净化的用户数据提供给它。 -如果在数据库配置文件中指定了前缀,此函数也会将 **表前缀** 添加到表格名,以启用前缀,请通过第二个参数设置 ``true`` (布尔值): +此函数还会为你的表添加 **表前缀**，前提是你的数据库配置文件中指定了前缀。要启用前缀功能，请通过第二个参数设置为 ``true`` （布尔值）： .. literalinclude:: queries/008.php @@ -96,33 +99,32 @@ $db->protectIdentifiers() 转义值 *************** -在将数据提交到数据库之前对其进行转义是非常好的安全实践。CodeIgniter 提供了三种帮助你实现这一点的方法: +在将数据提交到数据库之前进行转义是一种非常好的安全实践。CodeIgniter 提供了三种方法来帮助你实现这一点： .. _database-queries-db_escape: 1. $db->escape() ================ -此函数确定数据类型,以便它只能转义字符串数据。它还会自动在数据周围添加单引号,所以你不必这样做: +此函数会确定数据类型，以便仅转义字符串数据。它还会自动在数据周围添加单引号，因此你无需手动添加： .. literalinclude:: queries/009.php 2. $db->escapeString() ====================== -此函数转义传入的数据,而不考虑类型。大多数时间你会使用上面的函数而不是这个。像这样使用该函数: +此函数会转义传递给它的数据，无论其类型如何。大多数情况下，你将使用上面的函数而不是这个。使用此函数的方法如下： .. literalinclude:: queries/010.php 3. $db->escapeLikeString() ========================== -当字符串将在 LIKE 条件中使用时,应使用此方法, -以便字符串中的 LIKE 通配符 (``%``、``_``) 也适当转义。 +当字符串用于 LIKE 条件时，应使用此方法，以确保字符串中的 LIKE 通配符（``%``、``_``）也得到正确转义。 .. literalinclude:: queries/011.php -.. important:: ``escapeLikeString()`` 方法使用 ``'!'`` (感叹号)来转义 ``LIKE`` 条件的特殊字符。因为此方法转义了你自己要用引号括起来的部分字符串,所以它无法自动为你添加 ``ESCAPE '!'`` 条件,因此你必须手动完成这一操作。 +.. important:: ``escapeLikeString()`` 方法使用 ``'!'`` （感叹号）来转义 ``LIKE`` 条件中的特殊字符。由于此方法转义的是你自己需要用引号包裹的部分字符串，因此它无法自动为你添加 ``ESCAPE '!'`` 条件，所以你需要手动完成。 .. _database-queries-query-bindings: @@ -130,31 +132,31 @@ $db->protectIdentifiers() 查询绑定 ************** -绑定使你可以通过让系统为你组装查询来简化查询语法。考虑以下示例: +绑定功能通过让系统为你组合查询，从而简化你的查询语法。请看以下示例： .. literalinclude:: queries/012.php -查询中的问号自动替换为查询函数第二个参数数组中的值。 +查询中的问号会自动被查询函数第二个参数数组中的值所替换。 -绑定也适用于数组,它将转换为 IN 集: +绑定也适用于数组，数组将被转换为 IN 集合： .. literalinclude:: queries/013.php -生成的查询将是:: +最终生成的查询将为:: SELECT * FROM some_table WHERE id IN (3,6) AND status = 'live' AND author = 'Rick' -使用绑定的次要好处是值会自动转义,从而产生更安全的查询。 -你不必记住手动转义数据 - 引擎会自动为你完成这一操作。 +使用绑定的另一个好处是，值会被自动转义，从而生成更安全的查询。 +你无需记住要手动转义数据——引擎会自动为你完成。 命名绑定 ============== -除了使用问号标记绑定值的位置外,你还可以命名绑定,允许传入值的键与查询中的占位符匹配: +你可以为绑定命名，而不是使用问号来标记绑定值的位置，这样传递的值的键就可以与查询中的占位符相匹配： .. literalinclude:: queries/014.php -.. note:: 查询中的每个名称必须用冒号括起来。 +.. note:: 查询中的每个名称必须用冒号包围。 *************** 处理错误 @@ -163,7 +165,7 @@ $db->protectIdentifiers() $db->error() ============ -如果你需要获取最后发生的错误, ``error()`` 方法将返回包含代码和消息的数组。这是一个快速示例: +如果你需要获取最近发生的错误，``error()`` 方法将返回一个包含其代码和消息的数组。这里有一个快速示例： .. literalinclude:: queries/015.php @@ -172,134 +174,136 @@ $db->error() 预处理查询 **************** -大多数数据库引擎都支持某种形式的预编译语句,允许你预先准备一次查询,然后使用新的数据集多次运行该查询。这消除了 SQL 注入的可能性,因为数据采用不同于查询本身的格式传递给数据库。当需要多次运行相同的查询时,它也可以快得多。但是,对每个查询都这样做可能会大大降低性能,因为调用数据库的频率加倍。由于查询生成器和数据库连接已经为你处理了数据的转义,所以安全方面已经为你照顾好了。但是,有时候你需要通过运行预编译语句或预处理查询来优化查询。 +大多数数据库引擎都支持某种形式的预处理语句，允许你先准备一次查询，然后使用新的数据集多次执行该查询。由于数据是以与查询本身不同的格式传递给数据库的，这消除了 SQL 注入的可能性。当你需要多次运行同一查询时，这种方式也可能快得多。然而，对每个查询都使用预处理可能会造成重大的性能损失，因为你会更频繁地调用数据库。由于查询构建器（Query Builder）和数据库连接已经为你处理了数据转义，安全性方面已经为你解决了。不过，有时你可能需要通过运行预处理语句或预处理查询来优化查询。 准备查询 =================== -这可以通过 ``prepare()`` 方法轻松完成。它接受一个参数,该参数是一个返回查询对象的闭包。查询对象由任何“final”类型的查询自动生成,包括 **insert**、**update**、**delete**、**replace** 和 **get**。通过使用查询构建器运行查询来实现这一点最简单。查询实际上不会运行,值也不重要,因为它们从未应用,而是充当占位符。这将返回一个 PreparedQuery 对象: +这可以通过 ``prepare()`` 方法轻松完成。该方法接受一个参数，即返回查询对象的闭包（Closure）。查询对象会由任何“最终”类型的查询自动生成，包括 **insert**、**update**、**delete**、**replace** 和 **get**。使用查询构建器来运行查询是最简单的方法。查询实际上不会执行，值也不重要，因为它们永远不会被应用，而是作为占位符。这将返回一个 PreparedQuery 对象： .. literalinclude:: queries/016.php -如果不想使用查询构建器,可以使用问号作为值占位符手动创建查询对象: +如果你不想使用查询构建器，可以使用问号作为值占位符，手动创建查询对象： .. literalinclude:: queries/017.php -如果数据库在预编译语句阶段需要一个选项数组传递给它,则可以在第二个参数中传递该数组: +如果数据库在准备语句阶段需要传入一个选项数组，你可以在第二个参数中传入该数组： .. literalinclude:: queries/018.php -.. note:: 目前，唯一实际使用选项数组的数据库是 SQLSRV。 +.. note:: 目前，真正使用选项数组的数据库只有 SQLSRV。 执行查询 =================== -一旦你有了预处理的查询,就可以使用 ``execute()`` 方法实际运行查询。你可以根据查询中的占位符数量传递任意多个变量。必须传入的参数数目必须与查询中的占位符数目匹配。它们还必须以在原始查询中出现的占位符的顺序传递: +一旦你有了一个预处理查询，就可以使用 ``execute()`` 方法来实际运行查询。你可以在查询参数中传入任意数量的变量。你传入的参数数量必须与查询中的占位符数量相匹配。它们还必须按照占位符在原始查询中出现的顺序传入： .. literalinclude:: queries/019.php -对于“写入”类型的查询,它返回 true 或 false,指示查询的成功或失败。对于“读取”类型的查询,它返回一个标准的 :doc:`结果集 `。 +对于“写入”类型的查询，它返回 true 或 false，表示查询的成功或失败。 +对于“读取”类型的查询，它返回一个标准的 :doc:`结果集 `。 其他方法 ============= -除了这两个主要方法之外,预处理查询对象还有以下方法: +除了这两个主要方法外，预处理查询对象还具有以下方法： .. _database-queries-stmt-close: close() ------- -虽然 PHP 在数据库关闭所有打开的语句方面做得很好,但是当不需要预处理语句时关闭它总是一个好主意: +虽然 PHP 在关闭所有与数据库的打开语句方面做得相当好，但在你完成使用后关闭预处理语句始终是个好主意： .. literalinclude:: queries/020.php -.. note:: 从 v4.3.0 开始, ``close()`` 方法在所有 DBMS 中释放预编译语句。以前,它们在 Postgre、SQLSRV 和 OCI8 中没有被释放。 +.. note:: 自 v4.3.0 版本起，``close()`` 方法在所有数据库管理系统（DBMS）中都会释放预处理语句。在此之前，PostgreSQL、SQLSRV 和 OCI8 中不会释放。 getQueryString() ---------------- -这将返回预处理查询的字符串。 +此方法将预处理查询作为字符串返回。 hasError() ---------- -如果最后一个 ``execute()`` 调用产生任何错误,则返回布尔值 true/false。 +如果上一次 ``execute()`` 调用产生了任何错误，则返回布尔值 true/false。 getErrorCode() -------------- getErrorMessage() ----------------- -如果遇到任何错误,可以使用这些方法检索错误代码和字符串。 +如果遇到任何错误，可以使用这些方法来检索错误代码和错误信息。 ************************** 使用查询对象 ************************** -在内部,所有查询都作为 ``CodeIgniter\Database\Query`` 的实例进行处理和存储。此类负责绑定参数,否则准备查询,并存储有关其查询的性能数据。 +在内部，所有查询都会作为 ``CodeIgniter\Database\Query`` 的实例进行处理和存储。此类负责绑定参数、准备查询以及存储有关其查询的性能数据。 $db->getLastQuery() =================== -当你只需要检索最后一个查询对象时,使用 ``getLastQuery()`` 方法: +当你只需要检索最后一个查询对象时，使用 ``getLastQuery()`` 方法： .. literalinclude:: queries/021.php 查询类 =============== -每个查询对象都存储与查询本身相关的几个信息片段。这在一定程度上由时间线功能使用,但也可供你使用。 +每个查询对象都存储了有关查询本身的一些信息。 +这在一定程度上被时间线（Timeline）功能所使用，但也可以供你使用。 getQuery() ---------- -在所有处理完成后返回最终查询。这是发送到数据库的确切查询: +返回所有处理完成后最终的查询。这是实际发送到数据库的确切查询： .. literalinclude:: queries/022.php -通过将查询对象转换为字符串,也可以检索相同的值: +通过将查询对象转换为字符串，也可以获得相同的值： .. literalinclude:: queries/023.php getOriginalQuery() ------------------ -返回传入对象的原始 SQL。其中不会有任何绑定,也不会替换前缀等: +返回传递给对象的原始 SQL。其中不会包含任何绑定、前缀替换等内容： .. literalinclude:: queries/024.php hasError() ---------- -如果在执行此查询期间遇到错误,则此方法将返回 true: +如果在执行此查询期间遇到错误，此方法将返回 true： .. literalinclude:: queries/025.php isWriteType() ------------- -如果查询被确定为写入类型查询(即 INSERT、UPDATE、DELETE 等),则返回 true: +如果确定查询为写入类型查询（即 INSERT、UPDATE、DELETE 等），则返回 true： .. literalinclude:: queries/026.php swapPrefix() ------------ -用另一个值替换 SQL 中的一个表前缀。第一个参数是要替换的原始前缀,第二个参数是要替换的值: +在 SQL 中将一个表前缀替换为另一个值。第一个参数是你想要替换的原始前缀，第二个参数是你想要将其替换为的值： .. literalinclude:: queries/027.php getStartTime() -------------- -以秒(含微秒)为单位获取查询执行的时间: +获取查询执行的时间（以秒为单位，包含微秒）： .. literalinclude:: queries/028.php getDuration() ------------- -以秒(含微秒)为单位返回查询持续时间的浮点数: +返回一个浮点数，表示查询持续的时间（以秒为单位，包含微秒）： .. literalinclude:: queries/029.php diff --git a/source/database/query_builder.rst b/source/database/query_builder.rst index 55395445a..ac6f16209 100755 --- a/source/database/query_builder.rst +++ b/source/database/query_builder.rst @@ -2,48 +2,57 @@ 查询构建器类 ################### -CodeIgniter 为你提供了访问查询构建器类的方式。该模式允许你通过最少的脚本执行数据库的检索、插入和更新操作。在某些情况下，只需一两行代码即可执行数据库操作。CodeIgniter 不要求每个数据库表对应一个独立的类文件，而是提供了一个更为简化的接口。 +CodeIgniter 提供了查询构建器类。这种模式允许使用最少的脚本从数据库中检索、插入和更新信息。在某些情况下，只需一两行代码就能执行数据库操作。 +CodeIgniter 不要求每个数据库表都有自己的类文件，而是提供了一个更简化的接口。 -除了简单性，使用查询构建器功能的一个主要优势是它允许你创建与数据库无关的应用程序，因为查询语法由每个数据库适配器生成。它还允许更安全的查询，因为系统会自动对值进行转义。 +除了简单之外，使用查询构建器功能的一个主要好处是，它允许创建数据库无关的应用程序，因为查询语法是由每个数据库适配器生成的。它还允许更安全的查询，因为值由系统自动转义。 -.. note:: CodeIgniter 不支持表名和列名中包含点号（``.``）。自 v4.5.0 起，支持包含点号的数据库名。 +.. note:: CodeIgniter 不支持表名和字段名中的点（``.``）。 + 从 v4.5.0 开始，支持带点的数据库名称。 .. contents:: :local: :depth: 2 ************************ -SQL 注入防护 +SQL 注入保护 ************************ -你可以借助查询构建器相当安全地生成 SQL 语句。 然而，它并非被设计为无论你传递什么数据都能防止 SQL 注入。 +使用查询构建器生成 SQL 语句是相当安全的。然而，它并非被设计为，无论你传递什么数据都能防止 SQL 注入。 传递给查询构建器的参数可以是： - 1. **标识符**，例如字段（或表）名 + 1. **标识符**，如字段名或表名 2. 它们的 **值** 3. **SQL 字符串** 的一部分 -查询构建器默认会对所有 **值** 进行转义。 +查询构建器默认会转义所有 **值**。 -默认情况下，它也会尝试正确保护 **标识符** 和 **SQL 字符串** 中的标识符。然而，该实现是为了在多数用例中良好工作，并非设计用于防御所有攻击。因此，在未经适当验证的情况下，你绝不应将用户输入传递给它们。 +它还会默认尝试正确保护 **标识符** 和 **SQL 字符串** 中的标识符。 +然而，它是为了在许多用例中良好工作而实现的，并不是设计用来防止所有攻击的。 +因此，绝不应该在没有适当验证的情况下将用户输入传入其中。 -此外，许多方法具有 ``$escape`` 参数，可以设置为禁用转义。如果 ``$escape`` 设置为 false，查询构建器将不提供任何保护，因此在传递给查询构建器之前，你必须自行确保它们已正确转义或保护。使用指定原始 SQL 语句的 ``RawSql`` 时也是如此。 +此外，许多方法都有 ``$escape`` 参数，可以设置为禁用转义。 +如果 ``$escape`` 设置为 false，查询构建器将不会提供任何保护， +因此你必须自己确保在将其传递给查询构建器之前， +它们已经被正确转义或保护。 +使用 ``RawSql`` 时也是如此，它指定了一个原始 SQL 语句。 ************************* 加载查询构建器 ************************* -查询构建器通过数据库连接上的 ``table()`` 方法加载。这会为你设置查询的 **FROM** 部分，并返回查询构建器类的新实例： +查询构建器通过数据库连接上的 ``table()`` 方法加载。这会为你设置查询的 **FROM** 部分， +并返回查询构建器类的新实例： .. literalinclude:: query_builder/001.php -只有在你明确请求该类时，查询构建器才会加载到内存中，因此默认情况下不会占用资源。 +查询构建器仅在你明确请求该类时才加载到内存中，因此默认情况下不使用任何资源。 ************** 选择数据 ************** -以下方法允许你构建 SQL **SELECT** 语句。 +以下方法允许构建 SQL **SELECT** 语句。 Get === @@ -51,43 +60,47 @@ Get $builder->get() --------------- -运行选择查询并返回结果。可单独使用以从表中检索所有记录： +运行选择查询并返回结果。可以单独使用检索表中的所有记录： .. literalinclude:: query_builder/002.php -第一个和第二个参数允许你设置 limit 和 offset 子句： +第一个和第二个参数允许设置 limit 和 offset 子句： .. literalinclude:: query_builder/003.php -你会注意到上述方法被赋值给名为 $query 的变量，该变量可用于显示结果： +你会注意到上述方法被赋值给一个名为 $query 的变量，该变量可以用来显示结果： .. literalinclude:: query_builder/004.php -关于结果生成的完整讨论，请访问 :ref:`getResult() ` 方法。 +请访问 :ref:`getResult() ` 方法，获取关于结果生成的完整讨论。 $builder->getCompiledSelect() ----------------------------- -像 ``$builder->get()`` 一样编译选择查询，但不会 *运行* 查询。此方法仅以字符串形式返回 SQL 查询。 +编译选择查询，就像 ``$builder->get()`` 一样，但不 *运行* 查询。此方法只是将 SQL 查询作为字符串返回。 示例： .. literalinclude:: query_builder/005.php -第一个参数（false）允许你设置查询构建器是否会被重置（因为参数的默认值为 true，即 ``getCompiledSelect(bool $reset = true)``，默认情况下会像使用 ``$builder->get()`` 一样被重置）： +下面第一个查询中的参数（false）允许设置是否重置查询构建器 +（因为参数的默认值是 true，``getCompiledSelect(bool $reset = true)``，默认情况下它会像使用 ``$builder->get()`` 时一样被重置）： .. literalinclude:: query_builder/006.php -需要注意的关键点是，第二个查询未使用 ``limit(10, 20)``，但生成的 SQL 查询包含 ``LIMIT 20, 10``。造成此结果的原因是第一个查询的参数设置为 ``false``，导致 ``limit(10, 20)`` 保留在第二个查询中。 +上述示例的关键点是，第二个查询没有 +使用 ``limit(10, 20)``，但生成的 SQL 查询却有 ``LIMIT 20, 10``。 +出现这种结果的原因是第一个查询中的参数设置为 ``false``，``limit(10, 20)`` 保留在第二个查询中。 $builder->getWhere() -------------------- -与 ``get()`` 方法相同，区别在于它允许你在第一个参数中添加 "where" 子句，而无需使用 ``$builder->where()`` 方法： +与 ``get()`` 方法相同，只是它允许你在第一个参数中添加 +"where" 子句，而不是使用 ``$builder->where()`` 方法： .. literalinclude:: query_builder/007.php -有关 ``where()`` 方法的更多信息，请阅读下文。 +请阅读下面的 ``where()`` 方法获取更多信息。 .. _query-builder-select: @@ -97,13 +110,13 @@ Select $builder->select() ------------------ -允许你编写查询的 **SELECT** 部分： +允许编写查询的 **SELECT** 部分： .. literalinclude:: query_builder/008.php -.. note:: 如果从表中选择所有（``*``），则无需使用此方法。当省略时，CodeIgniter 假定你希望选择所有字段并自动添加 ``SELECT *``。 +.. note:: 如果从表中选择所有（``*``）字段，则不需要使用此方法。当省略时，CodeIgniter 假定你希望选择所有字段，并自动添加 ``SELECT *``。 -``$builder->select()`` 接受可选的第二个参数。如果将其设置为 ``false``，CodeIgniter 将不会尝试保护你的字段或表名。这在需要复合 select 语句且自动转义字段可能破坏它们时非常有用。 +``$builder->select()`` 接受一个可选的第二个参数。如果将其设置为 ``false``，CodeIgniter 将不会尝试保护字段或表名。这在需要复合 select 语句且自动转义字段可能破坏它们时非常有用。 .. literalinclude:: query_builder/009.php @@ -114,46 +127,46 @@ RawSql .. versionadded:: 4.2.0 -自 v4.2.0 起，``$builder->select()`` 接受表示原始 SQL 字符串的 ``CodeIgniter\Database\RawSql`` 实例。 +从 v4.2.0 开始，``$builder->select()`` 接受一个 ``CodeIgniter\Database\RawSql`` 实例，它表示原始 SQL 字符串。 .. literalinclude:: query_builder/099.php -.. warning:: 使用 ``RawSql`` 时，你必须手动转义值并保护标识符。否则可能导致 SQL 注入。 +.. warning:: 使用 ``RawSql`` 时，必须手动转义值并保护标识符。否则可能导致 SQL 注入。 $builder->selectMax() --------------------- -为你的查询编写 **SELECT MAX(field)** 部分。你可以选择包含第二个参数以重命名结果字段。 +为查询编写 **SELECT MAX(field)** 部分。可以选择包含第二个参数来重命名结果字段。 .. literalinclude:: query_builder/010.php $builder->selectMin() --------------------- -为你的查询编写 **SELECT MIN(field)** 部分。与 ``selectMax()`` 类似，你可以选择包含第二个参数以重命名结果字段。 +为查询编写 **SELECT MIN(field)** 部分。与 ``selectMax()`` 一样，可以选择包含第二个参数来重命名结果字段。 .. literalinclude:: query_builder/011.php $builder->selectAvg() --------------------- -为你的查询编写 **SELECT AVG(field)** 部分。与 ``selectMax()`` 类似，你可以选择包含第二个参数以重命名结果字段。 +为查询编写 **SELECT AVG(field)** 部分。与 ``selectMax()`` 一样，可以选择包含第二个参数来重命名结果字段。 .. literalinclude:: query_builder/012.php $builder->selectSum() --------------------- -为你的查询编写 **SELECT SUM(field)** 部分。与 ``selectMax()`` 类似，你可以选择包含第二个参数以重命名结果字段。 +为查询编写 **SELECT SUM(field)** 部分。与 ``selectMax()`` 一样，可以选择包含第二个参数来重命名结果字段。 .. literalinclude:: query_builder/013.php $builder->selectCount() ----------------------- -为你的查询编写 **SELECT COUNT(field)** 部分。与 ``selectMax()`` 类似，你可以选择包含第二个参数以重命名结果字段。 +为查询编写 **SELECT COUNT(field)** 部分。与 ``selectMax()`` 一样，可以选择包含第二个参数来重命名结果字段。 -.. note:: 此方法在与 ``groupBy()`` 结合使用时特别有用。对于一般计数，请参见 ``countAll()`` 或 ``countAllResults()``。 +.. note:: 此方法在与 ``groupBy()`` 一起使用时特别有用。对于一般性的结果计数，请参阅 ``countAll()`` 或 ``countAllResults()``。 .. literalinclude:: query_builder/014.php @@ -171,7 +184,7 @@ From $builder->from() ---------------- -允许你编写查询的 **FROM** 部分： +允许编写查询的 **FROM** 部分： .. literalinclude:: query_builder/016.php @@ -185,13 +198,13 @@ $builder->from() $builder->fromSubquery() ------------------------ -允许你将 **FROM** 查询的一部分作为子查询编写。 +允许将 **FROM** 查询的一部分编写为子查询。 -这是将子查询添加到现有表的位置： +以下示例向现有表添加子查询： .. literalinclude:: query_builder/017.php -使用 ``$db->newQuery()`` 方法将子查询作为主表： +使用 ``$db->newQuery()`` 方法使子查询成为主表： .. literalinclude:: query_builder/018.php @@ -203,13 +216,13 @@ Join $builder->join() ---------------- -允许你编写查询的 **JOIN** 部分： +允许编写查询的 **JOIN** 部分： .. literalinclude:: query_builder/019.php 如果在一个查询中需要多个连接，可以进行多次方法调用。 -如果需要特定类型的 **JOIN**，可以通过该方法的第三个参数指定。选项包括：``left``、``right``、``outer``、``inner``、``left outer`` 和 ``right outer``。 +如果需要特定类型的 **JOIN**，可以通过方法的第三个参数指定。选项有：``left``、``right``、``outer``、``inner``、``left outer`` 和 ``right outer``。 .. literalinclude:: query_builder/020.php @@ -220,11 +233,11 @@ RawSql .. versionadded:: 4.2.0 -自 v4.2.0 起，``$builder->join()`` 接受表示原始 SQL 字符串的 ``CodeIgniter\Database\RawSql`` 实例作为 JOIN ON 条件。 +从 v4.2.0 开始，``$builder->join()`` 接受一个 ``CodeIgniter\Database\RawSql`` 实例作为 JOIN ON 条件，它表示原始 SQL 字符串。 .. literalinclude:: query_builder/102.php -.. warning:: 使用 ``RawSql`` 时，你必须手动转义值并保护标识符。否则可能导致 SQL 注入。 +.. warning:: 使用 ``RawSql`` 时，必须手动转义值并保护标识符。否则可能导致 SQL 注入。 ************************* 查找特定数据 @@ -236,47 +249,49 @@ Where $builder->where() ----------------- -此方法允许你使用五种方法之一设置 **WHERE** 子句： +此方法允许使用五种方式设置 **WHERE** 子句： -.. note:: 传递给此方法的所有值都会自动转义，从而生成更安全的查询，除非使用自定义字符串。 +.. note:: 传递给此方法的所有值都会自动转义， + 产生更安全的查询，除非使用自定义字符串。 -.. note:: ``$builder->where()`` 接受可选的第三个参数。如果将其设置为 ``false``，CodeIgniter 将不会尝试保护你的字段或表名。 +.. note:: ``$builder->where()`` 接受一个可选的第三个参数。如果将其设置为 + ``false``，CodeIgniter 将不会尝试保护字段或表名。 -1. 简单键/值方法 +1. 简单键/值方式 ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. literalinclude:: query_builder/021.php - 注意等号已为你添加。 + 注意，等号会为你自动添加。 - 如果多次调用该方法，它们将通过 **AND** 链接： + 如果使用多个方法调用，它们将用 **AND** 连接在一起： .. literalinclude:: query_builder/022.php -2. 自定义键/值方法 +2. 自定义键/值方式 ^^^^^^^^^^^^^^^^^^^^^^^^^^ - 你可以在第一个参数中包含运算符以控制比较： + 可以在第一个参数中包含运算符以控制比较： .. literalinclude:: query_builder/023.php -3. 关联数组方法 +3. 关联数组方式 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. literalinclude:: query_builder/024.php - 你也可以使用此方法包含自己的运算符： + 也可以使用此方法包含自己的运算符： .. literalinclude:: query_builder/025.php 4. 自定义字符串 ^^^^^^^^^^^^^^^^ - 你可以手动编写自己的子句： + 可以手动编写自己的子句： .. literalinclude:: query_builder/026.php - .. warning:: 如果在字符串中使用用户提供的数据，你必须手动转义值并保护标识符。否则可能导致 SQL 注入。 + .. warning:: 如果在字符串中使用用户提供的数据，必须手动转义值并保护标识符。否则可能导致 SQL 注入。 .. literalinclude:: query_builder/027.php @@ -287,11 +302,11 @@ $builder->where() .. versionadded:: 4.2.0 - 自 v4.2.0 起，``$builder->where()`` 接受表示原始 SQL 字符串的 ``CodeIgniter\Database\RawSql`` 实例。 + 从 v4.2.0 开始，``$builder->where()`` 接受一个 ``CodeIgniter\Database\RawSql`` 实例，它表示原始 SQL 字符串。 .. literalinclude:: query_builder/100.php - .. warning:: 使用 ``RawSql`` 时，你必须手动转义值并保护标识符。否则可能导致 SQL 注入。 + .. warning:: 使用 ``RawSql`` 时，必须手动转义值并保护标识符。否则可能导致 SQL 注入。 .. _query-builder-where-subquery: @@ -303,51 +318,51 @@ $builder->where() $builder->orWhere() ------------------- -此方法与上述方法相同，区别在于多个实例通过 **OR** 连接： +此方法与上述方法相同，只是多个实例通过 **OR** 连接： .. literalinclude:: query_builder/029.php $builder->whereIn() ------------------- -生成 **WHERE field IN ('item', 'item')** SQL 查询，并在适当时通过 **AND** 连接： +生成一个 **WHERE field IN ('item', 'item')** SQL 查询，在适当时用 **AND** 连接： .. literalinclude:: query_builder/030.php -你可以使用子查询代替值数组： +可以使用子查询代替值数组： .. literalinclude:: query_builder/031.php $builder->orWhereIn() --------------------- -生成 **WHERE field IN ('item', 'item')** SQL 查询，并在适当时通过 **OR** 连接： +生成一个 **WHERE field IN ('item', 'item')** SQL 查询，在适当时用 **OR** 连接： .. literalinclude:: query_builder/032.php -你可以使用子查询代替值数组： +可以使用子查询代替值数组： .. literalinclude:: query_builder/033.php $builder->whereNotIn() ---------------------- -生成 **WHERE field NOT IN ('item', 'item')** SQL 查询，并在适当时通过 **AND** 连接： +生成一个 **WHERE field NOT IN ('item', 'item')** SQL 查询，在适当时用 **AND** 连接： .. literalinclude:: query_builder/034.php -你可以使用子查询代替值数组： +可以使用子查询代替值数组： .. literalinclude:: query_builder/035.php $builder->orWhereNotIn() ------------------------ -生成 **WHERE field NOT IN ('item', 'item')** SQL 查询，并在适当时通过 **OR** 连接： +生成一个 **WHERE field NOT IN ('item', 'item')** SQL 查询，在适当时用 **OR** 连接： .. literalinclude:: query_builder/036.php -你可以使用子查询代替值数组： +可以使用子查询代替值数组： .. literalinclude:: query_builder/037.php @@ -361,26 +376,26 @@ Like $builder->like() ---------------- -此方法允许你生成 **LIKE** 子句，适用于执行搜索。 +此方法允许生成 **LIKE** 子句，用于执行搜索。 .. note:: 传递给此方法的所有值都会自动转义。 -.. note:: 所有 ``like*`` 方法变体可以通过将第五个参数设置为 ``true`` 来强制执行不区分大小写的搜索。这将使用平台特定的功能（如果可用），否则将强制将值转换为小写，即 ``WHERE LOWER(column) LIKE '%search%'``。这可能需要在 ``LOWER(column)`` 而非 ``column`` 上创建索引才能生效。 +.. note:: 所有 ``like*`` 方法变体可以通过向方法传递第五个参数 ``true`` 来强制执行不区分大小写的搜索。这将使用平台特定的功能（如果可用），否则将强制值为小写，即 ``WHERE LOWER(column) LIKE '%search%'``。这可能需要为 ``LOWER(column)`` 而不是 ``column`` 创建索引才能有效。 -1. 简单键/值方法 +1. 简单键/值方方式 ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. literalinclude:: query_builder/038.php - 如果多次调用该方法，它们将通过 **AND** 链接： + 如果使用多个方法调用，它们将用 **AND** 连接在一起： .. literalinclude:: query_builder/039.php - 如果要控制通配符（ **%** ）的位置，可以使用可选的第三个参数。选项为 ``before``、``after`` 和 ``both`` （默认）。 + 如果想控制通配符（**%**）放置的位置，可以使用可选的第三个参数。选项有 ``before``、``after`` 和 ``both`` （默认）。 .. literalinclude:: query_builder/040.php -2. 关联数组方法 +2. 关联数组方式 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. literalinclude:: query_builder/041.php @@ -392,41 +407,41 @@ $builder->like() .. versionadded:: 4.2.0 - 自 v4.2.0 起，``$builder->like()`` 接受表示原始 SQL 字符串的 ``CodeIgniter\Database\RawSql`` 实例。 + 从 v4.2.0 开始，``$builder->like()`` 接受一个 ``CodeIgniter\Database\RawSql`` 实例，它表示原始 SQL 字符串。 .. literalinclude:: query_builder/101.php - .. warning:: 使用 ``RawSql`` 时，你必须手动转义值并保护标识符。否则可能导致 SQL 注入。 + .. warning:: 使用 ``RawSql`` 时，必须手动转义值并保护标识符。否则可能导致 SQL 注入。 $builder->orLike() ------------------ -此方法与上述方法相同，区别在于多个实例通过 **OR** 连接： +此方法与上述方法相同，只是多个实例通过 **OR** 连接： .. literalinclude:: query_builder/042.php $builder->notLike() ------------------- -此方法与 ``like()`` 相同，但生成 **NOT LIKE** 语句： +此方法与 ``like()`` 相同，只是它生成 **NOT LIKE** 语句： .. literalinclude:: query_builder/043.php $builder->orNotLike() --------------------- -此方法与 ``notLike()`` 相同，但多个实例通过 **OR** 连接： +此方法与 ``notLike()`` 相同，只是多个实例通过 **OR** 连接： .. literalinclude:: query_builder/044.php $builder->groupBy() ------------------- -允许你编写查询的 **GROUP BY** 部分： +允许编写查询的 **GROUP BY** 部分： .. literalinclude:: query_builder/045.php -你也可以传递多个值的数组： +也可以传递多个值的数组： .. literalinclude:: query_builder/046.php @@ -440,90 +455,90 @@ $builder->distinct() $builder->having() ------------------ -允许你编写查询的 **HAVING** 部分。有两种可能的语法，1 个参数或 2 个： +允许编写查询的 **HAVING** 部分。有 2 种可能的语法，1 个参数或 2 个参数： .. literalinclude:: query_builder/048.php -你也可以传递多个值的数组： +也可以传递多个值的数组： .. literalinclude:: query_builder/049.php -如果你使用的数据库由 CodeIgniter 转义值，可以通过传递可选的第三个参数并设置为 ``false`` 来防止转义内容。 +如果使用的数据库由 CodeIgniter 负责转义值，可以通过传递可选的第三个参数并将其设置为 ``false`` 来防止内容被转义。 .. literalinclude:: query_builder/050.php $builder->orHaving() -------------------- -与 ``having()`` 相同，但多个子句通过 **OR** 分隔。 +与 ``having()`` 相同，只是用 **OR** 分隔多个子句。 $builder->havingIn() -------------------- -生成 **HAVING field IN ('item', 'item')** SQL 查询，并在适当时通过 **AND** 连接： +生成一个 **HAVING field IN ('item', 'item')** SQL 查询，在适当时用 **AND** 连接： .. literalinclude:: query_builder/051.php -你可以使用子查询代替值数组： +可以使用子查询代替值数组： .. literalinclude:: query_builder/052.php $builder->orHavingIn() ---------------------- -生成 **HAVING field IN ('item', 'item')** SQL 查询，并在适当时通过 **OR** 连接： +生成一个 **HAVING field IN ('item', 'item')** SQL 查询，在适当时用 **OR** 连接： .. literalinclude:: query_builder/053.php -你可以使用子查询代替值数组： +可以使用子查询代替值数组： .. literalinclude:: query_builder/054.php $builder->havingNotIn() ----------------------- -生成 **HAVING field NOT IN ('item', 'item')** SQL 查询，并在适当时通过 **AND** 连接： +生成一个 **HAVING field NOT IN ('item', 'item')** SQL 查询，在适当时用 **AND** 连接： .. literalinclude:: query_builder/055.php -你可以使用子查询代替值数组： +可以使用子查询代替值数组： .. literalinclude:: query_builder/056.php $builder->orHavingNotIn() ------------------------- -生成 **HAVING field NOT IN ('item', 'item')** SQL 查询，并在适当时通过 **OR** 连接： +生成一个 **HAVING field NOT IN ('item', 'item')** SQL 查询，在适当时用 **OR** 连接： .. literalinclude:: query_builder/057.php -你可以使用子查询代替值数组： +可以使用子查询代替值数组： .. literalinclude:: query_builder/058.php $builder->havingLike() ---------------------- -此方法允许你为查询的 **HAVING** 部分生成 **LIKE** 子句，适用于执行搜索。 +此方法允许为查询的 **HAVING** 部分生成 **LIKE** 子句，用于执行搜索。 .. note:: 传递给此方法的所有值都会自动转义。 -.. note:: 所有 ``havingLike*()`` 方法变体可以通过将第五个参数设置为 ``true`` 来强制执行不区分大小写的搜索。这将使用平台特定的功能（如果可用），否则将强制将值转换为小写，即 ``HAVING LOWER(column) LIKE '%search%'``。这可能需要在 ``LOWER(column)`` 而非 ``column`` 上创建索引才能生效。 +.. note:: 所有 ``havingLike*()`` 方法变体可以通过向方法传递第五个参数 ``true`` 来强制执行不区分大小写的搜索。这将使用平台特定的功能（如果可用），否则将强制值为小写，即 ``HAVING LOWER(column) LIKE '%search%'``。这可能需要为 ``LOWER(column)`` 而不是 ``column`` 创建索引才能有效。 -1. 简单键/值方法 +1. 简单键/值方式 ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. literalinclude:: query_builder/059.php - 如果多次调用该方法，它们将通过 **AND** 链接： + 如果使用多个方法调用，它们将用 **AND** 连接在一起： .. literalinclude:: query_builder/060.php - 如果要控制通配符（ **%** ）的位置，可以使用可选的第三个参数。选项为 ``before``、``after`` 和 ``both`` （默认）。 + 如果想控制通配符（**%**）放置的位置，可以使用可选的第三个参数。选项有 ``before``、``after`` 和 ``both`` （默认）。 .. literalinclude:: query_builder/061.php -2. 关联数组方法 +2. 关联数组方式 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. literalinclude:: query_builder/062.php @@ -531,21 +546,21 @@ $builder->havingLike() $builder->orHavingLike() ------------------------ -此方法与上述方法相同，区别在于多个实例通过 **OR** 连接： +此方法与上述方法相同，只是多个实例通过 **OR** 连接： .. literalinclude:: query_builder/063.php $builder->notHavingLike() ------------------------- -此方法与 ``havingLike()`` 相同，但生成 **NOT LIKE** 语句： +此方法与 ``havingLike()`` 相同，只是它生成 **NOT LIKE** 语句： .. literalinclude:: query_builder/064.php $builder->orNotHavingLike() --------------------------- -此方法与 ``notHavingLike()`` 相同，但多个实例通过 **OR** 连接： +此方法与 ``notHavingLike()`` 相同，只是多个实例通过 **OR** 连接： .. literalinclude:: query_builder/065.php @@ -559,15 +574,16 @@ OrderBy $builder->orderBy() ------------------- -允许你设置 **ORDER BY** 子句。 +允许设置 **ORDER BY** 子句。 -第一个参数包含要排序的列名。 +第一个参数包含要排序的字段名。 -第二个参数允许你设置结果的方向。选项为 ``ASC``、``DESC`` 和 ``RANDOM``。 +第二个参数允许设置结果的排序方式。 +选项有 ``ASC``、``DESC`` 和 ``RANDOM``。 .. literalinclude:: query_builder/066.php -你也可以在第一个参数中传递自己的字符串： +也可以在第一个参数中传递自己的字符串： .. literalinclude:: query_builder/067.php @@ -575,7 +591,7 @@ $builder->orderBy() .. literalinclude:: query_builder/068.php -如果选择 ``RANDOM`` 方向选项，除非指定数字种子值，否则将忽略第一个参数。 +如果选择 ``RANDOM`` 方向选项，则将忽略第一个参数，除非指定数字种子值。 .. literalinclude:: query_builder/069.php @@ -589,35 +605,38 @@ Limit $builder->limit() ----------------- -允许你限制查询返回的行数： +允许限制查询返回的行数： .. literalinclude:: query_builder/070.php -.. note:: 如果在 SQL 语句中指定了 ``LIMIT 0``，将返回 0 条记录。然而，在查询构建器中存在一个错误：如果指定 ``limit(0)``，生成的 SQL 语句将没有 ``LIMIT`` 子句，并返回所有记录。在 v4.5.0 中添加了设置以修复此错误行为。详细信息请参阅 :ref:`v450-query-builder-limit-0-behavior`。此错误行为将在未来版本中修复，因此建议你更改默认设置。 +.. note:: 如果在 SQL 语句中指定 ``LIMIT 0``，将返回 0 条记录。 + 然而，查询构建器中有一个错误，如果指定 ``limit(0)``， + 生成的 SQL 语句将没有 ``LIMIT`` 子句，所有记录都将被返回。为了修复此错误行为，在 v4.5.0 中添加了一个设置。参见 + :ref:`v450-query-builder-limit-0-behavior` 了解详细信息。此错误行为将在未来版本中修复，因此建议更改默认设置。 -第二个参数允许你设置结果偏移量。 +第二个参数允许设置结果偏移量。 .. literalinclude:: query_builder/071.php $builder->countAllResults() --------------------------- -允许你确定特定查询构建器查询中的行数。查询支持查询构建器的限制条件，如 ``where()``、``orWhere()``、``like()``、``orLike()`` 等。示例： +允许确定特定查询构建器查询中的行数。支持查询构建器的限制条件，如 ``where()``、``orWhere()``、``like()``、``orLike()`` 等。示例： .. literalinclude:: query_builder/072.php -但是，此方法还会重置你可能传递给 ``select()`` 的任何字段值。如果需要保留它们，可以将第一个参数传递为 ``false``。 +然而，此方法还会重置你可能已传递给 ``select()`` 的任何字段值。如果需要保留它们，可以将 ``false`` 作为第一个参数传递。 .. literalinclude:: query_builder/073.php $builder->countAll() -------------------- -允许你确定特定表中的行数。示例： +允许确定特定表中的行数。示例： .. literalinclude:: query_builder/074.php -与 ``countAllResult()`` 方法类似，此方法也会重置你可能传递给 ``select()`` 的任何字段值。如果需要保留它们，可以将第一个参数传递为 ``false``。 +与 ``countAllResult()`` 方法一样，此方法也会重置你可能已传递给 ``select()`` 的字段值。如果需要保留它们，可以将 ``false`` 作为第一个参数传递。 .. _query-builder-union: @@ -631,22 +650,26 @@ Union $builder->union() ----------------- -用于组合两个或多个 SELECT 语句的结果集。它将仅返回唯一结果。 +用于组合两个或多个 SELECT 语句的结果集。它将只返回唯一的结果。 .. literalinclude:: query_builder/103.php -.. note:: 为了与 DBMS（如 MSSQL 和 Oracle）正确配合，查询会被包装在 ``SELECT * FROM ( ... ) alias`` 中。主查询将始终具有别名 ``uwrp0``。通过 ``union()`` 添加的每个后续查询将具有别名 ``uwrpN+1``。 +.. note:: 为了与 DBMS（如 MSSQL 和 Oracle）正常工作，查询被包装在 ``SELECT * FROM ( ... ) alias`` 中。 + 主查询将始终具有别名 ``uwrp0``。通过 ``union()`` 添加的每个后续查询将具有别名 ``uwrpN+1``。 -所有联合查询将添加在主查询之后，无论 ``union()`` 方法的调用顺序如何。也就是说，即使在调用 ``union()`` 之后调用 ``limit()`` 或 ``orderBy()`` 方法，这些方法也将相对于主查询。 +所有联合查询都将在主查询之后添加，无论 ``union()`` 方法的调用顺序如何。 +也就是说，``limit()`` 或 ``orderBy()`` 方法将相对于主查询，即使在 ``union()`` 之后调用也是如此。 -在某些情况下，可能需要对查询结果进行排序或限制记录数。解决方案是使用通过 ``$db->newQuery()`` 创建的包装器。在下面的示例中，我们获取前 5 个用户 + 后 5 个用户并按 id 排序结果： +在某些情况下，可能需要对查询结果进行排序或限制记录数。 +解决方案是使用通过 ``$db->newQuery()`` 创建的包装器。 +在下面的示例中，我们获取前 5 个用户 + 最后 5 个用户，并按 id 对结果进行排序： .. literalinclude:: query_builder/104.php $builder->unionAll() -------------------- -行为与 ``union()`` 方法相同。但是，将返回所有结果，而不仅仅是唯一结果。 +行为与 ``union()`` 方法相同。然而，将返回所有结果，而不仅仅是唯一的结果。 ************** 查询分组 @@ -655,7 +678,7 @@ $builder->unionAll() Group ===== -查询分组允许你通过将 **WHERE** 子句括在括号中来创建分组。这将允许你创建具有复杂 **WHERE** 子句的查询。支持嵌套分组。示例： +查询分组允许通过将 **WHERE** 子句括在括号中来创建 **WHERE** 子句组。这样就可以创建具有复杂 **WHERE** 子句的查询。支持嵌套分组。示例： .. literalinclude:: query_builder/075.php @@ -664,72 +687,72 @@ Group $builder->groupStart() ---------------------- -通过向查询的 **WHERE** 子句添加左括号开始新分组。 +通过向查询的 **WHERE** 子句添加左括号来开始新组。 $builder->orGroupStart() ------------------------ -通过向查询的 **WHERE** 子句添加左括号开始新分组，并添加前缀 **OR**。 +通过向查询的 **WHERE** 子句添加左括号来开始新分组，前缀为 **OR**。 $builder->notGroupStart() ------------------------- -通过向查询的 **WHERE** 子句添加左括号开始新分组，并添加前缀 **NOT**。 +通过向查询的 **WHERE** 子句添加左括号来开始新分组，前缀为 **NOT**。 $builder->orNotGroupStart() --------------------------- -通过向查询的 **WHERE** 子句添加左括号开始新分组，并添加前缀 **OR NOT**。 +通过向查询的 **WHERE** 子句添加左括号来开始新分组，前缀为 **OR NOT**。 $builder->groupEnd() -------------------- -通过向查询的 **WHERE** 子句添加右括号结束当前分组。 +通过向查询的 **WHERE** 子句添加右括号来结束当前组。 $builder->havingGroupStart() ---------------------------- -通过向查询的 **HAVING** 子句添加左括号开始新分组。 +通过向查询的 **HAVING** 子句添加左括号来开始新组。 $builder->orHavingGroupStart() ------------------------------ -通过向查询的 **HAVING** 子句添加左括号开始新分组，并添加前缀 **OR**。 +通过向查询的 **HAVING** 子句添加左括号来开始新分组，前缀为 **OR**。 $builder->notHavingGroupStart() ------------------------------- -通过向查询的 **HAVING** 子句添加左括号开始新分组，并添加前缀 **NOT**。 +通过向查询的 **HAVING** 子句添加左括号来开始新分组，前缀为 **NOT**。 $builder->orNotHavingGroupStart() --------------------------------- -通过向查询的 **HAVING** 子句添加左括号开始新分组，并添加前缀 **OR NOT**。 +通过向查询的 **HAVING** 子句添加左括号来开始新分组，前缀为 **OR NOT**。 $builder->havingGroupEnd() -------------------------- -通过向查询的 **HAVING** 子句添加右括号结束当前分组。 +通过向查询的 **HAVING** 子句添加右括号来结束当前分组。 ************** 插入数据 ************** -Insert +插入 ====== $builder->insert() ------------------ -根据你提供的数据生成 insert 字符串并运行查询。你可以向该方法传递 **数组** 或 **对象**。以下是使用数组的示例： +根据提供的数据生成插入字符串并运行查询。可以向方法传递 **数组** 或 **对象**。以下是使用数组的示例： .. literalinclude:: query_builder/076.php 第一个参数是值的关联数组。 -.. note:: 除 ``RawSql`` 外，所有值都会自动转义，生成更安全的查询。 +.. note:: 除 ``RawSql`` 外的所有值都会自动转义，生成更安全的查询。 -.. warning:: 使用 ``RawSql`` 时，你必须手动转义数据。否则可能导致 SQL 注入。 +.. warning:: 使用 ``RawSql`` 时，必须手动转义数据。否则可能导致 SQL 注入。 以下是使用对象的示例： @@ -737,29 +760,32 @@ $builder->insert() .. literalinclude:: query_builder/121.php -第一个参数是一个对象。 +第一个参数是对象。 $builder->ignore() ------------------ -根据你提供的数据生成 insert ignore 字符串并运行查询。因此，如果具有相同主键的条目已存在，则不会插入该查询。你可以选择向该方法传递 **布尔值**。也可用于 **insertBatch**、**update** 和 **delete** （在支持时）。以下是使用上述示例数组的示例： +根据提供的数据生成插入忽略字符串并运行查询。如果已存在具有相同主键的条目，则不会插入该查询。 +可以选择向方法传递 **布尔值**。也可以用于 **insertBatch**、**update** 和 **delete** （在支持时）。 +以下是使用上述示例数组的示例： .. literalinclude:: query_builder/078.php $builder->getCompiledInsert() ----------------------------- -像 ``$builder->insert()`` 一样编译插入查询，但不会 *运行* 查询。此方法仅以字符串形式返回 SQL 查询。 +像 ``$builder->insert()`` 一样编译插入查询，但不 *运行* 查询。此方法只是将 SQL 查询作为字符串返回。 示例： .. literalinclude:: query_builder/079.php -第一个参数允许你设置是否重置查询构建器查询（默认情况下会重置，就像使用 ``$builder->insert()`` 一样）： +第一个参数允许设置是否重置查询构建器查询 +（默认情况下它会像 ``$builder->insert()`` 一样被重置）： .. literalinclude:: query_builder/080.php -第二个查询起作用的原因是第一个参数设置为 ``false``。 +第二个查询有效的原因是第一个参数设置为 ``false``。 .. note:: 此方法不适用于批量插入。 @@ -774,31 +800,31 @@ $builder->insertBatch() 从数据插入 ^^^^^^^^^^^^^^^^ -根据你提供的数据生成 insert 字符串并运行查询。你可以向该方法传递 **数组** 或 **对象**。以下是使用数组的示例： +根据提供的数据生成插入字符串并运行查询。可以向方法传递 **数组** 或 **对象**。以下是使用数组的示例： .. literalinclude:: query_builder/081.php 第一个参数是值的关联数组。 -.. note:: 除 ``RawSql`` 外，所有值都会自动转义，生成更安全的查询。 +.. note:: 除 ``RawSql`` 外的所有值都会自动转义，生成更安全的查询。 -.. warning:: 使用 ``RawSql`` 时，你必须手动转义数据。否则可能导致 SQL 注入。 +.. warning:: 使用 ``RawSql`` 时，必须手动转义数据。否则可能导致 SQL 注入。 从查询插入 ^^^^^^^^^^^^^^^^^^^ -你也可以从查询插入： +也可以从查询插入： .. literalinclude:: query_builder/117.php -.. note:: 自 v4.3.0 起，可以使用 ``setQueryAsData()``。 +.. note:: 从 v4.3.0 开始可以使用 ``setQueryAsData()``。 -.. note:: 必须将 select 查询的列别名与目标表的列匹配。 +.. note:: 需要为选择查询的字段设置别名以匹配目标表的字段。 .. _upsert-data: ************** -更新插入数据 +Upsert 数据 ************** Upsert @@ -809,11 +835,13 @@ $builder->upsert() .. versionadded:: 4.3.0 -根据你提供的数据生成更新插入字符串并运行查询。你可以向该方法传递 **数组** 或 **对象**。默认情况下，将按顺序定义约束。首先选择主键，然后是唯一键。MySQL 将默认使用任何约束。以下是使用数组的示例： +根据提供的数据生成 upsert 字符串并运行查询。可以向方法传递 **数组** 或 **对象**。默认情况下，约束将按顺序定义。将首先选择主键，然后选择唯一键。MySQL 默认将使用任何约束。以下是使用数组的示例： .. literalinclude:: query_builder/112.php -.. note:: 对于非 MySQL 的数据库，如果一个表包含多个键（主键或唯一键），在处理约束时默认会优先使用主键。如果你希望使用其他唯一键而非主键，请使用 ``onConstraint()`` 方法。 +.. note:: 对于 MySQL 之外的数据库，如果表有多个键（主键或唯一键）， + 在处理约束时默认将优先考虑主键。如果希望 + 使用不同的唯一键而不是主键，请使用 ``onConstraint()`` 方法。 第一个参数是值的关联数组。 @@ -823,7 +851,7 @@ $builder->upsert() .. literalinclude:: query_builder/113.php -第一个参数是一个对象。 +第一个参数是对象。 .. note:: 所有值都会自动转义，生成更安全的查询。 @@ -832,13 +860,13 @@ $builder->getCompiledUpsert() .. versionadded:: 4.3.0 -像 ``$builder->upsert()`` 一样编译更新插入查询，但不会 *运行* 查询。此方法仅以字符串形式返回 SQL 查询。 +像 ``$builder->upsert()`` 一样编译 upsert 查询，但不 *运行* 查询。此方法只是将 SQL 查询作为字符串返回。 示例： .. literalinclude:: query_builder/114.php -.. note:: 此方法不适用于批量更新插入。 +.. note:: 此方法不适用于批量 upsert。 upsertBatch =========== @@ -848,10 +876,10 @@ $builder->upsertBatch() .. versionadded:: 4.3.0 -从数据更新插入 +从数据 Upsert ^^^^^^^^^^^^^^^^ -根据你提供的数据生成更新插入字符串并运行查询。你可以向该方法传递 **数组** 或 **对象**。默认情况下，将按顺序定义约束。首先选择主键，然后是唯一键。MySQL 将默认使用任何约束。 +根据提供的数据生成 upsert 字符串并运行查询。可以向方法传递 **数组** 或 **对象**。默认情况下，约束将按顺序定义。将首先选择主键，然后选择唯一键。MySQL 默认将使用任何约束。 以下是使用数组的示例： @@ -861,81 +889,90 @@ $builder->upsertBatch() .. note:: 所有值都会自动转义，生成更安全的查询。 -从查询更新插入 +从查询 Upsert ^^^^^^^^^^^^^^^^^^^ -你也可以从查询更新插入： +也可以从查询进行 upsert： .. literalinclude:: query_builder/115.php -.. note:: 自 v4.3.0 起，可以使用 ``setQueryAsData()``、``onConstraint()`` 和 ``updateFields()`` 方法。 +.. note:: 从 v4.3.0 开始可以使用 ``setQueryAsData()``、``onConstraint()`` 和 ``updateFields()`` + 方法。 -.. note:: 必须将 select 查询的列别名与目标表的列匹配。 +.. note:: 需要为选择查询的字段设置别名以匹配目标表的字段。 $builder->onConstraint() ------------------------ .. versionadded:: 4.3.0 -允许手动设置用于更新插入的约束。这不适用于 MySQL，因为 MySQL 默认检查所有约束。 +允许手动设置用于 upsert 的约束。这不适用于 MySQL，因为 MySQL 默认检查所有约束。 .. literalinclude:: query_builder/109.php -此方法接受字符串或列数组。 +此方法接受字符串或字段数组。 $builder->updateFields() ------------------------ .. versionadded:: 4.3.0 -允许手动设置执行更新插入时要更新的字段。 +允许手动设置执行 upsert 时要更新的字段。 .. literalinclude:: query_builder/110.php -此方法接受字符串、列数组或 RawSql。你还可以指定不包含在数据集中的额外列进行更新。这可以通过将第二个参数设置为 ``true`` 来实现。 +此方法接受字符串、字段数组或 RawSql。还可以指定要更新的额外字段，该字段不包含在数据集中。 +可以通过将第二个参数设置为 ``true`` 来完成此操作。 .. literalinclude:: query_builder/111.php -注意 ``updated_at`` 字段未插入，但用于更新。 +注意，``updated_at`` 字段未插入，但在更新时使用。 ************* 更新数据 ************* -Update +更新 ====== $builder->replace() ------------------- -此方法执行 **REPLACE** 语句，本质上是 SQL 标准的（可选） **DELETE** + **INSERT**，使用 *PRIMARY* 和 *UNIQUE* 作为决定因素。在我们的案例中，它将使你无需通过组合不同的 ``select()``、``update()``、``delete()`` 和 ``insert()`` 调用来实现复杂逻辑。 +此方法执行 **REPLACE** 语句，这基本上是 SQL +标准中的（可选） **DELETE** + **INSERT**，使用 *主键* 和 *唯一键* +作为决定条件。 +在我们的情况下，它将使你无需实现复杂的 +逻辑，无需使用 ``select()``、``update()``、 +``delete()`` 和 ``insert()`` 调用的各种组合。 示例： .. literalinclude:: query_builder/082.php -在上述示例中，如果我们假设 ``title`` 字段是主键，则包含 ``My title`` 作为 ``title`` 值的行将被删除，并用我们的新行数据替换。 +在上述示例中，如果我们假设 ``title`` 字段是主键， +那么如果一行包含 ``My title`` 作为 ``title`` 值，该行将被删除， +我们的新行数据将替换它。 -也允许使用 ``set()`` 方法，并且所有值都会自动转义，就像 ``insert()`` 一样。 +也允许使用 ``set()`` 方法，所有值都会自动转义，就像使用 ``insert()`` 一样。 $builder->set() --------------- -此方法允许你为插入或更新设置值。 +此方法允许为插入或更新设置值。 -**它可以代替直接向 insert() 或 update() 方法传递数据数组：** +**它可以用来代替直接向 insert() 或 update() 方法传递数据数组：** .. literalinclude:: query_builder/083.php -如果多次调用该方法，它们将根据你执行的是插入还是更新正确组装： +如果使用多个方法调用，它们将根据你是执行插入还是更新来正确组装： .. literalinclude:: query_builder/084.php -``set()`` 也接受可选的第三个参数（``$escape``），如果设置为 ``false``，将防止值被转义。为了说明差异，以下是使用和不使用转义参数的 ``set()``。 +``set()`` 还将接受可选的第三个参数（``$escape``），如果设置为 ``false``，将防止值被转义。为了说明区别，以下是使用和不使用转义参数的 ``set()``。 .. literalinclude:: query_builder/085.php -你也可以向此方法传递关联数组： +也可以向此方法传递关联数组： .. literalinclude:: query_builder/086.php @@ -948,21 +985,21 @@ $builder->set() $builder->update() ------------------ -根据你提供的数据生成 update 字符串并运行查询。你可以传递 **数组** 或 **对象**。以下是使用数组的示例： +生成 update 字符串并根据提供的数据运行查询。可以向方法传递 **数组** 或 **对象**。以下是使用数组的示例： .. literalinclude:: query_builder/088.php -或者你可以提供对象： +或可以提供对象： .. literalinclude:: query_builder/077.php .. literalinclude:: query_builder/089.php -.. note:: 除 ``RawSql`` 外，所有值都会自动转义，生成更安全的查询。 +.. note:: 除 ``RawSql`` 外的所有值都会自动转义，生成更安全的查询。 -.. warning:: 使用 ``RawSql`` 时，你必须手动转义数据。否则可能导致 SQL 注入。 +.. warning:: 使用 ``RawSql`` 时，必须手动转义数据。否则可能导致 SQL 注入。 -你会注意到使用 ``$builder->where()`` 方法，允许你设置 **WHERE** 子句。你可以直接将此信息作为字符串传递到 ``update()`` 方法中： +你会注意到使用了 ``$builder->where()`` 方法，允许设置 **WHERE** 子句。可以选择将此信息直接作为字符串传递到 ``update()`` 方法中： .. literalinclude:: query_builder/090.php @@ -970,14 +1007,14 @@ $builder->update() .. literalinclude:: query_builder/091.php -执行更新时，也可以使用上述的 ``$builder->set()`` 方法。 +执行更新时也可以使用上述的 ``$builder->set()`` 方法。 $builder->getCompiledUpdate() ----------------------------- -此方法与 ``$builder->getCompiledInsert()`` 的工作方式完全相同，区别在于生成的是 **UPDATE** SQL 字符串而非 **INSERT** SQL 字符串。 +这与 ``$builder->getCompiledInsert()`` 的工作方式完全相同，只是它生成 **UPDATE** SQL 字符串而不是 **INSERT** SQL 字符串。 -有关详细信息，请查看 `$builder->getCompiledInsert()`_ 的文档。 +有关更多信息，请查看 `$builder->getCompiledInsert()`_ 的文档。 .. note:: 此方法不适用于批量更新。 @@ -989,43 +1026,44 @@ UpdateBatch $builder->updateBatch() ----------------------- -.. note:: 自 v4.3.0 起，``updateBatch()`` 的第二个参数 ``$index`` 已更改为 ``$constraints``。现在接受数组、字符串或 ``RawSql`` 类型。 +.. note:: 从 v4.3.0 开始，``updateBatch()`` 的第二个参数 ``$index`` 已 + 更改为 ``$constraints``。它现在接受数组、字符串或 ``RawSql`` 类型。 从数据更新 ^^^^^^^^^^^^^^^^ -根据你提供的数据生成 update 字符串并运行查询。你可以向该方法传递 **数组** 或 **对象**。以下是使用数组的示例： +根据提供的数据生成 update 字符串并运行查询。可以向方法传递 **数组** 或 **对象**。以下是使用数组的示例： .. literalinclude:: query_builder/092.php 第一个参数是值的关联数组，第二个参数是 where 键。 -.. note:: 自 v4.3.0 起，生成的 SQL 结构已改进。 +.. note:: 从 v4.3.0 开始，生成的 SQL 结构已得到改进。 -自 v4.3.0 起，你也可以使用 ``onConstraint()`` 和 ``updateFields()`` 方法： +从 v4.3.0 开始，还可以使用 ``onConstraint()`` 和 ``updateFields()`` 方法： .. literalinclude:: query_builder/120.php -.. note:: 除 ``RawSql`` 外，所有值都会自动转义，生成更安全的查询。 +.. note:: 除 ``RawSql`` 外的所有值都会自动转义，生成更安全的查询。 -.. warning:: 使用 ``RawSql`` 时，你必须手动转义数据。否则可能导致 SQL 注入。 +.. warning:: 使用 ``RawSql`` 时，必须手动转义数据。否则可能导致 SQL 注入。 .. note:: 因为工作原理的原因，若使用此方法则 ``affectedRows()`` 无法提供正确的结果。相反，``updateBatch()`` 返回受影响的行数。 从查询更新 ^^^^^^^^^^^^^^^^^^^ -自 v4.3.0 起，你也可以使用 ``setQueryAsData()`` 方法从查询更新： +从 v4.3.0 开始，还可以使用 ``setQueryAsData()`` 方法从查询更新： .. literalinclude:: query_builder/116.php -.. note:: 必须将 select 查询的列别名与目标表的列匹配。 +.. note:: 需要为 select 查询的字段设置别名以匹配目标表的字段。 ************* 删除数据 ************* -Delete +删除 ====== $builder->delete() @@ -1035,7 +1073,8 @@ $builder->delete() .. literalinclude:: query_builder/093.php -第一个参数是 where 子句。你也可以使用 ``where()`` 或 ``orWhere()`` 方法，而不是将数据传递到方法的第一个参数： +第一个参数是 where 子句。 +也可以使用 ``where()`` 或 ``orWhere()`` 方法，而不是将数据传递给方法的第一个参数： .. literalinclude:: query_builder/094.php @@ -1044,9 +1083,9 @@ $builder->delete() $builder->getCompiledDelete() ----------------------------- -此方法与 ``$builder->getCompiledInsert()`` 的工作方式完全相同，区别在于生成的是 **DELETE** SQL 字符串而非 **INSERT** SQL 字符串。 +这与 ``$builder->getCompiledInsert()`` 的工作方式完全相同，只是它生成 **DELETE** SQL 字符串而不是 **INSERT** SQL 字符串。 -有关详细信息，请查看 `$builder->getCompiledInsert()`_ 的文档。 +有关更多信息，请查看 `$builder->getCompiledInsert()`_ 的文档。 .. _delete-batch: @@ -1061,7 +1100,7 @@ $builder->deleteBatch() 从数据删除 ^^^^^^^^^^^^^^^^ -根据一组数据生成批量 **DELETE** 语句。 +基于一组数据生成批量 **DELETE** 语句。 .. literalinclude:: query_builder/118.php @@ -1072,7 +1111,7 @@ $builder->deleteBatch() 从查询删除 ^^^^^^^^^^^^^^^^^^^ -你也可以从查询删除： +也可以从查询删除： .. literalinclude:: query_builder/119.php @@ -1090,7 +1129,7 @@ $builder->truncate() .. literalinclude:: query_builder/096.php -.. note:: 如果 TRUNCATE 命令不可用，``truncate()`` 将执行 "DELETE FROM table"。 +.. note:: 如果 TRUNCATE 命令不可用，``truncate()`` 将执行为 "DELETE FROM table"。 ********************** 条件语句 @@ -1106,15 +1145,18 @@ $builder->when() .. versionadded:: 4.3.0 -这允许根据条件修改查询而不破坏查询构建器链。第一个参数是条件，它应该评估为布尔值。第二个参数是一个可调用的函数，当条件为真时将运行该函数。 +这允许基于条件修改查询，而无需中断查询构建器链。第一个参数是条件，它使用 PHP 的原生布尔逻辑进行评估——这意味着像 ``false``、``null``、 +``0``、``'0'``、``0.0``、空字符串 ``''`` 和空数组 ``[]`` 这样的值将被视为 false。 +第二个参数是在条件为 true 时将运行的回调函数。 -例如，你可能希望仅根据 HTTP 请求中发送的值应用给定的 WHERE 语句： +例如，你可能只希望根据 HTTP 请求中发送的值应用给定的 WHERE 语句： .. literalinclude:: query_builder/105.php -由于条件评估为 ``true``，将调用回调函数。条件中设置的值将作为第二个参数传递给回调函数，以便在查询中使用。 +由于条件被评估为 ``true``，将调用回调函数。条件中设置的值将作为第二个参数传递给回调函数，以便在查询中使用。 -有时，你可能希望在条件评估为 false 时应用不同的语句。这可以通过提供第二个闭包实现： +有时你可能希望在条件评估为 false 时应用不同的语句。 +这可以通过提供第二个闭包来实现： .. literalinclude:: query_builder/106.php @@ -1126,7 +1168,7 @@ $builder->whenNot() .. versionadded:: 4.3.0 -此方法与 ``$builder->when()`` 的工作方式完全相同，区别在于仅在条件评估为 ``false`` 时运行回调函数，而 ``when()`` 在 ``true`` 时运行。 +这与 ``$builder->when()`` 的工作方式完全相同，只是它只会在条件评估为 ``false`` 时运行回调函数，而不是像 ``when()`` 那样在 ``true`` 时运行。 .. literalinclude:: query_builder/107.php @@ -1134,7 +1176,7 @@ $builder->whenNot() 方法链 *************** -方法链允许你通过连接多个方法来简化语法。考虑以下示例： +方法链允许通过连接多个方法来简化语法。考虑此示例： .. literalinclude:: query_builder/097.php @@ -1150,9 +1192,10 @@ ResetQuery $builder->resetQuery() ---------------------- -重置查询构建器允许你在不首先使用 ``$builder->get()`` 或 ``$builder->insert()`` 等方法执行查询的情况下重新开始查询。 +重置查询构建器允许在不先使用 ``$builder->get()`` 或 ``$builder->insert()`` 等方法执行查询的情况下重新开始。 -这在以下情况下非常有用：你使用查询构建器生成 SQL（例如 ``$builder->getCompiledSelect()``），但随后选择运行查询： +这在以下情况下很有用：使用查询构建器生成 SQL +（例如，``$builder->getCompiledSelect()``），但之后选择运行查询： .. literalinclude:: query_builder/098.php @@ -1166,17 +1209,18 @@ $builder->resetQuery() .. php:method:: db() - :returns: 当前使用的数据库连接 + :returns: 正在使用的数据库连接 :rtype: ``ConnectionInterface`` - 从 ``$db`` 返回当前数据库连接。用于访问不直接对查询构建器可用的 ``ConnectionInterface`` 方法，如 ``insertID()`` 或 ``errors()``。 + 从 ``$db`` 返回当前数据库连接。用于访问查询构建器无法直接使用的 + ``ConnectionInterface`` 方法，如 ``insertID()`` 或 ``errors()``。 .. php:method:: resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 重置当前查询构建器状态。在希望构建可在某些条件下取消的查询时非常有用。 + 重置当前查询构建器状态。当你想构建一个在某些条件下可以取消的查询时很有用。 .. php:method:: countAllResults([$reset = true]) @@ -1184,7 +1228,7 @@ $builder->resetQuery() :returns: 查询结果中的行数 :rtype: int - 生成特定于平台的查询字符串，统计查询构建器查询返回的所有记录。 + 生成特定于平台的查询字符串，用于计算查询构建器查询返回的所有记录数。 .. php:method:: countAll([$reset = true]) @@ -1192,13 +1236,13 @@ $builder->resetQuery() :returns: 查询结果中的行数 :rtype: int - 生成特定于平台的查询字符串，统计特定表中的所有记录。 + 生成特定于平台的查询字符串，用于计算特定表中的所有记录数。 .. php:method:: get([$limit = null[, $offset = null[, $reset = true]]]]) :param int $limit: LIMIT 子句 :param int $offset: OFFSET 子句 - :param bool $reset: 是否清除查询构建器的值？ + :param bool $reset: 是否要清除查询构建器的值？ :returns: ``\CodeIgniter\Database\ResultInterface`` 实例（方法链） :rtype: ``\CodeIgniter\Database\ResultInterface`` @@ -1209,11 +1253,11 @@ $builder->resetQuery() :param string $where: WHERE 子句 :param int $limit: LIMIT 子句 :param int $offset: OFFSET 子句 - :param bool $reset: 是否清除查询构建器的值？ + :param bool $reset: 是否要清除查询构建器的值？ :returns: ``\CodeIgniter\Database\ResultInterface`` 实例（方法链） :rtype: ``\CodeIgniter\Database\ResultInterface`` - 与 ``get()`` 相同，但允许直接添加 WHERE 子句。 + 与 ``get()`` 相同，但还允许直接添加 WHERE 子句。 .. php:method:: select([$select = '*'[, $escape = null]]) @@ -1226,7 +1270,7 @@ $builder->resetQuery() .. php:method:: selectAvg([$select = ''[, $alias = '']]) - :param string $select: 计算平均值的字段 + :param string $select: 要计算平均值的字段 :param string $alias: 结果值名称的别名 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` @@ -1235,7 +1279,7 @@ $builder->resetQuery() .. php:method:: selectMax([$select = ''[, $alias = '']]) - :param string $select: 计算最大值的字段 + :param string $select: 要计算最大值的字段 :param string $alias: 结果值名称的别名 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` @@ -1244,7 +1288,7 @@ $builder->resetQuery() .. php:method:: selectMin([$select = ''[, $alias = '']]) - :param string $select: 计算最小值的字段 + :param string $select: 要计算最小值的字段 :param string $alias: 结果值名称的别名 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` @@ -1253,7 +1297,7 @@ $builder->resetQuery() .. php:method:: selectSum([$select = ''[, $alias = '']]) - :param string $select: 计算总和的字段 + :param string $select: 要计算总和的字段 :param string $alias: 结果值名称的别名 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` @@ -1262,7 +1306,7 @@ $builder->resetQuery() .. php:method:: selectCount([$select = ''[, $alias = '']]) - :param string $select: 计算计数的字段 + :param string $select: 要计算平均值的字段 :param string $alias: 结果值名称的别名 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` @@ -1276,7 +1320,7 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向选择部分添加子查询。 + 向选择中添加子查询。 .. php:method:: distinct([$val = true]) @@ -1284,12 +1328,13 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 设置一个标志，告诉查询构建器向查询的 ``SELECT`` 部分添加 ``DISTINCT`` 子句。 + 设置一个标志，告诉查询构建器向查询的 ``SELECT`` 部分添加 + ``DISTINCT`` 子句。 .. php:method:: from($from[, $overwrite = false]) :param mixed $from: 表名；字符串或数组 - :param bool $overwrite: 是否覆盖第一个现有表？ + :param bool $overwrite: 是否移除现有的第一个表？ :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` @@ -1308,13 +1353,14 @@ $builder->resetQuery() .. versionadded:: 4.3.0 - :param BaseBuilder|RawSql $query: BaseBuilder 或 RawSql 实例 + :param BaseBuilder|RawSql $query: BaseBuilder 或 RawSql 的实例 :param string|null $alias: 查询的别名 - :param array|string|null $columns: 查询中的列数组或逗号分隔的字符串 + :param array|string|null $columns: 查询中字段的数组或逗号分隔的字符串 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 设置查询作为 ``insertBatch()``、``updateBatch()``、``upsertBatch()`` 的数据源。如果 ``$columns`` 为 null，将运行查询以生成列名。 + 将查询设置为 ``insertBatch()``、``updateBatch()``、``upsertBatch()`` 的数据源。 + 如果 ``$columns`` 为 null，则将运行查询以生成字段名。 .. php:method:: join($table, $cond[, $type = ''[, $escape = null]]) @@ -1325,7 +1371,8 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向查询添加 ``JOIN`` 子句。自 v4.2.0 起，可以使用 ``RawSql`` 作为 JOIN ON 条件。另请参阅 :ref:`query-builder-join`。 + 向查询添加 ``JOIN`` 子句。从 v4.2.0 开始，``RawSql`` 可以用作 + JOIN ON 条件。另请参见 :ref:`query-builder-join`。 .. php:method:: where($key[, $value = null[, $escape = null]]) @@ -1335,7 +1382,7 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 生成查询的 ``WHERE`` 部分。多个调用之间用 ``AND`` 分隔。 + 生成查询的 ``WHERE`` 部分。用 ``AND`` 分隔多个调用。 .. php:method:: orWhere($key[, $value = null[, $escape = null]]) @@ -1345,7 +1392,7 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 生成查询的 ``WHERE`` 部分。多个调用之间用 ``OR`` 分隔。 + 生成查询的 ``WHERE`` 部分。用 ``OR`` 分隔多个调用。 .. php:method:: orWhereIn([$key = null[, $values = null[, $escape = null]]]) @@ -1355,7 +1402,7 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 生成 ``WHERE field IN('item', 'item')`` SQL 查询，并在适当时用 ``OR`` 连接。 + 生成 ``WHERE`` 字段 ``IN('item', 'item')`` SQL 查询，在适当时用 ``OR`` 连接。 .. php:method:: orWhereNotIn([$key = null[, $values = null[, $escape = null]]]) @@ -1365,7 +1412,7 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 生成 ``WHERE field NOT IN('item', 'item')`` SQL 查询，并在适当时用 ``OR`` 连接。 + 生成 ``WHERE`` 字段 ``NOT IN('item', 'item')`` SQL 查询，在适当时用 ``OR`` 连接。 .. php:method:: whereIn([$key = null[, $values = null[, $escape = null]]]) @@ -1375,7 +1422,7 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 生成 ``WHERE field IN('item', 'item')`` SQL 查询，并在适当时用 ``AND`` 连接。 + 生成 ``WHERE`` 字段 ``IN('item', 'item')`` SQL 查询，在适当时用 ``AND`` 连接。 .. php:method:: whereNotIn([$key = null[, $values = null[, $escape = null]]]) @@ -1385,35 +1432,35 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 生成 ``WHERE field NOT IN('item', 'item')`` SQL 查询，并在适当时用 ``AND`` 连接。 + 生成 ``WHERE`` 字段 ``NOT IN('item', 'item')`` SQL 查询，在适当时用 ``AND`` 连接。 .. php:method:: groupStart() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 开始一个组表达式，使用 ``AND`` 连接内部条件。 + 开始一个组表达式，对其内部的条件使用 ``AND``。 .. php:method:: orGroupStart() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 开始一个组表达式，使用 ``OR`` 连接内部条件。 + 开始一个组表达式，对其内部的条件使用 ``OR``。 .. php:method:: notGroupStart() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 开始一个组表达式，使用 ``AND NOT`` 连接内部条件。 + 开始一个组表达式，对其内部的条件使用 ``AND NOT``。 .. php:method:: orNotGroupStart() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 开始一个组表达式，使用 ``OR NOT`` 连接内部条件。 + 开始一个组表达式，对其内部的条件使用 ``OR NOT``。 .. php:method:: groupEnd() @@ -1428,11 +1475,11 @@ $builder->resetQuery() :param string $match: 要匹配的文本部分 :param string $side: 在表达式的哪一侧放置 '%' 通配符 :param bool $escape: 是否转义值和标识符 - :param bool $insensitiveSearch: 是否强制不区分大小写的搜索 + :param bool $insensitiveSearch: 是否强制执行不区分大小写的搜索 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向查询添加 ``LIKE`` 子句，多个调用之间用 ``AND`` 分隔。 + 向查询添加 ``LIKE`` 子句，用 ``AND`` 分隔多个调用。 .. php:method:: orLike($field[, $match = ''[, $side = 'both'[, $escape = null[, $insensitiveSearch = false]]]]) @@ -1440,11 +1487,11 @@ $builder->resetQuery() :param string $match: 要匹配的文本部分 :param string $side: 在表达式的哪一侧放置 '%' 通配符 :param bool $escape: 是否转义值和标识符 - :param bool $insensitiveSearch: 是否强制不区分大小写的搜索 + :param bool $insensitiveSearch: 是否强制执行不区分大小写的搜索 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向查询添加 ``LIKE`` 子句，多个调用之间用 ``OR`` 分隔。 + 向查询添加 ``LIKE`` 子句，用 ``OR`` 分隔多个调用。 .. php:method:: notLike($field[, $match = ''[, $side = 'both'[, $escape = null[, $insensitiveSearch = false]]]]) @@ -1452,11 +1499,11 @@ $builder->resetQuery() :param string $match: 要匹配的文本部分 :param string $side: 在表达式的哪一侧放置 '%' 通配符 :param bool $escape: 是否转义值和标识符 - :param bool $insensitiveSearch: 是否强制不区分大小写的搜索 + :param bool $insensitiveSearch: 是否强制执行不区分大小写的搜索 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向查询添加 ``NOT LIKE`` 子句，多个调用之间用 ``AND`` 分隔。 + 向查询添加 ``NOT LIKE`` 子句，用 ``AND`` 分隔多个调用。 .. php:method:: orNotLike($field[, $match = ''[, $side = 'both'[, $escape = null[, $insensitiveSearch = false]]]]) @@ -1464,30 +1511,31 @@ $builder->resetQuery() :param string $match: 要匹配的文本部分 :param string $side: 在表达式的哪一侧放置 '%' 通配符 :param bool $escape: 是否转义值和标识符 + :param bool $insensitiveSearch: 是否强制执行不区分大小写的搜索 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向查询添加 ``NOT LIKE`` 子句，多个调用之间用 ``OR`` 分隔。 + 向查询添加 ``NOT LIKE`` 子句，用 ``OR`` 分隔多个调用。 .. php:method:: having($key[, $value = null[, $escape = null]]) :param mixed $key: 标识符（字符串）或字段/值对的关联数组 - :param string $value: 如果 $key 是标识符，则查找的值 + :param string $value: 如果 $key 是标识符，则为要查找的值 :param string $escape: 是否转义值和标识符 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向查询添加 ``HAVING`` 子句，多个调用之间用 ``AND`` 分隔。 + 向查询添加 ``HAVING`` 子句，用 ``AND`` 分隔多个调用。 .. php:method:: orHaving($key[, $value = null[, $escape = null]]) :param mixed $key: 标识符（字符串）或字段/值对的关联数组 - :param string $value: 如果 $key 是标识符，则查找的值 + :param string $value: 如果 $key 是标识符，则为要查找的值 :param string $escape: 是否转义值和标识符 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向查询添加 ``HAVING`` 子句，多个调用之间用 ``OR`` 分隔。 + 向查询添加 ``HAVING`` 子句，用 ``OR`` 分隔多个调用。 .. php:method:: orHavingIn([$key = null[, $values = null[, $escape = null]]]) @@ -1497,7 +1545,7 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 生成 ``HAVING field IN('item', 'item')`` SQL 查询，并在适当时用 ``OR`` 连接。 + 生成 ``HAVING`` 字段 IN('item', 'item') SQL 查询，在适当时用 ``OR`` 连接。 .. php:method:: orHavingNotIn([$key = null[, $values = null[, $escape = null]]]) @@ -1507,7 +1555,7 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 生成 ``HAVING field NOT IN('item', 'item')`` SQL 查询，并在适当时用 ``OR`` 连接。 + 生成 ``HAVING`` 字段 ``NOT IN('item', 'item')`` SQL 查询，在适当时用 ``OR`` 连接。 .. php:method:: havingIn([$key = null[, $values = null[, $escape = null]]]) @@ -1517,18 +1565,18 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 生成 ``HAVING field IN('item', 'item')`` SQL 查询，并在适当时用 ``AND`` 连接。 + 生成 ``HAVING`` 字段 ``IN('item', 'item')`` SQL 查询，在适当时用 ``AND`` 连接。 .. php:method:: havingNotIn([$key = null[, $values = null[, $escape = null]]]) :param string $key: 要检查的字段名 :param array|BaseBulder|Closure $values: 目标值数组，或用于子查询的匿名函数 :param bool $escape: 是否转义值和标识符 - :param bool $insensitiveSearch: 是否强制不区分大小写的搜索 + :param bool $insensitiveSearch: 是否强制执行不区分大小写的搜索 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 生成 ``HAVING field NOT IN('item', 'item')`` SQL 查询，并在适当时用 ``AND`` 连接。 + 生成 ``HAVING`` 字段 ``NOT IN('item', 'item')`` SQL 查询，在适当时用 ``AND`` 连接。 .. php:method:: havingLike($field[, $match = ''[, $side = 'both'[, $escape = null[, $insensitiveSearch = false]]]]) @@ -1536,11 +1584,11 @@ $builder->resetQuery() :param string $match: 要匹配的文本部分 :param string $side: 在表达式的哪一侧放置 '%' 通配符 :param bool $escape: 是否转义值和标识符 - :param bool $insensitiveSearch: 是否强制不区分大小写的搜索 + :param bool $insensitiveSearch: 是否强制执行不区分大小写的搜索 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向查询的 ``HAVING`` 部分添加 ``LIKE`` 子句，多个调用之间用 ``AND`` 分隔。 + 向查询的 ``HAVING`` 部分添加 ``LIKE`` 子句，用 ``AND`` 分隔多个调用。 .. php:method:: orHavingLike($field[, $match = ''[, $side = 'both'[, $escape = null[, $insensitiveSearch = false]]]]) @@ -1548,11 +1596,11 @@ $builder->resetQuery() :param string $match: 要匹配的文本部分 :param string $side: 在表达式的哪一侧放置 '%' 通配符 :param bool $escape: 是否转义值和标识符 - :param bool $insensitiveSearch: 是否强制不区分大小写的搜索 + :param bool $insensitiveSearch: 是否强制执行不区分大小写的搜索 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向查询的 ``HAVING`` 部分添加 ``LIKE`` 子句，多个调用之间用 ``OR`` 分隔。 + 向查询的 ``HAVING`` 部分添加 ``LIKE`` 子句，用 ``OR`` 分隔多个调用。 .. php:method:: notHavingLike($field[, $match = ''[, $side = 'both'[, $escape = null[, $insensitiveSearch = false]]]]) @@ -1560,11 +1608,11 @@ $builder->resetQuery() :param string $match: 要匹配的文本部分 :param string $side: 在表达式的哪一侧放置 '%' 通配符 :param bool $escape: 是否转义值和标识符 - :param bool $insensitiveSearch: 是否强制不区分大小写的搜索 + :param bool $insensitiveSearch: 是否强制执行不区分大小写的搜索 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向查询的 ``HAVING`` 部分添加 ``NOT LIKE`` 子句，多个调用之间用 ``AND`` 分隔。 + 向查询的 ``HAVING`` 部分添加 ``NOT LIKE`` 子句，用 ``AND`` 分隔多个调用。 .. php:method:: orNotHavingLike($field[, $match = ''[, $side = 'both'[, $escape = null[, $insensitiveSearch = false]]]]) @@ -1575,35 +1623,35 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 向查询的 ``HAVING`` 部分添加 ``NOT LIKE`` 子句，多个调用之间用 ``OR`` 分隔。 + 向查询的 ``HAVING`` 部分添加 ``NOT LIKE`` 子句，用 ``OR`` 分隔多个调用。 .. php:method:: havingGroupStart() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 开始 ``HAVING`` 子句的组表达式，使用 ``AND`` 连接内部条件。 + 开始 ``HAVING`` 子句的组表达式，对其内部的条件使用 ``AND``。 .. php:method:: orHavingGroupStart() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 开始 ``HAVING`` 子句的组表达式，使用 ``OR`` 连接内部条件。 + 开始 ``HAVING`` 子句的组表达式，对其内部的条件使用 ``OR``。 .. php:method:: notHavingGroupStart() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 开始 ``HAVING`` 子句的组表达式，使用 ``AND NOT`` 连接内部条件。 + 开始 ``HAVING`` 子句的组表达式，对其内部的条件使用 ``AND NOT``。 .. php:method:: orNotHavingGroupStart() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 开始 ``HAVING`` 子句的组表达式，使用 ``OR NOT`` 连接内部条件。 + 开始 ``HAVING`` 子句的组表达式，对其内部的条件使用 ``OR NOT``。 .. php:method:: havingGroupEnd() @@ -1614,7 +1662,7 @@ $builder->resetQuery() .. php:method:: groupBy($by[, $escape = null]) - :param mixed $by: 分组的字段；字符串或数组 + :param mixed $by: 要分组的字段；字符串或数组 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` @@ -1622,8 +1670,8 @@ $builder->resetQuery() .. php:method:: orderBy($orderby[, $direction = ''[, $escape = null]]) - :param string $orderby: 排序字段 - :param string $direction: 排序方向 - ASC、DESC 或 random + :param string $orderby: 要排序的字段 + :param string $direction: 请求的排序顺序 - ASC、DESC 或 random :param bool $escape: 是否转义值和标识符 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` @@ -1632,8 +1680,8 @@ $builder->resetQuery() .. php:method:: limit($value[, $offset = 0]) - :param int $value: 限制结果的行数 - :param int $offset: 跳过的行数 + :param int $value: 要限制结果的行数 + :param int $offset: 要跳过的行数 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` @@ -1641,7 +1689,7 @@ $builder->resetQuery() .. php:method:: offset($offset) - :param int $offset: 跳过的行数 + :param int $offset: 要跳过的行数 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` @@ -1671,7 +1719,7 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 添加稍后传递给 ``insert()``、``update()`` 或 ``replace()`` 的字段/值对。 + 添加字段/值对，稍后传递给 ``insert()``、``update()`` 或 ``replace()``。 .. php:method:: insert([$set = null[, $escape = null]]) @@ -1686,18 +1734,20 @@ $builder->resetQuery() :param array $set: 要插入的数据 :param bool $escape: 是否转义值 - :param int $batch_size: 单次插入的行数 - :returns: 插入的行数，或在无数据执行插入操作时返回 ``false`` + :param int $batch_size: 一次插入的行数 + :returns: 插入的行数，如果没有数据执行插入操作则返回 ``false`` :rtype: int|false 编译并执行批量 ``INSERT`` 语句。 - .. note:: 当提供的行数超过 ``$batch_size`` 时，将执行多个 ``INSERT`` 查询，每个查询尝试插入最多 ``$batch_size`` 行。 + .. note:: 当提供超过 ``$batch_size`` 行时，将执行多个 + ``INSERT`` 查询，每个查询尝试插入 + 最多 ``$batch_size`` 行。 .. php:method:: setInsertBatch($key[, $value = ''[, $escape = null]]) .. deprecated:: 4.3.0 - 请改用 :php:meth:`CodeIgniter\\Database\\BaseBuilder::setData()`。 + 使用 :php:meth:`CodeIgniter\\Database\\BaseBuilder::setData()` 代替。 :param mixed $key: 字段名或字段/值对的数组 :param string $value: 字段值，如果 $key 是单个字段 @@ -1705,9 +1755,9 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 添加稍后通过 ``insertBatch()`` 插入到表中的字段/值对。 + 添加字段/值对，稍后通过 ``insertBatch()`` 插入到表中。 - .. important:: 此方法已弃用，将在未来版本中移除。 + .. important:: 此方法已弃用。将在未来版本中删除。 .. php:method:: upsert([$set = null[, $escape = null]]) @@ -1720,17 +1770,21 @@ $builder->resetQuery() .. php:method:: upsertBatch([$set = null[, $escape = null[, $batch_size = 100]]]) - :param array $set: 要更新插入的数据 + :param array $set: 要 upsert 的数据 :param bool $escape: 是否转义值 - :param int $batch_size: 单次更新插入的行数 - :returns: 更新插入的行数，或在失败时返回 ``false`` + :param int $batch_size: 一次 upsert 的行数 + :returns: upsert 的行数，失败时返回 ``false`` :rtype: int|false 编译并执行批量 ``UPSERT`` 语句。 - .. note:: MySQL 使用 ``ON DUPLICATE KEY UPDATE``，每行的受影响行数为 1（如果作为新行插入）、2（如果更新现有行）和 0（如果现有行设置为当前值）。 + .. note:: MySQL 使用 ``ON DUPLICATE KEY UPDATE``，每行的受影响行数值 + 如果行作为新行插入则为 1，如果现有行被更新则为 2， + 如果现有行被设置为其当前值则为 0。 - .. note:: 当提供的行数超过 ``$batch_size`` 时，将执行多个 ``UPSERT`` 查询，每个查询尝试更新插入最多 ``$batch_size`` 行。 + .. note:: 当提供超过 ``$batch_size`` 行时，将执行多个 + ``UPSERT`` 查询，每个查询尝试 upsert + 最多 ``$batch_size`` 行。 .. php:method:: update([$set = null[, $where = null[, $limit = null]]]) @@ -1745,28 +1799,32 @@ $builder->resetQuery() .. php:method:: updateBatch([$set = null[, $constraints = null[, $batchSize = 100]]]) :param array|object|null $set: 字段名，或字段/值对的关联数组 - :param array|RawSql|string|null $constraints: 用作更新键的字段或字段集 - :param int $batchSize: 单次查询中分组条件的数量 - :returns: 更新的行数，或在失败时返回 ``false`` + :param array|RawSql|string|null $constraints: 用作更新键的字段或字段 + :param int $batchSize: 在单个查询中分组的条件数 + :returns: 更新的行数，失败时返回 ``false`` :rtype: int|false - .. note:: 自 v4.3.0 起，参数 ``$set`` 和 ``$constraints`` 的类型已更改。 + .. note:: 从 v4.3.0 开始，参数 ``$set`` 和 ``$constraints`` 的类型已更改。 - 编译并执行批量 ``UPDATE`` 语句。``$constraints`` 参数接受逗号分隔的字段字符串、数组、关联数组或 ``RawSql``。 + 编译并执行批量 ``UPDATE`` 语句。 + ``$constraints`` 参数接受逗号分隔的字段字符串、数组、关联数组或 ``RawSql``。 - .. note:: 当提供的字段/值对超过 ``$batchSize`` 时，将执行多个查询，每个查询处理最多 ``$batchSize`` 字段/值对。如果我们将 ``$batchSize`` 设置为 0，则所有字段/值对将在单个查询中执行。 + .. note:: 当提供超过 ``$batchSize`` 个字段/值对时， + 将执行多个查询，每个查询处理最多 ``$batchSize`` + 个字段/值对。如果我们将 ``$batchSize`` 设置为 0， + 则所有字段/值对将在一个查询中执行。 .. php:method:: updateFields($set, [$addToDefault = false, [$ignore = null]]) .. versionadded:: 4.3.0 :param mixed $set: 行或行数组，行是数组或对象 - :param bool $addToDefault: 添加数据集中不存在的额外列 - :param bool $ignore: 要忽略的列数组 + :param bool $addToDefault: 添加比数据集中更多的字段 + :param bool $ignore: 从 $set 中忽略的字段数组 :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 与 ``updateBatch()`` 和 ``upsertBatch()`` 方法一起使用。定义将更新的字段。 + 与 ``updateBatch()`` 和 ``upsertBatch()`` 方法一起使用。这定义了将被更新的字段。 .. php:method:: onConstraint($set) @@ -1776,7 +1834,7 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 与 ``updateBatch()`` 和 ``upsertBatch()`` 方法一起使用。接受逗号分隔的字段字符串、数组、关联数组或 RawSql。 + 与 ``updateBatch()`` 和 ``upsertBatch()`` 方法一起使用。这接受逗号分隔的字段字符串、数组、关联数组或 RawSql。 .. php:method:: setData($set, [$escape = null, [$alias = '']]) @@ -1788,12 +1846,12 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 用于 ``*Batch()`` 方法设置插入、更新、更新插入的数据。 + 用于 ``*Batch()`` 方法设置插入、更新、upsert 的数据。 .. php:method:: setUpdateBatch($key[, $value = ''[, $escape = null]]) .. deprecated:: 4.3.0 - 请改用 :php:meth:`CodeIgniter\\Database\\BaseBuilder::setData()`。 + 使用 :php:meth:`CodeIgniter\\Database\\BaseBuilder::setData()` 代替。 :param mixed $key: 字段名或字段/值对的数组 :param string $value: 字段值，如果 $key 是单个字段 @@ -1801,9 +1859,9 @@ $builder->resetQuery() :returns: ``BaseBuilder`` 实例（方法链） :rtype: ``BaseBuilder`` - 添加稍后通过 ``updateBatch()`` 更新表中的字段/值对。 + 添加字段/值对，稍后通过 ``updateBatch()`` 更新表中的数据。 - .. important:: 此方法已弃用，将在未来版本中移除。 + .. important:: 此方法已弃用。将在未来版本中删除。 .. php:method:: replace([$set = null]) @@ -1817,7 +1875,7 @@ $builder->resetQuery() :param string $where: WHERE 子句 :param int $limit: LIMIT 子句 - :param bool $reset_data: 是否重置查询的 "write" 子句 + :param bool $reset_data: 是否重置查询的"写入"子句 :returns: ``BaseBuilder`` 实例（方法链）或失败时返回 ``false`` :rtype: ``BaseBuilder|false`` @@ -1826,26 +1884,30 @@ $builder->resetQuery() .. php:method:: deleteBatch([$set = null[, $constraints = null[, $batchSize = 100]]]) :param array|object|null $set: 字段名，或字段/值对的关联数组 - :param array|RawSql|string|null $constraints: 用作删除键的字段或字段集 - :param int $batchSize: 单次查询中分组条件的数量 - :returns: 删除的行数，或在失败时返回 ``false`` + :param array|RawSql|string|null $constraints: 用作删除键的字段或字段 + :param int $batchSize: 在单个查询中分组的条件数 + :returns: 删除的行数，失败时返回 ``false`` :rtype: int|false 编译并执行批量 ``DELETE`` 查询。 .. php:method:: increment($column[, $value = 1]) - :param string $column: 要递增的列名 - :param int $value: 递增的量 + :param string $column: 要递增的字段名 + :param int $value: 字段中递增的数量 - 将字段的值递增指定量。如果字段不是数字字段（如 ``VARCHAR``），可能会被替换为 ``$value``。 + 将字段的值按指定数量递增。如果字段 + 不是数字字段，如 ``VARCHAR``，它可能会被替换 + 为 ``$value``。 .. php:method:: decrement($column[, $value = 1]) - :param string $column: 要递减的列名 - :param int $value: 递减的量 + :param string $column: 要递减的字段名 + :param int $value: 递减的数量 - 将字段的值递减指定量。如果字段不是数字字段（如 ``VARCHAR``），可能会被替换为 ``$value``。 + 将字段的值按指定数量递减。如果字段 + 不是数字字段，如 ``VARCHAR``，它可能会被替换 + 为 ``$value``。 .. php:method:: truncate() @@ -1854,14 +1916,15 @@ $builder->resetQuery() 在表上执行 ``TRUNCATE`` 语句。 - .. note:: 如果使用的数据库平台不支持 ``TRUNCATE``，将改用 ``DELETE`` 语句。 + .. note:: 如果使用的数据库平台不支持 ``TRUNCATE``， + 将使用 ``DELETE`` 语句代替。 .. php:method:: emptyTable() :returns: 成功时返回 ``true``，失败时返回 ``false`` :rtype: bool - 通过 ``DELETE`` 语句删除表中的所有记录。 + 通过 ``DELETE`` 语句从表中删除所有记录。 .. php:method:: getCompiledSelect([$reset = true]) @@ -1869,7 +1932,7 @@ $builder->resetQuery() :returns: 编译后的 SQL 语句字符串 :rtype: string - 编译 ``SELECT`` 语句并以字符串形式返回。 + 编译 ``SELECT`` 语句并将其作为字符串返回。 .. php:method:: getCompiledInsert([$reset = true]) @@ -1877,7 +1940,7 @@ $builder->resetQuery() :returns: 编译后的 SQL 语句字符串 :rtype: string - 编译 ``INSERT`` 语句并以字符串形式返回。 + 编译 ``INSERT`` 语句并将其作为字符串返回。 .. php:method:: getCompiledUpdate([$reset = true]) @@ -1885,7 +1948,7 @@ $builder->resetQuery() :returns: 编译后的 SQL 语句字符串 :rtype: string - 编译 ``UPDATE`` 语句并以字符串形式返回。 + 编译 ``UPDATE`` 语句并将其作为字符串返回。 .. php:method:: getCompiledDelete([$reset = true]) @@ -1893,4 +1956,4 @@ $builder->resetQuery() :returns: 编译后的 SQL 语句字符串 :rtype: string - 编译 ``DELETE`` 语句并以字符串形式返回。 + 编译 ``DELETE`` 语句并将其作为字符串返回。 diff --git a/source/database/results.rst b/source/database/results.rst index a265c660d..3fce83593 100755 --- a/source/database/results.rst +++ b/source/database/results.rst @@ -2,7 +2,7 @@ 生成查询结果 ######################## -有几种生成查询结果的方法: +生成查询结果的方式有多种： .. contents:: :local: @@ -17,40 +17,39 @@ getResult() =========== -此方法将查询结果作为 **对象** 的数组返回,如果失败则返回 **空数组**。 +此方法将查询结果以 **对象数组** 形式返回，失败时则返回 **空数组**。 -获取 stdClass 的数组 +获取 stdClass 数组 ---------------------------- -通常你会在 foreach 循环中使用它,如下所示: +通常你会在 foreach 循环中使用它，如下所示： .. literalinclude:: results/001.php -上面的方法是 :php:meth:`CodeIgniter\\Database\\BaseResult::getResultObject()` 的别名。 +上述方法是 :php:meth:`CodeIgniter\\Database\\BaseResult::getResultObject()` 的别名。 获取数组的数组 ------------------------- -如果希望以数组的数组形式获取结果,可以在第一个参数中传递 'array' 字符串: +如果希望结果以数组的数组形式返回，可以传入字符串 'array'： .. literalinclude:: results/002.php -上面的用法是 `getResultArray()`_ 的别名。 +上述用法是 `getResultArray()`_ 的别名。 -获取自定义对象的数组 ---------------------------------- +获取自定义对象数组 +-------------------- -你也可以将表示要为每个结果对象实例化的类的字符串传递给 ``getResult()`` +也可以向 ``getResult()`` 传递一个字符串，表示为每个结果对象实例化的类名 .. literalinclude:: results/003.php -上面的方法是 `getCustomResultObject()`_ 的别名。 +上述方法是 `getCustomResultObject()`_ 的别名。 getResultArray() ================ -此方法将查询结果作为纯数组返回,如果没有生成结果,则返回空数组。 -通常你会在 foreach 循环中使用它,如下所示: +此方法将查询结果作为纯数组返回，如果没有产生结果则返回空数组。通常你会在 foreach 循环中使用它，如下所示： .. literalinclude:: results/004.php @@ -61,66 +60,59 @@ getResultArray() getRow() ======== -此方法返回单个结果集。如果查询有多个行,则只返回第一行。 -结果作为 **对象** 返回。这里有个使用示例: +此方法返回单个结果集。如果查询有多行，它只返回第一行。结果以**对象**形式返回。用法示例： .. literalinclude:: results/005.php -如果要返回特定的行,可以在第一个参数中提交行号作为数字: +如果需要返回特定行，可以在第一个参数中提交行号（数字）： .. literalinclude:: results/006.php -你还可以添加第二个字符串参数,该参数是要使用的类的名称: +还可以添加第二个字符串参数，指定用于实例化行的类名： .. literalinclude:: results/007.php getRowArray() ============= -与上面的 ``getRow()`` 方法相同,只是它返回数组。 -例如: +与上面的 ``row()`` 方法相同，只是它返回数组。示例： .. literalinclude:: results/008.php -如果要返回特定的行,可以在第一个参数中提交行号作为数字: +如果需要返回特定行，可以在第一个参数中提交行号（数字）： .. literalinclude:: results/009.php -此外,你可以通过这些变体在结果中向前/向后/第一行/最后一行移动: +此外，可以使用以下变体在结果中前进/后退/定位到第一行/最后一行： | ``$row = $query->getFirstRow()`` | ``$row = $query->getLastRow()`` | ``$row = $query->getNextRow()`` | ``$row = $query->getPreviousRow()`` -默认情况下,除非在参数中放入 "array" 字样,否则它们返回对象: +默认情况下它们返回对象，除非在参数中放入 "array" 单词： | ``$row = $query->getFirstRow('array')`` | ``$row = $query->getLastRow('array')`` | ``$row = $query->getNextRow('array')`` | ``$row = $query->getPreviousRow('array')`` -.. note:: 上面的所有方法都会将整个结果集加载到内存中(预取)。对于处理大型结果集,请使用 ``getUnbufferedRow()``。 +.. note:: 上述所有方法都会将整个结果加载到内存中（预取）。处理大型结果集时使用 ``getUnbufferedRow()``。 getUnbufferedRow() ================== -此方法返回单个结果集,而不像 ``getRow()`` 那样在内存中预取全部结果。 -如果查询有多个行,它会返回当前行并将内部数据指针向前移动。 +此方法返回单个结果集，不像 ``row()`` 那样将整个结果预取到内存中。如果查询有多行，它会返回当前行并将内部数据指针向前移动。 .. literalinclude:: results/010.php -对于使用 MySQLi,你可以将 MySQLi 的结果模式设置为 ``MYSQLI_USE_RESULT``,以节省最大内存。 -使用这种方式通常不推荐,但在某些情况下可能是有益的,例如将大型查询写入 csv。 -如果更改结果模式,请注意与之相关的权衡。 +对于 MySQLi，可以将 MySQLi 的结果模式设置为 ``MYSQLI_USE_RESULT`` 以最大化内存节省。一般不推荐使用此设置，但在某些情况下（如将大型查询写入 CSV）可能有益。更改结果模式时请注意相关的权衡。 .. literalinclude:: results/011.php -.. note:: 在使用 ``MYSQLI_USE_RESULT`` 时,在所有记录被提取或进行 ``freeResult()`` 调用之前, - 对同一连接的后续所有调用都将导致错误。``getNumRows()`` 方法将仅基于数据指针的当前位置返回行数。 - MyISAM 表将保持锁定,直到提取了所有记录或进行了 ``freeResult()`` 调用。 +.. note:: 使用 ``MYSQLI_USE_RESULT`` 时，在获取所有记录或调用 ``freeResult()`` 之前，对同一连接的所有后续调用都会导致错误。``getNumRows()`` 方法只会根据数据指针的当前位置返回行数。MyISAM 表将保持锁定状态，直到获取所有记录或调用 ``freeResult()``。 -你可以选择传递 'object'(默认)或 'array' 以指定返回值的类型: +可以选择性地传递 'object'（默认）或 'array' 来指定返回值的类型： .. literalinclude:: results/012.php @@ -128,38 +120,35 @@ getUnbufferedRow() 自定义结果对象 ********************* -你可以让结果作为 ``stdClass`` 或数组的自定义类的实例返回,正如 ``getResult()`` 和 ``getResultArray()`` 方法允许的那样。 -如果类还未加载到内存中,则会自动加载。该对象将具有从数据库设置为属性的所有返回值。 -如果这些已声明且非公共,则应提供 ``__set()`` 方法以允许设置它们。 +可以让结果返回为自定义类的实例，而不是 ``stdClass`` 或数组，就像 ``getResult()`` 和 ``getResultArray()`` 方法允许的那样。如果类尚未加载到内存中，自动加载器将尝试加载它。对象将把数据库返回的所有值设置为属性。如果这些属性已声明且是非公共的，则应提供 ``__set()`` 方法以允许设置它们。 -例子: +示例： .. literalinclude:: results/013.php -除了下面列出的两种方法外,以下方法也可以使用类名称将结果返回为:``getFirstRow()``、``getLastRow()``、 -``getNextRow()`` 和 ``getPreviousRow()``。 +除了下面列出的两个方法外，以下方法也可以接受类名以返回结果：``getFirstRow()``、``getLastRow()``、``getNextRow()`` 和 ``getPreviousRow()``。 getCustomResultObject() ======================= -将整个结果集作为请求类的实例数组返回。唯一的参数是要实例化的类的名称。 +将整个结果集返回为请求的类实例的数组。唯一的参数是要实例化的类名。 -例子: +示例： .. literalinclude:: results/014.php getCustomRowObject() ==================== -从查询结果中返回单行。第一个参数是结果的行号。第二个参数是要实例化的类名称。 +从查询结果中返回单行。第一个参数是结果的行号。第二个参数是要实例化的类名。 -例子: +示例： .. literalinclude:: results/015.php -你也可以以完全相同的方式使用 ``getRow()`` 方法。 +也可以以完全相同的方式使用 ``getRow()`` 方法。 -例子: +示例： .. literalinclude:: results/016.php @@ -170,49 +159,45 @@ getCustomRowObject() getFieldCount() =============== -查询返回的字段(列)数。请确保使用查询结果对象调用该方法: +查询返回的字段（列）数量。确保使用查询结果对象调用此方法： .. literalinclude:: results/017.php getFieldNames() =============== -以数组形式返回查询返回的字段(列)的名称。 -请确保使用查询结果对象调用该方法: +返回包含查询返回的字段（列）名称的数组。确保使用查询结果对象调用此方法： .. literalinclude:: results/018.php getNumRows() ============ -查询返回的记录数。请确保使用查询结果对象调用该方法: +查询返回的记录数。确保使用查询结果对象调用此方法： .. literalinclude:: results/019.php -.. note:: 因为 SQLite3 缺乏有效的返回记录数的方法, - CodeIgniter 将在内部提取和缓冲查询结果记录,并返回生成的记录数组的计数,这可能效率低下。 +.. note:: 由于 SQLite3 缺乏高效的返回记录计数的方法，CodeIgniter 会在内部获取并缓冲查询结果记录，然后返回结果记录数组的计数，这可能效率不高。 freeResult() ============ -它释放与结果相关的内存并删除结果资源 ID。通常 PHP 会在脚本执行结束时自动释放其内存。 -但是,如果在特定脚本中运行了大量查询,你可能希望在生成每个查询结果后释放结果,以减少内存消耗。 +释放与结果关联的内存并删除结果资源 ID。通常 PHP 会在脚本执行结束时自动释放内存。但是，如果在特定脚本中运行大量查询，可能希望在生成每个查询结果后释放结果，以减少内存消耗。 -例子: +示例： .. literalinclude:: results/020.php dataSeek() ========== -此方法将下一个要提取的结果集的内部指针设置为。它仅与 ``getUnbufferedRow()`` 结合使用时才有用。 +此方法设置下一个要获取的结果集的内部指针。它仅在与 ``getUnbufferedRow()`` 结合使用时有用。 -它接受一个正整数值,默认为 0 并在成功时返回 true,失败时返回 false。 +它接受一个正整数值（默认为 0），成功时返回 true，失败时返回 false。 .. literalinclude:: results/021.php -.. note:: 并非所有数据库驱动程序都支持此功能并会返回 false。 - 最明显的是 - 你将无法与 PDO 一起使用它。 +.. note:: 并非所有数据库驱动程序都支持此功能，不支持的驱动程序将返回 false。最明显的是，无法在 PDO 中使用此功能。 *************** 类参考 @@ -224,139 +209,139 @@ dataSeek() .. php:method:: getResult([$type = 'object']) - :param string $type: 请求结果的类型 - array、object 或类名 - :returns: 包含提取行的数组 + :param string $type: 请求的结果类型 - array、object 或类名 + :returns: 包含获取行的数组 :rtype: array ``getResultArray()``、``getResultObject()`` 和 ``getCustomResultObject()`` 方法的包装器。 - 用法:参见 `结果数组`_ 。 + 用法：参见 `结果数组`_。 .. php:method:: getResultArray() - :returns: 包含提取行的数组 + :returns: 包含获取行的数组 :rtype: array - 将查询结果作为行数组返回,其中每行本身是一个关联数组。 + 将查询结果返回为行的数组，其中每行本身是一个关联数组。 - 用法:参见 `结果数组`_ 。 + 用法：参见 `结果数组`_。 .. php:method:: getResultObject() - :returns: 包含提取行的数组 + :returns: 包含获取行的数组 :rtype: array - 将查询结果作为行数组返回,其中每行是一个 ``stdClass`` 类型的对象。 + 将查询结果返回为行的数组，其中每行是 ``stdClass`` 类型的对象。 - 用法:参见 `获取 stdClass 的数组`_ 。 + 用法：参见 `获取 stdClass 数组`_。 .. php:method:: getCustomResultObject($className) :param string $className: 结果集的类名 - :returns: 包含提取行的数组 + :returns: 包含获取行的数组 :rtype: array - 将查询结果作为行数组返回,其中每行是指定类的实例。 + 将查询结果返回为行的数组，其中每行是指定类的实例。 .. php:method:: getRow([$n = 0[, $type = 'object']]) - :param int $n: 要返回的查询结果集的索引 - :param string $type: 请求结果的类型 - array、object 或类名 - :returns: 请求的行或不存在则为 null + :param int $n: 要返回的查询结果集索引 + :param string $type: 请求的结果类型 - array、object 或类名 + :returns: 请求的行，如果不存在则为 null :rtype: mixed ``getRowArray()``、``getRowObject()`` 和 ``getCustomRowObject()`` 方法的包装器。 - 用法:参见 `结果集`_ 。 + 用法：参见 `结果集`_。 .. php:method:: getUnbufferedRow([$type = 'object']) - :param string $type: 请求结果的类型 - array、object 或类名 - :returns: 结果集的下一行或不存在则为 null + :param string $type: 请求的结果类型 - array、object 或类名 + :returns: 结果集中的下一行，如果不存在则为 null :rtype: mixed - 获取下一行结果并以请求的形式返回。 + 获取下一个结果集并以请求的形式返回。 - 用法:参见 `结果集`_ 。 + 用法：参见 `结果集`_。 .. php:method:: getRowArray([$n = 0]) - :param int $n: 要返回的查询结果集的索引 - :returns: 请求的行或不存在则为 null + :param int $n: 要返回的查询结果集索引 + :returns: 请求的行，如果不存在则为 null :rtype: array - 将请求的结果集作为关联数组返回。 + 将请求的结果集返回为关联数组。 - 用法:参见 `结果集`_ 。 + 用法：参见 `结果集`_。 .. php:method:: getRowObject([$n = 0]) - :param int $n: 要返回的查询结果集的索引 - :returns: 请求的行或不存在则为 null + :param int $n: 要返回的查询结果集索引 + :returns: 请求的行，如果不存在则为 null :rtype: stdClass - 将请求的结果集作为 ``stdClass`` 类型的对象返回。 + 将请求的结果集返回为 ``stdClass`` 类型的对象。 - 用法:参见 `结果集`_ 。 + 用法：参见 `结果集`_。 .. php:method:: getCustomRowObject($n, $type) - :param int $n: 要返回的结果集的索引 + :param int $n: 要返回的结果集索引 :param string $class_name: 结果集的类名 - :returns: 请求的行或不存在则为 null + :returns: 请求的行，如果不存在则为 null :rtype: $type - 将请求的结果集作为请求类的实例返回。 + 将请求的结果集返回为请求类的实例。 .. php:method:: dataSeek([$n = 0]) - :param int $n: 下一个要返回的结果集的索引 - :returns: 成功则为 true,失败则为 false + :param int $n: 下一个要返回的结果集索引 + :returns: 成功时为 true，失败时为 false :rtype: bool 将内部结果集指针移动到所需的偏移量。 - 用法:参见 `结果辅助方法`_。 + 用法：参见 `结果辅助方法`_。 .. php:method:: setRow($key[, $value = null]) - :param mixed $key: 列名称或键/值对的数组 - :param mixed $value: 如果 $key 是单个字段名,则分配给该列的值 + :param mixed $key: 列名或键/值对数组 + :param mixed $value: 分配给列的值，当 $key 是单个字段名时 :rtype: void - 为特定列赋值。 + 为特定列分配值。 .. php:method:: getNextRow([$type = 'object']) - :param string $type: 请求结果的类型 - array、object 或类名 - :returns: 结果集的下一行,不存在则为 null + :param string $type: 请求的结果类型 - array、object 或类名 + :returns: 结果集的下一行，如果不存在则为 null :rtype: mixed - 从结果集返回下一行。 + 返回结果集中的下一行。 .. php:method:: getPreviousRow([$type = 'object']) - :param string $type: 请求结果的类型 - array、object 或类名 - :returns: 结果集的上一行,不存在则为 null + :param string $type: 请求的结果类型 - array、object 或类名 + :returns: 结果集的上一行，如果不存在则为 null :rtype: mixed - 从结果集返回上一行。 + 返回结果集中的上一行。 .. php:method:: getFirstRow([$type = 'object']) - :param string $type: 请求结果的类型 - array、object 或类名 - :returns: 结果集的第一行,不存在则为 null + :param string $type: 请求的结果类型 - array、object 或类名 + :returns: 结果集的第一行，如果不存在则为 null :rtype: mixed - 从结果集返回第一行。 + 返回结果集中的第一行。 .. php:method:: getLastRow([$type = 'object']) - :param string $type: 请求结果的类型 - array、object 或类名 - :returns: 结果集的最后一行,不存在则为 null + :param string $type: 请求的结果类型 - array、object 或类名 + :returns: 结果集的最后一行，如果不存在则为 null :rtype: mixed - 从结果集返回最后一行。 + 返回结果集中的最后一行。 .. php:method:: getFieldCount() @@ -365,14 +350,14 @@ dataSeek() 返回结果集中的字段数。 - 用法:参见 `结果辅助方法`_。 + 用法：参见 `结果辅助方法`_。 .. php:method:: getFieldNames() - :returns: 列名称数组 + :returns: 列名数组 :rtype: array - 返回结果集中包含的字段名称数组。 + 返回包含结果集中字段名的数组。 .. php:method:: getFieldData() @@ -394,4 +379,4 @@ dataSeek() 释放结果集。 - 用法:参见 `结果辅助方法`_。 + 用法：参见 `结果辅助方法`_。 diff --git a/source/dbmgmt/db_commands.rst b/source/dbmgmt/db_commands.rst index dee49c352..b53121aad 100644 --- a/source/dbmgmt/db_commands.rst +++ b/source/dbmgmt/db_commands.rst @@ -18,13 +18,14 @@ CodeIgniter 提供了一些简单的数据库管理命令。 db:table --show --------------- -要直接从喜欢的终端列出数据库中的所有表,可以使用 ``db:table --show`` 命令: +要在喜欢的终端中直接列出数据库中的所有表， +可以使用 ``db:table --show`` 命令： .. code-block:: console php spark db:table --show -使用此命令时，假设数据库中已存在表。 +使用此命令时假定数据库中存在表。 否则，CodeIgniter 会提示数据库中没有表。 .. _db-command-specify-the-dbgroup: @@ -37,7 +38,7 @@ db:table --dbgroup .. versionadded:: 4.5.0 -你可以使用 ``--dbgroup`` 选项来指定使用的数据库组： +可以使用 ``--dbgroup`` 选项指定要使用的数据库组： .. code-block:: console @@ -49,23 +50,23 @@ db:table --dbgroup db:table -------- -当你有一个名为 ``my_table`` 的表时,你可以看到表的字段名和记录: +当有一个名为 ``my_table`` 的表时，可以查看表的字段名和记录： .. code-block:: console php spark db:table my_table -如果数据库中没有表 ``my_table``,CodeIgniter 会显示可用表列表以供选择。 +如果数据库中不存在 ``my_table`` 表，CodeIgniter 会显示可用表列表供选择。 -你也可以不使用表名使用以下命令: +也可以不使用表名而使用以下命令： .. code-block:: console php spark db:table -在这种情况下,将询问表名。 +在这种情况下，会要求输入表名。 -你还可以传递一些选项: +还可以传递一些选项： .. code-block:: console @@ -73,9 +74,9 @@ db:table 选项 ``--limit-rows 50`` 将行数限制为 50 行。 -选项 ``--limit-field-value 20`` 将字段值的长度限制为 20 个字符,以防止表输出在终端中混淆。 +选项 ``--limit-field-value 20`` 将字段值的长度限制为 20 个字符，以防止终端中的表输出混乱。 -选项 ``--desc`` 将排序方向设置为“DESC”。 +选项 ``--desc`` 将排序方式设置为 "DESC"。 检索字段元数据 ======================= @@ -83,11 +84,12 @@ db:table db:table --metadata ------------------- -当你有一个名为 ``my_table`` 的表时,你可以使用 ``--metadata`` 选项查看元数据,如列类型、表的最大长度: +当有一个名为 ``my_table`` 的表时，可以使用 ``--metadata`` 选项查看列类型、表的最大长度等元数据： .. code-block:: console php spark db:table my_table --metadata -使用此命令时,假定表存在。否则,CodeIgniter 将显示表列表以供选择。 -此外,你可以将此命令用作 ``db:table --metadata``。 +使用此命令时假定表存在。 +否则，CodeIgniter 会显示表列表供选择。 +也可以将此命令用作 ``db:table --metadata``。 diff --git a/source/dbmgmt/forge.rst b/source/dbmgmt/forge.rst index 178e73964..0137925fe 100644 --- a/source/dbmgmt/forge.rst +++ b/source/dbmgmt/forge.rst @@ -12,17 +12,17 @@ 初始化 Forge 类 **************************** -.. important:: 为了初始化 Forge 类,你的数据库驱动程序必须已经运行,因为 Forge 类依赖于它。 +.. important:: 为了初始化 Forge 类，数据库驱动程序必须已经在运行，因为 Forge 类依赖于它。 -如下加载 Forge 类: +这样加载 Forge 类： .. literalinclude:: forge/001.php -你也可以向 DB Forge 加载器传递另一个数据库组名称,以防要管理的数据库不是默认数据库: +你也可以将另一个数据库组名传递给 DB Forge 加载器，以防要管理的数据库不是默认的： .. literalinclude:: forge/002.php -在上面的示例中,我们正在作为第一个参数传递一个不同的数据库组名称进行连接。 +在上面的示例中，我们将不同的数据库组名作为第一个参数传递进行连接。 ******************************* 创建和删除数据库 @@ -31,51 +31,52 @@ $forge->createDatabase('db_name') ================================= -允许你创建第一个参数中指定的数据库。基于成功或失败返回 true/false: +允许你创建第一个参数中指定的数据库。根据成功或失败返回 true/false： .. literalinclude:: forge/003.php -可选的第二个参数设置为 true 将添加 ``IF EXISTS`` 语句，或者在创建数据库之前检查数据库是否存在（具体取决于 DBMS）。 +可选的第二个参数设置为 true 将添加 ``IF EXISTS`` 语句，或者在创建前检查数据库是否存在（取决于 DBMS）。 .. literalinclude:: forge/004.php $forge->dropDatabase('db_name') =============================== -允许你删除第一个参数中指定的数据库。基于成功或失败返回 true/false: +允许你删除第一个参数中指定的数据库。根据成功或失败返回 true/false： .. literalinclude:: forge/005.php 在命令行中创建数据库 ====================================== -CodeIgniter 支持直接从喜欢的终端使用专用的 ``db:create`` 命令创建数据库。通过使用此命令,假定数据库还不存在。否则,CodeIgniter 将抱怨数据库创建失败。 +CodeIgniter 支持使用专用的 ``db:create`` 命令直接从你喜爱的终端创建数据库。使用此命令时假定数据库尚不存在。否则，CodeIgniter 将提示数据库创建失败。 -首先,只需键入命令和数据库名称(例如 ``foo``): +开始只需输入命令和数据库名称（例如，``foo``）： .. code-block:: console php spark db:create foo -如果一切顺利,你应该会看到显示的 ``Database "foo" successfully created.`` 消息。 +如果一切顺利，你应该会看到 ``Database "foo" successfully created.`` 消息显示。 -如果你在测试环境中或正在使用 SQLite3 驱动程序,可以使用 ``--ext`` 选项 -为将创建数据库的文件传递文件扩展名。有效值为 ``db`` 和 ``sqlite``,默认为 ``db``。请记住,这些前面不应有句点。 -: +如果你在测试环境中或使用 SQLite3 驱动程序，可以使用 ``--ext`` 选项传入文件扩展名来指定创建数据库的文件。有效值为 ``db`` 和 +``sqlite``，默认为 ``db``。记住这些值前面不应有句号。 .. code-block:: console php spark db:create foo --ext sqlite -上述命令将创建名为 **WRITEPATH/foo.sqlite** 的数据库文件。 +上述命令将在 **WRITEPATH/foo.sqlite** 中创建数据库文件。 -.. note:: 当使用特殊的 SQLite3 数据库名称 ``:memory:`` 时,请注意命令仍会生成成功消息,但不会创建数据库文件。这是因为 SQLite3 将只使用内存中的数据库。 +.. note:: 使用特殊的 SQLite3 数据库名称 ``:memory:`` 时，预期命令仍会 + 产生成功消息但不会创建数据库文件。这是因为 SQLite3 只会使用 + 内存数据库。 *************** 创建表 *************** -在创建表时,你可能希望执行几件事。添加字段、向表添加键、更改列。CodeIgniter 为此提供了一种机制。 +创建表时你可能希望做几件事。添加字段、向表添加键、修改字段。CodeIgniter 为此提供了一种机制。 .. _adding-fields: @@ -85,31 +86,35 @@ CodeIgniter 支持直接从喜欢的终端使用专用的 ``db:create`` 命令 $forge->addField() ------------------ -字段通常通过关联数组创建。在数组中,你必须包含与字段的数据类型相关的 ``type`` 键。 +字段通常通过关联数组创建。在数组中，必须包含与字段数据类型相关的 ``type`` 键。 -例如, ``INT``、``VARCHAR``、``TEXT`` 等。许多数据类型(例如 ``VARCHAR``)还需要一个 ``constraint`` 键。 +例如，``INT``、``VARCHAR``、``TEXT`` 等。 +许多数据类型（例如 ``VARCHAR``）还需要 ``constraint`` 键。 .. literalinclude:: forge/006.php -另外,可以使用以下键/值: +此外，可以使用以下键/值： -- ``unsigned``/true : 在字段定义中生成 ``UNSIGNED``。 -- ``default``/value : 在字段定义中生成 ``DEFAULT`` 约束。 -- ``null``/true : 在字段定义中生成 ``null``。如果不指定,字段将默认为 ``NOT null``。 -- ``auto_increment``/true : 在字段上生成 auto_increment 标志。请注意,字段类型必须是支持这一点的类型,如 ``INTEGER``。 -- ``unique``/true : 为字段定义生成唯一键。 +- ``unsigned``/true : 在字段定义中生成 ``UNSIGNED``。 +- ``default``/value : 在字段定义中生成 ``DEFAULT`` 约束。 +- ``null``/true : 在字段定义中生成 ``NULL``。如果没有此项，字段将默认为 ``NOT NULL``。 +- ``auto_increment``/true : 在字段上生成 auto_increment 标志。注意，字段类型必须是支持此功能的类型，例如 ``INTEGER``。 +- ``unique``/true : 为字段定义生成唯一键。 .. literalinclude:: forge/007.php -在定义了字段后,可以使用 ``$forge->addField($fields)`` 后跟对 :ref:`createTable() ` 方法的调用来添加它们。 +定义字段后，可以使用 +``$forge->addField($fields)`` 添加它们，然后调用 +:ref:`createTable() ` 方法。 -关于数据类型的注解 +数据类型说明 ------------------- 浮点类型 ^^^^^^^^^^^^^^^^^^^^ -浮点类型，如 ``FLOAT`` 和 ``DOUBLE``，表示的是近似值。因此，当需要精确值时，不应使用它们。 +浮点类型如 ``FLOAT`` 和 ``DOUBLE`` 表示近似值。 +因此，当需要精确值时不应使用它们。 :: @@ -127,50 +132,52 @@ $forge->addField() +------+------+ 1 row in set (0.01 sec) -当需要保存精确的精度时，例如在处理货币数据，应使用 ``DECIMAL`` 或 ``NUMERIC``。 +当需要保持精确精度时，例如货币数据， +应使用 ``DECIMAL`` 或 ``NUMERIC``。 TEXT ^^^^ -SQLSRV 上不应使用 ``TEXT``，它已被弃用。 -欲知详情，请参见 `ntext, text, 和 image (Transact-SQL) - SQL Server | Microsoft Learn `_。 +``TEXT`` 不应在 SQLSRV 上使用。它已被弃用。 +参见 `ntext, text, and image (Transact-SQL) - SQL Server | Microsoft Learn `_。 ENUM ^^^^ 并非所有数据库都支持 ``ENUM``。 -从 v4.5.0 开始，``SQLSRV`` Forge 会将 ``ENUM`` 数据类型转换为 ``VARCHAR(n)``。 -之前的版本转换为 ``TEXT``。 +从 v4.5.0 开始，``SQLSRV`` Forge 将 ``ENUM`` 数据类型转换为 ``VARCHAR(n)``。 +先前版本转换为 ``TEXT``。 .. _forge-addfield-default-value-rawsql: -作为默认值的原始 SQL 字符串 +将原始 SQL 字符串作为默认值 --------------------------------- .. versionadded:: 4.2.0 -从 v4.2.0 开始, ``$forge->addField()`` 接受一个 ``CodeIgniter\Database\RawSql`` 实例,它表示原始 SQL 字符串。 +从 v4.2.0 开始，``$forge->addField()`` 接受 ``CodeIgniter\Database\RawSql`` 实例，它表示原始 SQL 字符串。 .. literalinclude:: forge/027.php -.. warning:: 当你使用 ``RawSql`` 时,必须手动对数据进行转义。否则可能会导致 SQL 注入。 +.. warning:: 使用 ``RawSql`` 时，必须手动转义数据。否则可能导致 SQL 注入。 -作为字段传递字符串 +将字符串作为字段传递 ------------------------- -如果确切知道如何创建字段,可以将字符串传递到 ``addField()`` 中的字段定义中: +如果你确切知道希望如何创建字段，可以将 +字符串传入字段定义中，使用 ``addField()``： .. literalinclude:: forge/008.php -.. note:: 不能在传递原始字符串作为字段后对这些字段调用 ``addKey()``。 +.. note:: 将原始字符串作为字段传递后，不能对这些字段调用 ``addKey()``。 -.. note:: 对 ``addField()`` 的多次调用是累积的。 +.. note:: 多次调用 ``addField()`` 是累积的。 创建 id 字段 -------------------- -创建 id 字段有一个特殊的例外。类型为 id 的字段将自动被赋值为 INT(9) 自增主键。 +创建 id 字段有特殊例外。类型为 id 的字段将自动被分配为 INT(9) auto_incrementing 主键。 .. literalinclude:: forge/009.php @@ -182,9 +189,10 @@ ENUM $forge->addKey() ---------------- -通常,你会希望表具有键。这是通过 ``$forge->addKey('field')`` 完成的。可选的第二个参数设置为 true 将使其成为主键,第三个参数设置为 true 将使其成为唯一键。你可以使用第四个参数指定名称。请注意, ``addKey()`` 必须在表已存在的情况下后跟对 ``createTable()`` 或 ``processIndexes()`` 的调用。 +一般来说，你会希望表具有键。这可以通过 +``$forge->addKey('field')`` 完成。可选的第二个参数设置为 true 将使其成为主键，第三个参数设置为 true 将使其成为唯一键。你可以使用第四个参数指定名称。注意 ``addKey()`` 必须后跟对 ``createTable()`` 的调用，或者当表已存在时调用 ``processIndexes()``。 -多个非主键列必须作为数组发送。以下为 MySQL 的示例输出。 +多个非主键字段必须以数组形式发送。下面的示例输出适用于 MySQL。 .. literalinclude:: forge/010.php @@ -194,58 +202,61 @@ $forge->addPrimaryKey() $forge->addUniqueKey() ---------------------- -为了使代码更易读,也可以使用特定方法添加主键和唯一键: +为了使代码更易读，也可以使用特定方法添加主键和唯一键： .. literalinclude:: forge/011.php -.. note:: 当你添加主键时,即使提供了名称,MySQL 和 SQLite 也会假定名称为 ``PRIMARY``。 +.. note:: 添加主键时，MySQL 和 SQLite 将假定名称为 ``PRIMARY``，即使提供了名称。 .. _adding-foreign-keys: 添加外键 =================== -外键有助于在表之间强制关系和操作。对于支持外键的表,可以直接在 forge 中添加它们: +外键有助于在表之间强制执行关系和操作。对于支持外键的表， +可以直接在 forge 中添加它们： .. literalinclude:: forge/012.php -你还可以指定约束的“更新时”和“删除时”属性的所需操作以及名称: +你可以指定约束的 "on update" 和 "on delete" 属性的所需操作以及名称： .. literalinclude:: forge/013.php -.. note:: SQLite3 不支持命名外键。CodeIgniter 将引用它们的 ``prefix_table_column_foreign``。 +.. note:: SQLite3 不支持外键命名。CodeIgniter 将通过 ``prefix_table_column_foreign`` 引用它们。 .. _creating-a-table: -创建表格 +创建表 ================ -在声明字段和键之后,可以使用以下方法创建新表格 +声明字段和键后，可以使用以下命令创建新表 .. literalinclude:: forge/014.php -可选的第二个参数设置为 true 将只在表不存在时创建该表。 +可选的第二个参数设置为 true 将仅在表尚不存在时创建表。 .. literalinclude:: forge/015.php -你也可以传递可选的表属性,例如 MySQL 的 ``ENGINE``: +你也可以传递可选的表属性，例如 MySQL 的 ``ENGINE``： .. literalinclude:: forge/016.php -.. note:: 除非指定了 ``CHARACTER SET`` 和/或 ``COLLATE`` 属性,否则 ``createTable()`` 将始终使用配置的 *charset* 和 *DBCollat* 值添加它们,只要它们不为空(仅限 MySQL)。 +.. note:: 除非指定 ``CHARACTER SET`` 和/或 ``COLLATE`` 属性， + ``createTable()`` 将始终使用你配置的 *charset* + 和 *DBCollat* 值添加它们，只要它们不为空（仅 MySQL）。 *************** 删除表 *************** -删除一张表 +删除表 ================ -执行 ``DROP TABLE`` 语句,并可选地添加 ``IF EXISTS`` 子句。 +执行 ``DROP TABLE`` 语句并可选择添加 ``IF EXISTS`` 子句。 .. literalinclude:: forge/017.php -可以传递第三个参数以添加 ``CASCADE`` 选项,某些驱动程序可能需要它来处理具有外键的表的删除。 +可以传递第三个参数以添加 ``CASCADE`` 选项，某些驱动程序可能需要此选项来处理具有外键的表的删除。 .. literalinclude:: forge/018.php @@ -259,15 +270,19 @@ $forge->addUniqueKey() $forge->addColumn() ------------------- -``addColumn()`` 方法用于修改现有表。它接受与 :ref:`创建表 ` 相同的字段数组,可用于添加其他字段。 +``addColumn()`` 方法用于修改现有表。它 +接受与 :ref:`创建表 ` 相同的字段数组，并且可以 +用于添加额外字段。 -.. note:: 与创建表不同,如果未指定 ``null``,列将为 ``NULL``,而不是 ``NOT NULL``。 +.. note:: 与创建表时不同，如果未指定 ``null``，列 + 将为 ``NULL``，而不是 ``NOT NULL``。 .. literalinclude:: forge/022.php -如果使用 MySQL 或 CUBIRD,则可以利用它们的 ``AFTER`` 和 ``FIRST`` 子句来定位新列。 +如果使用 MySQL 或 CUBIRD，可以利用它们的 +``AFTER`` 和 ``FIRST`` 子句来定位新字段。 -例子: +示例： .. literalinclude:: forge/023.php @@ -295,15 +310,19 @@ $forge->dropColumn() $forge->modifyColumn() ---------------------- -此方法的使用与 ``addColumn()`` 相同,只是它更改现有列而不是添加新列。为了更改名称,可以将“name”键添加到定义字段的数组中。 +此方法的用法与 ``addColumn()`` 相同，只是它 +修改现有字段而不是添加新字段。为了 +更改名称，可以在字段定义数组中添加 "name" 键。 .. literalinclude:: forge/026.php -.. note:: ``modifyColumn()`` 可能会意外地更改 ``NULL``/``NOT NULL``。因此,建议始终为 ``null`` 键指定值。与创建表不同,如果未指定 ``null``,列将为 ``NULL``,而不是 ``NOT NULL``。 +.. note:: ``modifyColumn()`` 可能会意外更改 ``NULL``/``NOT NULL``。 + 因此建议始终为 ``null`` 键指定值。与创建表时不同， + 如果未指定 ``null``，字段将为 ``NULL``，而不是 ``NOT NULL``。 -.. note:: 由于一个错误,在 v4.3.4 之前,即使指定 ``'null' => false``,SQLite3 也可能不设置 ``NOT NULL``。 +.. note:: 由于错误，在 v4.3.4 之前，SQLite3 即使指定 ``'null' => false`` 也可能不设置 ``NOT NULL``。 -.. note:: 由于一个错误,在 v4.3.4 之前,Postgres 和 SQLSRV 即使指定 ``'null' => true`` 也会设置 ``NOT NULL``。 +.. note:: 由于错误，在 v4.3.4 之前，Postgres 和 SQLSRV 即使指定 ``'null' => true`` 也会设置 ``NOT NULL``。 .. _db-forge-adding-keys-to-a-table: @@ -312,7 +331,8 @@ $forge->modifyColumn() .. versionadded:: 4.3.0 -你可以通过使用 ``addKey()``、``addPrimaryKey()``、``addUniqueKey()`` 或 ``addForeignKey()`` 和 ``processIndexes()`` 向现有表添加键: +可以使用 ``addKey()``、``addPrimaryKey()``、 +``addUniqueKey()`` 或 ``addForeignKey()`` 和 ``processIndexes()`` 向现有表添加键： .. literalinclude:: forge/029.php @@ -344,7 +364,7 @@ $forge->modifyColumn() 重命名表 ================ -执行 TABLE RENAME +执行 TABLE 重命名 .. literalinclude:: forge/021.php @@ -358,164 +378,165 @@ $forge->modifyColumn() .. php:method:: addColumn($table[, $field = []]) - :param string $table: 要向其中添加列的表名 + :param string $table: 要添加字段的表名 :param array $field: 列定义 - :returns: 成功则为 true,失败则为 false + :returns: 成功时返回 true，失败时返回 false :rtype: bool - 向现有表添加列。用法:参见 `向表中添加字段`_. + 向现有表添加z字段。用法：参见 `向表中添加字段`_。 .. php:method:: addField($field) :param array $field: 要添加的字段定义 - :returns: ``\CodeIgniter\Database\Forge`` 实例(方法链) + :returns: ``\CodeIgniter\Database\Forge`` 实例（方法链） :rtype: ``\CodeIgniter\Database\Forge`` - 将用于创建表的字段添加到集合中。用法:参见 `添加字段`_。 + 向将用于创建表的集合添加字段。用法：参见 `添加字段`_。 .. php:method:: addForeignKey($fieldName, $tableName, $tableField[, $onUpdate = '', $onDelete = '', $fkName = '']) - :param string|string[] $fieldName: 键字段的名称或字段数组 - :param string $tableName: 父表的名称 - :param string|string[] $tableField: 父表字段的名称或字段数组 - :param string $onUpdate: “更新时”的所需操作 - :param string $onDelete: “删除时”的所需操作 - :param string $fkName: 外键的名称。这与 SQLite3 不兼容 - :returns: ``\CodeIgniter\Database\Forge`` 实例(方法链) + :param string|string[] $fieldName: 键字段名称或字段数组 + :param string $tableName: 父表名称 + :param string|string[] $tableField: 父表字段名称或字段数组 + :param string $onUpdate: "on update" 的所需操作 + :param string $onDelete: "on delete" 的所需操作 + :param string $fkName: 外键名称。这不适用于 SQLite3 + :returns: ``\CodeIgniter\Database\Forge`` 实例（方法链） :rtype: ``\CodeIgniter\Database\Forge`` - 将用于创建表的外键添加到集合中。用法:参见 `添加外键`_。 + 向将用于创建表的集合添加外键。用法：参见 `添加外键`_。 - .. note:: 从 v4.3.0 开始可以使用 ``$fkName``。 + .. note:: 从 v4.3.0 起可以使用 ``$fkName``。 .. php:method:: addKey($key[, $primary = false[, $unique = false[, $keyName = '']]]) - :param mixed $key: 键字段的名称或字段数组 - :param bool $primary: 设置为 true 将其设置为主键,否则设置为常规键 - :param bool $unique: 设置为 true 将其设置为唯一键,否则设置为常规键 - :param string $keyName: 要添加的键的名称 - :returns: ``\CodeIgniter\Database\Forge`` 实例(方法链) + :param mixed $key: 键字段名称或字段数组 + :param bool $primary: 如果应为主键则设置为 true，否则为常规键 + :param bool $unique: 如果应为唯一键则设置为 true，否则为常规键 + :param string $keyName: 要添加的键名称 + :returns: ``\CodeIgniter\Database\Forge`` 实例（方法链） :rtype: ``\CodeIgniter\Database\Forge`` - 将用于创建表的键添加到集合中。用法:参见 `添加键`_。 + 向将用于创建表的集合添加键。用法：参见 `添加键`_。 - .. note:: 从 v4.3.0 开始可以使用 ``$keyName``。 + .. note:: 从 v4.3.0 起可以使用 ``$keyName``。 .. php:method:: addPrimaryKey($key[, $keyName = '']) - :param mixed $key: 键字段的名称或字段数组 - :param string $keyName: 要添加的键的名称 - :returns: ``\CodeIgniter\Database\Forge`` 实例(方法链) + :param mixed $key: 键字段名称或字段数组 + :param string $keyName: 要添加的键名称 + :returns: ``\CodeIgniter\Database\Forge`` 实例（方法链） :rtype: ``\CodeIgniter\Database\Forge`` - 将用于创建表的主键添加到集合中。用法:参见 `添加键`_。 + 向将用于创建表的集合添加主键。用法：参见 `添加键`_。 - .. note:: 从 v4.3.0 开始可以使用 ``$keyName``。 + .. note:: 从 v4.3.0 起可以使用 ``$keyName``。 .. php:method:: addUniqueKey($key[, $keyName = '']) - :param mixed $key: 键字段的名称或字段数组 - :param string $keyName: 要添加的键的名称 - :returns: ``\CodeIgniter\Database\Forge`` 实例(方法链) + :param mixed $key: 键字段名称或字段数组 + :param string $keyName: 要添加的键名称 + :returns: ``\CodeIgniter\Database\Forge`` 实例（方法链） :rtype: ``\CodeIgniter\Database\Forge`` - 将用于创建表的唯一键添加到集合中。用法:参见 `添加键`_。 + 向将用于创建表的集合添加唯一键。用法：参见 `添加键`_。 - .. note:: 从 v4.3.0 开始可以使用 ``$keyName``。 + .. note:: 从 v4.3.0 起可以使用 ``$keyName``。 .. php:method:: createDatabase($dbName[, $ifNotExists = false]) :param string $db_name: 要创建的数据库名称 - :param string $ifNotExists: 设置为 true 将添加 ``IF NOT EXISTS`` 子句或检查数据库是否存在 - :returns: 成功则为 true,失败则为 false + :param string $ifNotExists: 设置为 true 以添加 ``IF NOT EXISTS`` 子句或检查数据库是否存在 + :returns: 成功时返回 true，失败时返回 false :rtype: bool - 创建新数据库。用法:参见 `创建和删除数据库`_。 + 创建新数据库。用法：参见 `创建和删除数据库`_。 .. php:method:: createTable($table[, $if_not_exists = false[, array $attributes = []]]) - :param string $table: 要创建的表的名称 - :param string $if_not_exists: 设置为 true 将添加 ``IF NOT EXISTS`` 子句 + :param string $table: 要创建的表名称 + :param string $if_not_exists: 设置为 true 以添加 ``IF NOT EXISTS`` 子句 :param string $attributes: 表属性的关联数组 - :returns: 成功则为查询对象,失败则为 false + :returns: 成功时返回查询对象，失败时返回 false :rtype: mixed - 创建新表。用法:参见 `创建表格`_。 + 创建新表。用法：参见 `创建表`_。 .. php:method:: dropColumn($table, $columnNames) :param string $table: 表名 - :param mixed $columnNames: 逗号分隔的字符串或列名称数组 - :returns: 成功则为 true,失败则为 false + :param mixed $columnNames: 逗号分隔的字符串或列名数组 + :returns: 成功时返回 true，失败时返回 false :rtype: bool - 从表中删除单个或多个列。用法:参见 `从表中删除字段`_。 + 从表中删除单个或多个列。用法：参见 `从表中删除字段`_。 .. php:method:: dropDatabase($dbName) :param string $dbName: 要删除的数据库名称 - :returns: 成功则为 true,失败则为 false + :returns: 成功时返回 true，失败时返回 false :rtype: bool - 删除数据库。用法:参见 `创建和删除数据库`_。 + 删除数据库。用法：参见 `创建和删除数据库`_。 .. php:method:: dropKey($table, $keyName[, $prefixKeyName = true]) - :param string $table: 具有键的表的名称 - :param string $keyName: 要删除的键的名称 - :param string $prefixKeyName: 是否要添加数据库前缀到 ``$keyName`` - :returns: 成功则为 true,失败则为 false + :param string $table: 具有键的表名 + :param string $keyName: 要删除的键名称 + :param string $prefixKeyName: 是否应将数据库前缀添加到 ``$keyName`` + :returns: 成功时返回 true，失败时返回 false :rtype: bool 删除索引或唯一索引。 - .. note:: 从 v4.3.0 开始可以使用 ``$keyName`` 和 ``$prefixKeyName``。 + .. note:: 从 v4.3.0 起可以使用 ``$keyName`` 和 ``$prefixKeyName``。 .. php:method:: dropPrimaryKey($table[, $keyName = '']) - :param string $table: 要删除主键的表的名称 - :param string $keyName: 要删除的主键的名称 - :returns: 成功则为 true,失败则为 false + :param string $table: 要删除主键的表名 + :param string $keyName: 要删除的主键名称 + :returns: 成功时返回 true，失败时返回 false :rtype: bool 从表中删除主键。 - .. note:: 从 v4.3.0 开始可以使用 ``$keyName``。 + .. note:: 从 v4.3.0 起可以使用 ``$keyName``。 .. php:method:: dropTable($table_name[, $if_exists = false]) - :param string $table: 要删除的表的名称 - :param string $if_exists: 设置为 true 将添加 ``IF EXISTS`` 子句 - :returns: 成功则为 true,失败则为 false + :param string $table: 要删除的表名称 + :param string $if_exists: 设置为 true 以添加 ``IF EXISTS`` 子句 + :returns: 成功时返回 true，失败时返回 false :rtype: bool - 删除表。用法:参见 `删除一张表`_。 + 删除表。用法：参见 `删除表`_。 .. php:method:: processIndexes($table) .. versionadded:: 4.3.0 - :param string $table: 要向其中添加索引的表的名称 - :returns: 成功则为 true,失败则为 false + :param string $table: 要添加索引的表名称 + :returns: 成功时返回 true，失败时返回 false :rtype: bool - 跟在 ``addKey()``、``addPrimaryKey()``、``addUniqueKey()`` 和 ``addForeignKey()`` 之后, - 向已有表添加索引。参见 `向表添加键`_。 + 在 ``addKey()``、``addPrimaryKey()``、``addUniqueKey()`` + 和 ``addForeignKey()`` 之后使用，向现有表添加索引。 + 参见 `向表添加键`_。 .. php:method:: modifyColumn($table, $field) :param string $table: 表名 :param array $field: 列定义 - :returns: 成功则为 true,失败则为 false + :returns: 成功时返回 true，失败时返回 false :rtype: bool - 修改表列。用法:参见 `修改表中的字段`_。 + 修改表列。用法：参见 `修改表中的字段`_。 .. php:method:: renameTable($tableName, $newTableName) :param string $tableName: 表的当前名称 :param string $newTableName: 表的新名称 - :returns: 成功则为查询对象,失败则为 false + :returns: 成功时返回查询对象，失败时返回 false :rtype: mixed - 重命名表。用法:参见 `重命名表`_。 + 重命名表。用法：参见 `重命名表`_。 diff --git a/source/dbmgmt/migration.rst b/source/dbmgmt/migration.rst index 316e45f45..f7e352e9f 100644 --- a/source/dbmgmt/migration.rst +++ b/source/dbmgmt/migration.rst @@ -1,17 +1,17 @@ -########## +################### 数据库迁移 -########## +################### -迁移是一种以结构化和有序的方式修改数据库的便捷方法。你可以手工编辑 SQL 片段,但这样你就需要告知其他开发者他们需要运行这些片段。你也需要在下次部署到生产环境时跟踪哪些更改需要运行。 +迁移是一种以结构化和有序的方式修改数据库的便捷方法。你可以手动编辑 SQL 片段，但随后你将负责通知其他开发者需要运行这些脚本。你还需要跟踪下一次部署时需要在生产机器上运行的更改。 -数据库表 **迁移** 用于跟踪已经运行的迁移，因此你只需确保你的迁移文件已经准备好，并运行 ``spark migrate`` 命令将数据库更新到最新状态。你还可以使用 ``spark migrate --all`` 命令来包括所有命名空间的迁移。 +数据库表 **migrations** 用于跟踪已运行的迁移，因此你只需确保迁移文件已准备好，然后运行 ``spark migrate`` 命令即可将数据库更新到最新状态。你也可以使用 ``spark migrate --all`` 来包含所有命名空间的迁移。 .. contents:: - :local: - :depth: 2 + :local: + :depth: 2 ******************** -迁移文件命名 +迁移文件名 ******************** 迁移文件名由时间戳前缀、下划线（``_``）和描述性名称（类名）组成。 @@ -20,63 +20,63 @@ 每个迁移都使用创建迁移时的时间戳（**2024-09-08-013653**）进行编号，格式为 **YYYY-MM-DD-HHIISS**。 -迁移的描述性名称（**AddBlogTable**）是 PHP 中的类名，因此你必须为其命名一个有效的类名。 +迁移的描述性名称（**AddBlogTable**）是 PHP 中的一个类名。因此你必须使用有效的类名。 -前缀中的年、月、日和时间的分隔符可以是短横线（``-``）、下划线（``_``）或者不使用任何分隔符。例如： +前缀中的年、月、日和时间可以用连字符（``-``）、下划线（``_``）分隔，也可以不分隔。例如： * 2012-10-31-100538_AlterBlogTrackViews.php * 2012_10_31_100539_AlterBlogAddTranslations.php * 20121031100537_AddBlog.php -每个迁移根据所采取的方法按数字顺序向前或向后运行。这有助于在团队协作环境中避免编号冲突。 +每个迁移都按数字顺序向前或向后运行，具体取决于所采取的方法。这有助于在团队环境中防止编号冲突。 ****************** 创建迁移 ****************** -这将是为一个带博客的新网站创建的第一个迁移。所有迁移都在 **app/Database/Migrations/** 目录下,文件名类似 **2022-01-31-013057_AddBlog.php**。 +这将是一个包含博客功能的新站点的首次迁移。所有迁移都位于 **app/Database/Migrations/** 目录中，文件名如 **2022-01-31-013057_AddBlog.php**。 .. literalinclude:: migration/001.php -数据库连接和数据库 Forge 类都可以通过 ``$this->db`` 和 ``$this->forge`` 获取。 +数据库连接和数据库 Forge 类分别通过 ``$this->db`` 和 ``$this->forge`` 提供给你。 -或者，你可以使用命令行调用来生成一个骨架迁移文件。更多详情请参阅 :ref:`command-line-tools` 中的 `make:migration`_。 +或者，你可以使用命令行调用来生成一个骨架迁移文件。有关更多详细信息，请参阅 :ref:`command-line-tools` 中的 `make:migration`_。 -.. note:: 由于迁移类是一个 PHP 类,每个迁移文件中的类名必须是唯一的。 +.. note:: 由于迁移类是一个 PHP 类，因此类名在每个迁移文件中必须是唯一的。 外键 ============ -当你的表包含外键时,迁移经常在尝试删除表和列时会遇到问题。要在运行迁移时暂时绕过外键检查,可以在数据库连接上使用 ``disableForeignKeyChecks()`` 和 ``enableForeignKeyChecks()`` 方法。 +当你的表包含外键时，迁移在尝试删除表和列时经常会引发问题。要在运行迁移时临时绕过外键检查，请在数据库连接上使用 ``disableForeignKeyChecks()`` 和 ``enableForeignKeyChecks()`` 方法。 .. literalinclude:: migration/002.php 数据库组 =============== -一个迁移只会对单个数据库组执行。如果你在 **app/Config/Database.php** 中定义了多个组，那么它将按照该配置文件中指定的 ``$defaultGroup`` 运行。 +迁移仅针对单个数据库组运行。如果你在 **app/Config/Database.php** 中定义了多个组，那么默认情况下它将针对该配置文件中指定的 ``$defaultGroup`` 运行。 -有时你可能需要为不同的数据库组使用不同的模式。也许你有一个数据库用于所有常规站点信息,而另一个数据库用于业务关键的数据。 +有时你可能需要为不同的数据库组使用不同的模式。例如，你可能有一个数据库用于存储所有常规站点信息，而另一个数据库用于存储关键任务数据。 -你可以通过在迁移上设置 ``$DBGroup`` 属性来确保迁移只针对适当的组运行。此名称必须与数据库组的名称完全匹配: +你可以通过在迁移中设置 ``$DBGroup`` 属性来确保迁移仅在正确的组上运行。此名称必须与数据库组的名称完全匹配： .. literalinclude:: migration/003.php -.. note:: 跟踪已经运行过的迁移的 **migrations** 表将始终在默认数据库组中创建。 +.. note:: 用于跟踪已运行迁移的 **migrations** 表将始终在默认数据库组中创建。 命名空间 ========== -迁移库可以自动扫描你在 **app/Config/Autoload.php** 中定义的所有命名空间,或者从 Composer 等外部源加载的命名空间,使用 ``$psr4`` 属性匹配目录名称。它将包含在 **Database/Migrations** 中找到的所有迁移。 +迁移库可以使用 ``$psr4`` 属性匹配目录名称，自动扫描你在 **app/Config/Autoload.php** 中定义或从 Composer 等外部源加载的所有命名空间。它将包含在 **Database/Migrations** 中找到的所有迁移。 -每个命名空间都有自己的版本序列,这将帮助你升级和降级每个模块(命名空间)而不影响其他命名空间。 +每个命名空间都有自己的版本序列，这将帮助你在不影响其他命名空间的情况下升级和降级每个模块（命名空间）。 -例如,假设我们在 Autoload 配置文件中定义了以下命名空间: +例如，假设我们的 Autoload 配置文件中定义了以下命名空间： .. literalinclude:: migration/004.php :lines: 2- -这将查找 **APPPATH/Database/Migrations** 和 **ROOTPATH/MyCompany/Database/Migrations** 中的任何迁移。这使得在你的可重用、模块化代码套件中包含迁移变得很简单。 +这将查找位于 **APPPATH/Database/Migrations** 和 **ROOTPATH/MyCompany/Database/Migrations** 的所有迁移。这使得在可重用的模块化代码套件中包含迁移变得简单。 .. _command-line-tools: @@ -84,73 +84,73 @@ 命令行工具 ******************* -CodeIgniter 自带了几个 :doc:`commands `,可通过命令行访问,以帮助你使用迁移。这些工具使得使用迁移更加方便。这些工具主要提供了 MigrationRunner 类中可用的相同方法的访问。 +CodeIgniter 提供了多个 :doc:`命令 `，这些命令可以从命令行使用，以帮助你处理迁移。这些工具为你提供了更便捷的操作方式。这些工具主要提供了对 MigrationRunner 类中可用方法的访问。 migrate ======= -使用所有可用的迁移迁移一个数据库组: +使用所有可用的迁移来迁移一个数据库组： .. code-block:: console php spark migrate -你可以对 ``migrate`` 使用以下选项： +你可以将 ``migrate`` 与以下选项一起使用： -- ``-g`` - 用于指定数据库组。如果指定了该选项，只会运行指定数据库组的迁移。如果未指定，则会运行所有迁移。 -- ``-n`` - 用于选择命名空间，否则将使用 ``App`` 命名空间。 -- ``--all`` - 迁移所有命名空间到最新的迁移。 +- ``-g`` - 指定数据库组。如果指定了该选项，则仅运行指定数据库组的迁移。如果未指定，则运行所有迁移。 +- ``-n`` - 选择命名空间，否则将使用 ``App`` 命名空间。 +- ``--all`` - 将所有命名空间迁移到最新的迁移。 -这个例子将在 test 数据库组上使用任何新的迁移迁移 ``Acme\Blog`` 命名空间: +此示例将在测试数据库组上，将 ``Acme\Blog`` 命名空间与任何新迁移进行迁移： -For Unix: +对于 Unix 系统： .. code-block:: console php spark migrate -g test -n Acme\\Blog -For Windows: +对于 Windows 系统： .. code-block:: console php spark migrate -g test -n Acme\Blog -当使用 ``--all`` 选项时,它将扫描所有命名空间,尝试找到任何未运行的迁移。这些迁移将一起收集,然后按创建日期排序为一组。这应该有助于最大限度地减少主应用程序和任何模块之间的潜在冲突。 +当使用 ``--all`` 选项时，它将扫描所有命名空间，尝试找到尚未运行的迁移。这些迁移将被全部收集，然后按创建日期分组排序。这有助于最大限度地减少主应用程序和任何模块之间的潜在冲突。 migrate:rollback ================ -回滚所有迁移到空白状态,有效迁移到 0: +将所有迁移回滚到空白状态，即回滚到迁移 0： .. code-block:: console php spark migrate:rollback -你可以对 ``migrate:rollback`` 使用以下选项: +你可以将 ``migrate:rollback`` 与以下选项一起使用： -- ``-b`` - 选择批次:自然数指定批次。 -- ``-f`` - 强制绕过确认问题,它仅在生产环境中询问。 +- ``-b`` - 选择批次：自然数指定批次。 +- ``-f`` - 强制跳过确认问题，该问题仅在生产环境中被询问。 migrate:refresh =============== -首先回滚所有迁移,然后迁移所有来刷新数据库状态: +通过首先回滚所有迁移，然后再次执行所有迁移来刷新数据库状态： .. code-block:: console php spark migrate:refresh -你可以对 ``migrate:refresh`` 使用以下选项: +你可以将 ``migrate:refresh`` 与以下选项一起使用： -- ``-g`` - 用于指定数据库组。如果指定了该选项，只会运行指定数据库组的迁移。如果未指定，则会运行所有迁移。 -- ``-n`` - 用于选择命名空间，否则将使用 ``App`` 命名空间。 +- ``-g`` - 指定数据库组。如果指定了该选项，则仅运行指定数据库组的迁移。如果未指定，则运行所有迁移。 +- ``-n`` - 选择命名空间，否则将使用 ``App`` 命名空间。 - ``--all`` - 刷新所有命名空间。 -- ``-f`` - 强制绕过确认问题,它仅在生产环境中询问。 +- ``-f`` - 强制跳过确认问题，该问题仅在生产环境中被询问。 migrate:status ============== -显示所有迁移的列表以及它们运行的日期和时间,如果未运行则显示 '--': +显示所有迁移的列表以及它们运行的日期和时间，如果尚未运行则显示 '--'： .. code-block:: console @@ -166,43 +166,43 @@ migrate:status | CodeIgniter\Settings | 2021-11-14-143905 | AddContextColumn | default | 2022-04-06 01:23:08 | 1 | +----------------------+-------------------+-----------------------+---------+---------------------+-------+ -你可以对 ``migrate:status`` 使用以下选项: +你可以将 ``migrate:status`` 与以下选项一起使用： -- ``-g`` - 用于指定数据库组。如果指定了该选项，只会检查指定数据库组的迁移。如果未指定，则会检查所有迁移。 +- ``-g`` - 指定数据库组。如果指定了该选项，则仅检查指定数据库组的迁移。如果未指定，则检查所有迁移。 make:migration ============== -在 **app/Database/Migrations** 中创建一个骨架迁移文件。它会自动在文件名前加上当前时间戳。它创建的类名是文件名的大驼峰版本。 +在 **app/Database/Migrations** 中创建一个骨架迁移文件。它会自动在文件名前添加当前时间戳。它创建的类名是文件名的帕斯卡命名法（Pascal case）版本。 .. code-block:: console php spark make:migration [options] -你可以对 ``make:migration`` 使用以下选项: +你可以将 ``make:migration`` 与以下选项一起使用： -- ``--namespace`` - 设置根命名空间。默认: ``APP_NAMESPACE``。 -- ``--suffix`` - 在类名后追加组件标题。 +- ``--namespace`` - 设置根命名空间。默认值：``APP_NAMESPACE``。 +- ``--suffix`` - 将组件标题附加到类名。 -以下选项也可用于为数据库 Sessions 生成迁移文件: +以下选项也可用于为数据库会话生成迁移文件： -- ``--session`` - 为数据库 sessions 生成迁移文件。 -- ``--table`` - 数据库 sessions 使用的表名。默认: ``ci_sessions``。 -- ``--dbgroup`` - 数据库 sessions 使用的数据库组。默认: ``default``。 +- ``--session`` - 为数据库会话生成迁移文件。 +- ``--table`` - 用于数据库会话的表名。默认值：``ci_sessions``。 +- ``--dbgroup`` - 用于数据库会话的数据库组。默认值：``default``。 ********************* 迁移配置 ********************* -下表列出了所有迁移的配置选项,在 **app/Config/Migrations.php** 中可用。 +以下是 **app/Config/Migrations.php** 中可用的迁移配置选项表。 -========================== ====================== ========================== ================================================================================= -首选项 默认值 可选值 描述 -========================== ====================== ========================== ================================================================================= -**enabled** true true / false 启用或禁用迁移。 -**table** migrations None 用于存储 schema 版本号的表名。该表始终在默认数据库组（``$defaultGroup``）中创建。 -**timestampFormat** Y-m-d-His\_ 创建迁移时使用的时间戳格式。 -========================== ====================== ========================== ================================================================================= +==================== ============ ============= ============================================================= +配置项 默认值 选项 说明 +==================== ============ ============= ============================================================= +**enabled** true true / false 启用或禁用迁移。 +**table** migrations 无 用于存储模式版本号的表名。此表始终在默认数据库组（``$defaultGroup``）中创建。 +**timestampFormat** Y-m-d-His\_ 创建迁移时用于时间戳的格式。 +==================== ============ ============= ============================================================= *************** 类参考 @@ -214,60 +214,60 @@ make:migration .. php:method:: findMigrations() - :returns: 迁移文件数组 + :returns: 迁移文件的数组 :rtype: array 返回在 ``path`` 属性中找到的迁移文件名数组。 .. php:method:: latest($group) - :param mixed $group: 数据库组名称,如果为 null 则使用默认数据库组。 - :returns: 成功则为 ``true``,失败则为 ``false`` + :param mixed $group: 数据库组名，如果为 null 则使用默认数据库组。 + :returns: 成功时返回 ``true``，失败时返回 ``false`` :rtype: bool - 该方法定位命名空间(或所有命名空间)的迁移,确定哪些迁移尚未运行,并按版本顺序运行它们(命名空间交错)。 + 它会定位命名空间（或所有命名空间）的迁移，确定哪些迁移尚未运行，并按版本顺序运行它们（命名空间混合在一起）。 .. php:method:: regress($targetBatch, $group) - :param int $targetBatch: 要迁移到的前一批次; 1+ 指定批次,0 还原全部,负数指相对批次(例如 -3 表示“往前三批”) - :param ?string $group: 数据库组名称,如果为 null 则使用默认数据库组。 - :returns: 成功则为 ``true``,失败或找不到迁移则为 ``false`` + :param int $targetBatch: 要回滚到的上一批次；1+ 指定批次，0 回滚所有，负数表示相对批次（例如，-3 表示“回滚三批”） + :param ?string $group: 数据库组名，如果为 null 则使用默认数据库组。 + :returns: 成功时返回 ``true``，失败或未找到迁移时返回 ``false`` :rtype: bool - 回滚可用于将更改回滚到以前的状态,逐批进行。 + regress 可用于将更改回滚到以前的状态，按批次进行。 .. literalinclude:: migration/006.php .. php:method:: force($path, $namespace, $group) :param mixed $path: 有效迁移文件的路径。 - :param mixed $namespace: 所提供迁移的命名空间。 - :param mixed $group: 数据库组名称,如果为 null 则使用默认数据库组。 - :returns: 成功则为 ``true``,失败则为 ``false`` + :param mixed $namespace: 提供的迁移的命名空间。 + :param mixed $group: 数据库组名，如果为 null 则使用默认数据库组。 + :returns: 成功时返回 ``true``，失败时返回 ``false`` :rtype: bool - 该方法强制单文件迁移,不考虑顺序或批次。基于它是否已经迁移来检测 ``up()`` 或 ``down()`` 方法。 + 它强制单个文件进行迁移，无论顺序或批次如何。``up()`` 或 ``down()`` 方法根据是否已迁移来确定。 - .. note:: 该方法仅建议用于测试,可能会导致数据一致性问题。 + .. note:: 此方法仅建议用于测试，可能会导致数据一致性问题。 .. php:method:: setNamespace($namespace) - :param string|null $namespace: 应用程序命名空间。``null`` 为所有命名空间。 + :param string|null $namespace: 应用程序命名空间。``null`` 表示所有命名空间。 :returns: 当前的 MigrationRunner 实例 :rtype: CodeIgniter\\Database\\MigrationRunner - 设置库应查找迁移文件的命名空间: + 设置库应查找迁移文件的命名空间： .. literalinclude:: migration/007.php - .. note:: 如果设置为 ``null``,则它将查找所有命名空间中的迁移文件。 + .. note:: 如果你设置为 ``null``，它将在所有命名空间中查找迁移文件。 .. php:method:: setGroup($group) - :param string $group: 数据库组名称。 + :param string $group: 数据库组名。 :returns: 当前的 MigrationRunner 实例 :rtype: CodeIgniter\\Database\\MigrationRunner - 设置库应查找迁移文件的组: + 设置库应查找迁移文件的组： .. literalinclude:: migration/008.php diff --git a/source/dbmgmt/seeds.rst b/source/dbmgmt/seeds.rst index 3cc63b33a..005d71f28 100755 --- a/source/dbmgmt/seeds.rst +++ b/source/dbmgmt/seeds.rst @@ -2,8 +2,7 @@ 数据库填充 ################ -数据库填充是向数据库中添加数据的一个简单方法。它在开发过程中特别有用,你需要用一些样本数据来填充数据库以进行开发,但它的用途不仅限于此。 -填充器可以包含一些不想放入迁移文件的静态数据,像国家信息、地理编码表、事件或设置信息等等。 +数据库填充是一种向数据库添加数据的简单方法。在开发过程中尤其有用，当你需要使用示例数据填充数据库以便进行开发时，但并不仅限于此。填充器可以包含不适合放在迁移中的静态数据，例如国家、地理编码表、事件或设置信息等。 .. contents:: :local: @@ -13,9 +12,7 @@ 数据库填充器 **************** -数据库填充器是简单的类,必须有一个 ``run()`` 方法,并扩展 ``CodeIgniter\Database\Seeder``。 -在 ``run()`` 内,该类可以创建任何它需要的形式的数据。它可以通过 ``$this->db`` 和 ``$this->forge`` 访问数据库连接和伪造器。 -填充文件必须存储在 **app/Database/Seeds** 目录中。文件名必须与类名匹配。 +数据库填充器是简单的类，必须包含一个 ``run()`` 方法，并且继承 ``CodeIgniter\Database\Seeder``。在 ``run()`` 方法中，该类可以创建任何所需的数据。它可以通过 ``$this->db`` 和 ``$this->forge`` 分别访问数据库连接和 Forge。填充文件必须存储在 **app/Database/Seeds** 目录中。文件名必须与类名匹配。 .. literalinclude:: seeds/001.php @@ -23,12 +20,11 @@ 嵌套填充器 *************** -填充器可以通过 ``call()`` 方法调用其他填充器。这使你可以轻松组织一个中心填充器,但将任务组织到单独的填充器文件中: +填充器可以通过 ``call()`` 方法调用其他填充器。这允许你轻松地组织一个中心填充器，但将任务分散到单独的填充器文件中： .. literalinclude:: seeds/002.php -在 ``call()`` 方法中,你也可以使用完全限定的类名,这使你可以将填充器保存在自动加载程序可以找到的任何地方。 -这对于更模块化的代码库很有帮助: +你也可以在 ``call()`` 方法中使用完全限定的类名，允许你将填充器放在任何自动加载器可以找到的地方。这对于更模块化的项目结构非常有用： .. literalinclude:: seeds/003.php @@ -36,14 +32,14 @@ 使用填充器 ************* -你可以通过数据库配置类获取主填充器的副本: +你可以通过数据库配置类获取主填充器的实例： .. literalinclude:: seeds/004.php 命令行填充 ==================== -你也可以通过命令行作为迁移CLI工具的一部分从命令行填充数据,如果你不想创建一个专用的控制器: +你也可以通过命令行进行数据填充，作为迁移命令行工具的一部分，如果你不想创建一个专用的控制器： .. code-block:: console @@ -53,7 +49,7 @@ 创建填充器文件 ********************* -使用命令行,你可以轻松生成填充器文件。 +通过命令行，你可以轻松地生成填充文件： .. code-block:: console @@ -61,20 +57,20 @@ 上述命令将输出位于 **app/Database/Seeds** 目录下的 **UserSeeder.php** 文件。 -你可以通过提供 ``--namespace`` 选项来指定填充器文件要存储的 ``root`` 命名空间: +你可以通过提供 ``--namespace`` 选项来指定填充文件将存储的 ``root`` 命名空间： -For Unix: +对于 Unix 系统： .. code-block:: console php spark make:seeder MySeeder --namespace Acme\\Blog -For Windows: +对于 Windows 系统： .. code-block:: console php spark make:seeder MySeeder --namespace Acme\Blog -如果 ``Acme\Blog`` 映射到 **app/Blog** 目录,那么此命令将在 **app/Blog/Database/Seeds** 目录中生成 **MySeeder.php**。 +如果 ``Acme\Blog`` 映射到 **app/Blog** 目录，那么此命令将在 **app/Blog/Database/Seeds** 目录生成 **MySeeder.php** 文件。 -提供 ``--force`` 选项将覆盖目标位置中的现有文件。 +提供 ``--force`` 选项将覆盖目标位置的现有文件。 diff --git a/source/extending/authentication.rst b/source/extending/authentication.rst index 1c4c5f596..1fb49e684 100644 --- a/source/extending/authentication.rst +++ b/source/extending/authentication.rst @@ -1,20 +1,21 @@ 身份验证 ##################################### -CodeIgniter 为 CodeIgniter 4 提供了一个官方的身份验证和授权框架 :ref:`CodeIgniter Shield `，它被设计为安全、灵活且易于扩展，以满足许多不同类型网站的需求。 +CodeIgniter 为 CodeIgniter 4 提供了官方的身份验证和授权框架 :ref:`CodeIgniter Shield `， +它旨在提供安全、灵活且易于扩展的功能，以满足各种类型网站的需求。 -为了在开发者之间保持一致，以下是一些推荐的准则。 +以下是推荐的指南，以鼓励模块、项目和框架本身的开发者之间保持一致性。 -推荐 +推荐实践 =============== -* 处理登录和登出操作的模块在成功时应该触发 ``login`` 和 ``logout`` 事件 -* 定义“当前用户”的模块应该定义 ``user_id()`` 函数以返回用户的唯一标识符，如果没有当前用户则返回 ``null`` +* 处理登录和登出操作的模块应在成功时触发 ``login`` 和 ``logout`` 事件 +* 定义“当前用户”的模块应定义 ``user_id()`` 函数以返回用户的唯一标识符，或对“无当前用户”情况返回 ``null`` -符合这些推荐的模块可以在 **composer.json** 中添加以下内容表示兼容:: +满足这些推荐实践的模块可通过在 **composer.json** 中添加以下内容来表明其兼容性:: "provide": { "codeigniter4/authentication-implementation": "1.0" }, -你可以在 `Packagist `_ 上查看提供该实现的模块列表。 +你可以在 `Packagist `_ 上查看提供此实现的模块列表。 diff --git a/source/extending/basecontroller.rst b/source/extending/basecontroller.rst index 2050bb86e..e85f57273 100644 --- a/source/extending/basecontroller.rst +++ b/source/extending/basecontroller.rst @@ -2,8 +2,7 @@ 扩展控制器 ************************ -CodeIgniter 的核心控制器不应该改变,但是在 -**app/Controllers/BaseController.php** 提供了一个默认的类扩展。你创建的任何新控制器都应该扩展 ``BaseController`` 来利用预加载的组件和你提供的任何其他功能: +不应修改 CodeIgniter 的核心控制器，但框架为你提供了一个默认的类扩展，位于 **app/Controllers/BaseController.php**。你创建的任何新控制器都应继承 ``BaseController``，以利用预加载的组件和你提供的任何附加功能： .. literalinclude:: basecontroller/001.php @@ -14,24 +13,24 @@ CodeIgniter 的核心控制器不应该改变,但是在 预加载组件 ===================== -基础控制器是一个很好的地方,可以加载你打算在项目每次运行时使用的任何辅助函数、模型、类库、服务等。辅助函数应该添加到预定义的 ``$helpers`` 数组中。例如,如果你需要 HTML 和 Text 辅助函数在所有地方可用: +基础控制器是加载项目每次运行所需使用的任何辅助函数、模型、库、服务等内容的理想位置。辅助函数应添加到预定义的 ``$helpers`` 数组中。例如，如果你希望 HTML 和文本辅助函数在所有地方都可用： .. literalinclude:: basecontroller/002.php -需要加载的任何其他组件或要处理的数据应该添加到构造函数 ``initController()`` 中。例如,如果你的项目大量使用 Session 库,你可以在这里初始化它: +任何其他需要加载的组件或需要处理的数据都应添加到构造函数 ``initController()`` 中。例如，如果你的项目大量使用 Session 库，你可能希望在这里初始化它： .. literalinclude:: basecontroller/003.php -其他方法 +附加方法 ================== -基础控制器是不可路由的。作为一个额外的安全措施, **所有** 你创建的新方法都应该声明为 ``protected`` 或 ``private``,并且只能通过扩展 ``BaseController`` 的控制器访问它们。 +基础控制器本身不可路由。作为额外的安全措施，你创建的所有新方法都应声明为 ``protected`` 或 ``private``，并且只能通过你创建的继承自 ``BaseController`` 的控制器来访问。 -其他选择 +其他选项 ============= -你可能会发现需要多个基础控制器。只要其他控制器扩展正确的基础控制器,就可以创建多个基础控制器。例如,如果你的项目有复杂的公共接口和简单的管理门户,可以考虑让公共控制器扩展 ``BaseController``,为任何管理控制器创建 ``AdminController``。 +你可能会发现需要不止一个基础控制器。你可以创建新的基础控制器，只要你创建的其他控制器都继承了正确的基类即可。例如，如果你的项目有一个复杂的公共接口和一个简单的管理门户，你可能希望将 ``BaseController`` 用于公共控制器，并为管理控制器创建一个 ``AdminController``。 -如果你不想使用基础控制器,可以通过让控制器扩展系统的 Controller 来绕过它: +如果你不想使用基础控制器，可以通过让你的控制器继承系统控制器来绕过它： .. literalinclude:: basecontroller/004.php diff --git a/source/extending/common.rst b/source/extending/common.rst index 4ebba3de0..c526465b9 100644 --- a/source/extending/common.rst +++ b/source/extending/common.rst @@ -2,6 +2,6 @@ 替换通用函数 ************************** -CodeIgniter 中有很多函数需要提前加载,以便在核心类中使用,因此不能放入 helper 中。虽然大多数用户都不需要这样做,但对于那些想要显着改变 CodeIgniter 核心的人来说,替换这些函数的选项确实存在。在 **app/** 目录中有一个文件 **Common.php**,其中定义的任何函数都会优先于 **system/Common.php** 中的版本。这也是一个机会,可以创建在整个框架中打算使用的全局可用函数。 +CodeIgniter 有许多必需的函数需要在核心类中尽早加载，因此无法将其放入辅助函数中。尽管绝大多数开发者不会涉及此类修改，但对于希望深度定制核心功能的高级用户，框架仍提供了替换这些函数的机制。你可以在 **app/Common.php** 中定义自定义函数，这些函数将优先于 **system/Common.php** 中的同名函数被加载。此外，这也是定义可在整个应用中使用的全局函数的理想位置。 -.. note:: 与核心系统类挂钩有很多含义,所以在尝试之前,请确保你知道你在做什么。 +.. note:: 修改核心系统类有很多影响，因此在尝试之前，请确保你清楚自己在做什么。 diff --git a/source/extending/composer_packages.rst b/source/extending/composer_packages.rst index df5e0dce7..d726b3343 100644 --- a/source/extending/composer_packages.rst +++ b/source/extending/composer_packages.rst @@ -2,17 +2,18 @@ 创建 Composer 包 ########################## -你可以将你创建的 :doc:`../general/modules` 转换为 Composer 包，或者为 CodeIgniter 4 创建一个 Composer 包。 +你可以将创建的 :doc:`../general/modules` 制作成 Composer 包， +或为 CodeIgniter 4 创建 Composer 包。 .. contents:: :local: :depth: 2 **************** -文件夹结构 +目录结构 **************** -下面是一个典型的 Composer 包的目录结构示例:: +Composer 包的典型目录结构如下:: your-package-name/ ├── .gitattributes @@ -29,9 +30,9 @@ 创建 composer.json ********************** -在你的包目录的根目录中，创建一个 **composer.json** 文件。该文件定义了关于你的包及其依赖项的元数据。 +在包目录的根目录下，创建一个 **composer.json** 文件。该文件定义了有关包及其依赖项的元数据。 -使用 ``composer init`` 命令可以帮助你创建它。 +``composer init`` 命令可帮助你创建它。 例如，**composer.json** 可能如下所示:: @@ -62,43 +63,50 @@ 包名称 ============ -``name`` 字段在这里非常重要。包名称通常以 "vendor-name/package-name" 的格式书写，全部小写。以下是一个常见的示例： +``name`` 字段在此很重要。包名称通常以全小写格式 +"vendor-name/package-name" 书写。以下是一个常见的例子： -- ``your-vendor-name``：标识供应商（包的创建者）的名称，例如你的姓名或组织名称。 +- ``your-vendor-name``：标识供应商（包的创建者）的名称， + 例如你的姓名或你的组织。 - ``your-package-name``：你正在创建的包的名称。 -因此，为了使名称唯一以区分其它包，使其与其他包区分开是非常重要的，尤其是在发布时。 +因此，使名称具有唯一性以区别于其他包非常重要。 +在发布时，唯一性尤为重要。 命名空间 ========= -包名称决定了 ``autoload.psr4`` 中的供应商命名空间。 +包名称随后决定了 ``autoload.psr4`` 中的供应商命名空间。 -如果你的包名称是 ``your-vendor/your-package``，那么供应商命名空间必须是 ``YourVendor``。因此，你需要像下面这样编写:: +如果你的包名称是 ``your-vendor/your-package``，则供应商命名空间必须 +是 ``YourVendor``。因此你可以如下编写:: "autoload": { "psr-4": { "YourVendor\\YourPackage\\": "src/" } - } + }, 这个设置指示 Composer 自动加载你的包的源代码。 选择许可证 ================ -如果你对开源许可证不熟悉，请参考 https://choosealicense.com/。许多 PHP 包，包括 CodeIgniter，使用 MIT 许可证。 +如果不熟悉开源许可证，请参阅 https://choosealicense.com/。 +许多 PHP 包，包括 CodeIgniter，都使用 MIT 许可证。 *************************** 准备开发工具 *************************** -有许多工具可以帮助确保代码质量。因此，你应该使用它们。你可以使用 `CodeIgniter DevKit `_ 轻松安装和配置此类工具。 +有许多工具可帮助确保代码质量。因此你应该使用它们。 +你可以通过 `CodeIgniter DevKit `_ +轻松安装和配置这些工具。 安装 DevKit ================= -在你的包目录的根目录中，运行以下命令： +在包目录的根目录下，运行以下命令： .. code-block:: console @@ -106,22 +114,24 @@ composer config prefer-stable true composer require --dev codeigniter4/devkit -DevKit 安装了各种 Composer 包，帮助你进行开发，并在 **vendor/codeigniter4/devkit/src/Template** 中为它们安装了模板。将其中的文件复制到你的项目根目录，并根据你的需求进行编辑。 +DevKit 会安装各种有助于开发的 Composer 包，并在 **vendor/codeigniter4/devkit/src/Template** 中为它们安装模板。将其中的文件复制到项目根目录，并根据需要进行编辑。 -配置 Coding Standards Fixer +配置编码标准修复工具 ================================== -DevKit 提供了基于 `PHP-CS-Fixer `_ 的 `CodeIgniter Coding Standard `_ 的 Coding Standards Fixer。 +DevKit 提供了基于 `PHP-CS-Fixer `_ +的 `CodeIgniter 编码标准 `_ 修复工具。 -将 **vendor/codeigniter4/devkit/src/Template/.php-cs-fixer.dist.php** 复制到你的项目根目录。 +将 **vendor/codeigniter4/devkit/src/Template/.php-cs-fixer.dist.php** 复制到 +项目根目录。 -为缓存文件创建 **build** 文件夹:: +为缓存文件创建 **build** 目录:: your-package-name/ ├── .php-cs-fixer.dist.php ├── build/ -打开你的编辑器中的 **.php-cs-fixer.dist.php** 文件，并修复文件夹路径:: +在编辑器中打开 **.php-cs-fixer.dist.php**，并修正文件夹路径:: --- a/.php-cs-fixer.dist.php +++ b/.php-cs-fixer.dist.php @@ -135,13 +145,14 @@ DevKit 提供了基于 `PHP-CS-Fixer exclude([ -完成后，你可以运行 Coding Standards Fixer： +就是这样。现在你可以运行编码标准修复工具： .. code-block:: console vendor/bin/php-cs-fixer fix --ansi --verbose --diff -如果你在 **composer.json** 中添加了 ``scripts.cs-fix``，则可以使用 ``composer cs-fix`` 命令运行它:: +如果在 **composer.json** 中添加 ``scripts.cs-fix``，你就可以用 +``composer cs-fix`` 命令运行它:: { // ... @@ -158,20 +169,24 @@ DevKit 提供了基于 `PHP-CS-Fixer `。 +如果需要在 **app/Config** 目录中覆盖或添加已知配置， +可以使用 :ref:`隐式注册器 `。 ********** -参考资料 +参考 ********** -我们已经发布了一些官方包。你可以在创建自己的包时使用这些包作为参考： +我们已发布了一些官方包。在创建自己的包时， +你可以将这些包作为参考： - https://github.com/codeigniter4/shield - https://github.com/codeigniter4/settings diff --git a/source/extending/contributing.rst b/source/extending/contributing.rst index 642e541ae..168e97668 100644 --- a/source/extending/contributing.rst +++ b/source/extending/contributing.rst @@ -2,6 +2,6 @@ 为 CodeIgniter 做贡献 ########################### -CodeIgniter 是一个社区驱动的项目，接受来自社区的代码和文档贡献。这些贡献是以 Issue 或 `Pull Request `_ 的形式在 GitHub 上的 `CodeIgniter4 仓库 `_ 提出的。 +CodeIgniter 是一个由社区驱动的项目，接受社区贡献的代码和文档。这些贡献以 GitHub 上的 `CodeIgniter4 仓库 `_ 的 Issues 或 `Pull Requests `_ 形式提交。 -如果你想贡献，请参阅我们代码仓库的 `为 CodeIgniter4 做贡献 `_ 部分。 +如果你希望做出贡献，请参阅我们代码仓库中的 `为 CodeIgniter4 做贡献 `_ 部分。 diff --git a/source/extending/core_classes.rst b/source/extending/core_classes.rst index e519d07fe..4de021591 100755 --- a/source/extending/core_classes.rst +++ b/source/extending/core_classes.rst @@ -2,11 +2,11 @@ 创建核心系统类 **************************** -每次 CodeIgniter 运行时,都会自动初始化几个基本类作为核心框架的一部分。但是,可以用你自己的版本替换任何核心系统类,或者只是扩展核心版本。 +每次 CodeIgniter 运行时，都会自动加载作为核心框架一部分的基础类。你可以用自己的类替换这些核心类，也可以继承并扩展它们。 -**大多数用户都不需要这样做,但对于那些想要显着改变 CodeIgniter 核心的人来说,替换或扩展它们的选项确实存在。** +**大多数情况下，用户无需进行此类操作。但如果你需要深度定制框架行为，CodeIgniter 也支持对核心类的替换或扩展。** -.. important:: 与核心系统类打交道有很多影响,所以在尝试之前,请确保你知道你在做什么。 +.. important:: 操作核心系统类会产生很多影响，因此在尝试之前，请确保你清楚自己在做什么。 .. contents:: :local: @@ -15,7 +15,7 @@ 系统类列表 ================= -以下是每次 CodeIgniter 运行时都会调用的核心系统类列表: +以下是每次 CodeIgniter 运行时都会调用的核心系统类列表： * ``CodeIgniter\Autoloader\Autoloader`` * ``CodeIgniter\Autoloader\FileLocator`` @@ -35,10 +35,10 @@ * ``CodeIgniter\Debug\Timer`` * ``CodeIgniter\Events\Events`` * ``CodeIgniter\Filters\Filters`` -* ``CodeIgniter\HTTP\CLIRequest`` (如果仅从命令行启动) +* ``CodeIgniter\HTTP\CLIRequest`` (仅在命令行中启动时) * ``CodeIgniter\HTTP\ContentSecurityPolicy`` * ``CodeIgniter\HTTP\Header`` -* ``CodeIgniter\HTTP\IncomingRequest`` (如果通过 HTTP 启动) +* ``CodeIgniter\HTTP\IncomingRequest`` (仅在通过 HTTP 启动时) * ``CodeIgniter\HTTP\Message`` * ``CodeIgniter\HTTP\OutgoingRequest`` * ``CodeIgniter\HTTP\Request`` @@ -46,7 +46,7 @@ * ``CodeIgniter\HTTP\SiteURI`` * ``CodeIgniter\HTTP\SiteURIFactory`` * ``CodeIgniter\HTTP\URI`` -* ``CodeIgniter\HTTP\UserAgent`` (如果通过 HTTP 启动) +* ``CodeIgniter\HTTP\UserAgent`` (仅在通过 HTTP 启动时) * ``CodeIgniter\Log\Logger`` * ``CodeIgniter\Log\Handlers\BaseHandler`` * ``CodeIgniter\Log\Handlers\FileHandler`` @@ -58,39 +58,39 @@ 替换核心类 ====================== -要使用自己的系统类代替默认类,请确保: +要使用你自己的系统类而不是默认类，请确保： -1. :doc:`自动加载器 <../concepts/autoloader>` 可以找到你的类, -2. 你的新类实现了适当的接口, -3. 并修改适当的 :doc:`服务 <../concepts/services>` 来加载你的类以替换核心类。 + 1. :doc:`自动加载器 <../concepts/autoloader>` 可以找到你的类， + 2. 你的新类实现了适当的接口， + 3. 并修改相应的 :doc:`服务 <../concepts/services>` 以加载你的类来替代核心类。 创建你的类 ------------------- -例如,如果你有一个新的 ``App\Libraries\RouteCollection`` 类,想用它代替核心系统类,你会这样创建你的类: +例如，如果你有一个新的 ``App\Libraries\RouteCollection`` 类，想用它来替代核心系统类，你可以这样创建你的类： .. literalinclude:: core_classes/001.php 添加服务 ------------------ -然后你需要在 **app/Config/Services.php** 中添加 ``routes`` 服务来加载你的类: +然后在 **app/Config/Services.php** 中添加 ``routes`` 服务来加载你的类： .. literalinclude:: core_classes/002.php 扩展核心类 ====================== -如果你只需要向现有的库中添加一些功能 - 可能是一两个方法 - 那么重新创建整个库就有些过度了。在这种情况下，更好的做法是简单地扩展这个类。扩展类与 `替换核心类`_ 几乎相同，只有一个例外： +如果只需要向现有库添加一些功能——比如增加一两个方法——那么完全重新创建整个库就过于复杂了。在这种情况下，最好只是简单地扩展该类。扩展类与 `替换核心类`_ 几乎完全相同，只有一个例外： * 类声明必须扩展父类。 -例如,要扩展原生的 ``RouteCollection`` 类,你需要用以下方式声明你的类: +例如，要扩展原生的 ``RouteCollection`` 类，你可以这样声明你的类： .. literalinclude:: core_classes/003.php -如果你的类中需要使用构造函数,请确保扩展父类构造函数: +如果你需要在类中使用构造函数，请确保扩展父类构造函数： .. literalinclude:: core_classes/004.php -**提示:** 你类中与父类方法同名的任何函数都会代替原生的方法(这被称为“方法重载”)。这允许你大幅改变 CodeIgniter 核心。 +**提示：** 在子类中定义与父类同名的方法会覆盖父类方法，这一机制称为“方法重写”，可用于自定义 CodeIgniter 核心类的行为。 diff --git a/source/extending/events.rst b/source/extending/events.rst index d0c0119fe..f5f01c3e6 100644 --- a/source/extending/events.rst +++ b/source/extending/events.rst @@ -1,9 +1,9 @@ 事件 ##################################### -CodeIgniter 的事件功能提供了一种无需修改核心文件即可介入和修改框架内部工作机制的方式。当 CodeIgniter 运行时，它遵循特定的执行流程。然而，有时你可能希望在执行流程的特定阶段触发某些操作。例如，你可能想在控制器加载之前或之后立即运行一个脚本，或者在某个其他位置触发你自己的脚本。 +CodeIgniter 的事件（Events）功能提供了一种在不修改核心文件的情况下，介入并修改框架内部工作流程的方法。当 CodeIgniter 运行时，它遵循一个特定的执行流程。然而，你可能希望在执行流程的特定阶段执行某些操作。例如，你可能希望在控制器加载前或加载后立即运行一个脚本，或者希望在其他某个位置触发你自己的脚本。 -事件基于*发布/订阅*模式工作，在脚本执行期间的某个时刻触发一个事件。其他脚本可以通过向 Events 类注册来"订阅"该事件，以告知框架当该事件触发时它们希望执行某个操作。 +事件基于 *发布/订阅* 模式工作，即在脚本执行过程中的某个时刻触发一个事件。其他脚本可以通过向 Events 类注册来“订阅”该事件，从而告知系统，当该事件被触发时，它们希望执行某个操作。 .. contents:: :local: @@ -17,46 +17,46 @@ CodeIgniter 的事件功能提供了一种无需修改核心文件即可介入 定义事件 ================= -大多数事件定义在 **app/Config/Events.php** 文件中。你可以使用 ``Events`` 类的 ``on()`` 方法为事件订阅一个操作。第一个参数是要订阅的事件名称，第二个参数是当事件触发时要运行的可调用对象： +大多数事件在 **app/Config/Events.php** 文件中定义。你可以使用 ``Events`` 类的 ``on()`` 方法，将一个操作订阅到一个事件。第一个参数是要订阅的事件名称，第二个参数是当该事件被触发时将要运行的可调用对象（callable）： .. literalinclude:: events/001.php -在这个例子中，每当 ``pre_system`` 事件被执行时，就会创建 ``MyClass`` 的实例并运行 ``myFunction()`` 方法。注意第二个参数可以是 PHP 识别的*任何*形式的`可调用对象 `_： +在这个例子中，每当 ``pre_system`` 事件被执行时，就会创建 ``MyClass`` 的实例并运行 ``myFunction()`` 方法。注意第二个参数可以是 PHP 识别的*任何*形式的`可调用对象 `_： .. literalinclude:: events/002.php 设置优先级 ------------------ -由于多个方法可以订阅同一个事件，你需要一种方式来定义这些方法的调用顺序。你可以通过向 ``on()`` 方法的第三个参数传递优先级值来实现。数值越小优先级越高执行越早，1 为最高优先级，没有最低值限制： +由于多个方法可以订阅同一个事件，你需要一种方式来定义这些方法的调用顺序。你可以通过将优先级数值作为 ``on()`` 方法的第三个参数来实现。数值越小，优先级越高，执行越早，其中值为 1 的优先级最高，而较低的数值则没有限制： .. literalinclude:: events/003.php 具有相同优先级的订阅者将按照它们被定义的顺序执行。 -自 v4.2.0 起，定义了三个类常量供你使用，这些常量设置了有用的数值范围。虽然不强制使用，但它们有助于提高可读性： +自 v4.2.0 版本起，定义了三个类常量供你使用，它们为这些数值设置了一些有用的范围。虽然你不是必须使用这些常量，但你可能会发现它们有助于提高代码的可读性： .. literalinclude:: events/004.php -.. important:: 常量 ``EVENT_PRIORITY_LOW``、``EVENT_PRIORITY_NORMAL`` 和 ``EVENT_PRIORITY_HIGH`` 已在 v4.6.0 中移除。 +.. important:: ``EVENT_PRIORITY_LOW``、``EVENT_PRIORITY_NORMAL`` 和 ``EVENT_PRIORITY_HIGH`` 这三个常量已在 v4.6.0 版本中移除。 -排序完成后，所有订阅者将按顺序执行。如果任何订阅者返回布尔值 false，则订阅者的执行将停止。 +排序后，所有订阅者将按顺序执行。如果任何一个订阅者返回了布尔值 false，则订阅者的执行将会停止。 发布自定义事件 ========================== -Events 类库也让你可以轻松在自己的代码中创建事件。要使用此功能，只需在 **Events** 类上调用 ``trigger()`` 方法并指定事件名称： +Events 库也使得在你自己的代码中创建事件变得非常简单。要使用此功能，你只需在 **Events** 类上调用 ``trigger()`` 方法，并传入事件的名称即可： .. literalinclude:: events/005.php -你可以通过添加额外参数将任意数量的参数传递给订阅者。订阅者将按照定义顺序接收这些参数： +你可以通过添加额外的参数，向订阅者传递任意数量的参数。订阅者将按照定义的顺序接收这些参数： .. literalinclude:: events/006.php 模拟事件 ================= -在测试期间，你可能不希望实际触发事件，因为每天发送数百封邮件既缓慢又适得其反。你可以使用 ``simulate()`` 方法让 Events 类仅模拟运行事件。当设置为 **true** 时，所有事件都将在触发方法中被跳过，其他操作仍会正常进行。 +在测试过程中，你可能不希望事件实际触发，因为每天发送数百封电子邮件既耗时又适得其反。你可以通过 ``simulate()`` 方法告诉 Events 类仅模拟事件的运行。当参数为 **true** 时，所有事件都将在触发方法中被跳过。不过，其他所有功能仍会正常工作。 .. literalinclude:: events/007.php @@ -72,18 +72,18 @@ Events 类库也让你可以轻松在自己的代码中创建事件。要使用 Web 应用 ------------ -以下是 Web 应用程序中由 **public/index.php** 调用的可用事件点列表： +以下是通过 **public/index.php** 调用的 Web 应用程序可用的事件点列表： -* **pre_system** 在系统执行的早期被调用。此时 URI、Request 和 Response 已实例化，但尚未进行页面缓存检查、路由和"before"控制器过滤器的执行。 -* **post_controller_constructor** 在控制器实例化后立即调用，但在任何方法调用之前。 -* **post_system** 在最终渲染页面发送到浏览器之前调用，在系统执行结束时，在"after"控制器过滤器执行之后。 +* **pre_system** 在系统执行早期调用。此时 URI、Request 和 Response 已被实例化，但页面缓存检查、路由以及“before”控制器过滤器的执行尚未发生。 +* **post_controller_constructor** 在你的控制器实例化后立即调用，但在任何方法调用发生之前。 +* **post_system** 在最终渲染的页面被发送到浏览器之前调用，位于系统执行的末尾，在“after”控制器过滤器执行之后。 .. _event-points-for-cli-apps: CLI 应用 ------------ -以下是针对 :doc:`../cli/spark_commands` 的可用事件点列表： +以下是 :doc:`../cli/spark_commands` 可用的事件点列表： * **pre_command** 在命令代码执行之前立即调用。 * **post_command** 在命令代码执行之后立即调用。 @@ -91,8 +91,8 @@ CLI 应用 其他 ------ -以下是各库可用的通用事件点列表： +以下是各个库可用的事件点列表： -* **email** 当 ``CodeIgniter\Email\Email`` 成功发送邮件后调用。接收 ``Email`` 类的属性数组作为参数。 -* **DBQuery** 在数据库查询（无论成功与否）之后调用。接收 ``Query`` 对象。 -* **migrate** 在成功调用 ``latest()`` 或 ``regress()`` 迁移方法后调用。接收 ``MigrationRunner`` 的当前属性以及方法名称。 +* **email** 从 ``CodeIgniter\Email\Email`` 成功发送电子邮件后调用。接收一个包含 ``Email`` 类属性的数组作为参数。 +* **DBQuery** 在数据库查询之后（无论成功与否）调用。接收 ``Query`` 对象。 +* **migrate** 在成功调用 ``latest()`` 或 ``regress()`` 进行迁移后调用。接收 ``MigrationRunner`` 的当前属性以及方法的名称。 diff --git a/source/extending/index.rst b/source/extending/index.rst index e5b9ebafe..533e63585 100644 --- a/source/extending/index.rst +++ b/source/extending/index.rst @@ -2,7 +2,7 @@ 扩展 CodeIgniter ##################### -扩展或基于 CodeIgniter 4 构建非常容易。 +CodeIgniter 4 被设计为易于扩展，也适合在其基础上构建定制化的应用或框架。 .. toctree:: :titlesonly: diff --git a/source/general/ajax.rst b/source/general/ajax.rst index bda459457..7e6c0b36c 100644 --- a/source/general/ajax.rst +++ b/source/general/ajax.rst @@ -2,64 +2,64 @@ AJAX 请求 ############## -IncomingRequest::isAJAX() 方法使用 X-Requested-With 头来定义请求是否是 XHR 还是普通的。然而,最新的 JavaScript 实现(即 fetch)在发送请求时不再发送此头,因此 IncomingRequest::isAJAX() 的使用变得不太可靠,因为没有此头就无法定义请求是否是 XHR。 +``IncomingRequest::isAJAX()`` 方法使用 ``X-Requested-With`` 请求头来判断请求是 XHR 还是普通请求。然而，最新的 JavaScript 实现（例如 fetch）不再随请求发送此请求头，因此 ``IncomingRequest::isAJAX()`` 的使用变得不太可靠，因为如果没有此请求头，就无法确定请求是否为 XHR。 -为了解决这个问题,最有效的解决方案(到目前为止)是手动定义请求头,强制向服务器发送信息,然后服务器将能够识别请求是 XHR。 +为了解决这个问题，目前最有效的解决方案是手动定义请求头，强制将信息发送到服务器，服务器随后就能识别出该请求是 XHR。 -下面是如何在 Fetch API 和其他 JavaScript 库中强制发送 X-Requested-With 头。 +以下是强制在 Fetch API 和其他 JavaScript 库中发送 ``X-Requested-With`` 请求头的方法。 .. contents:: - :local: - :depth: 2 + :local: + :depth: 2 Fetch API ========= .. code-block:: javascript - fetch(url, { - method: "POST", - headers: { - "Content-Type": "application/json", - "X-Requested-With": "XMLHttpRequest" - } - }); + fetch(url, { + method: "POST", + headers: { + "Content-Type": "application/json", + "X-Requested-With": "XMLHttpRequest" + } + }); jQuery ====== -对于像 jQuery 这样的库,不必明确发送此头,因为根据官方文档,所有 $.ajax() 请求都是标准头。但如果你仍要强制发送以防万一,只需如下所示: +对于 jQuery 等库，无需显式发送此请求头，因为根据 `官方文档 `_，它是所有 ``$.ajax()`` 请求的标准请求头。但如果你仍想强制发送以降低风险，只需按如下方式操作： .. code-block:: javascript - $.ajax({ - url: "your url", - headers: {'X-Requested-With': 'XMLHttpRequest'} - }); + $.ajax({ + url: "your url", + headers: {'X-Requested-With': 'XMLHttpRequest'} + }); VueJS ===== -在 VueJS 中,只要你使用 Axios 进行这种请求,就需要将以下代码添加到 created 函数中。 +在 VueJS 中，只要你使用 Axios 处理此类请求，只需将以下代码添加到 ``created`` 函数中即可。 .. code-block:: javascript - axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest'; + axios.defaults.headers.common['X-Requested-With'] = 'XMLHttpRequest'; React ===== .. code-block:: javascript - axios.get("your url", {headers: {'Content-Type': 'application/json'}}) + axios.get("your url", {headers: {'Content-Type': 'application/json'}}) htmx ==== -你可以使用 `ajax-header `_ 扩展。 +可以使用 `ajax-header `_ 扩展。 .. code-block:: html - - ... - + + ... + ` 和 - :ref:`Factories `。 + 详情请参阅 :ref:`配置 ` 和 + :ref:`工厂 `。 - ``config()`` 在内部使用 ``Factories::config()``。 + ``config()`` 内部使用 ``Factories::config()``。 有关第一个参数 ``$name`` 的详细信息，请参阅 :ref:`factories-loading-class`。 .. php:function:: cookie(string $name[, string $value = ''[, array $options = []]]) @@ -51,135 +53,152 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 :returns: ``Cookie`` 实例 :throws: ``CookieException`` - 创建新的 Cookie 实例的更简单方法。 + 创建新 Cookie 实例的更简单方式。 .. php:function:: cookies([array $cookies = [][, bool $getGlobal = true]]) - :param array $cookies: 如果 ``getGlobal`` 为 ``false``,则传入 ``CookieStore`` 构造函数 - :param bool $getGlobal: 如果为 ``false``,创建 ``CookieStore`` 的新实例 + :param array $cookies: 如果 ``getGlobal`` 为 ``false``，此参数将传递给 ``CookieStore`` 的构造函数。 + :param bool $getGlobal: 如果为 ``false``，则创建一个新的 ``CookieStore`` 实例。 :rtype: ``CookieStore`` - :returns: 保存在当前 ``Response`` 中的 ``CookieStore`` 实例,或新的 ``CookieStore`` 实例 + :returns: 当前 ``Response`` 中保存的 ``CookieStore`` 实例，或一个新的 ``CookieStore`` 实例。 - 获取 ``Response`` 中保存的全局 ``CookieStore`` 实例。 + 获取 ``Response`` 保存的全局 ``CookieStore`` 实例。 .. php:function:: env($key[, $default = null]) :param string $key: 要检索的环境变量名称 - :param mixed $default: 如果找不到值,返回的默认值 - :returns: 环境变量、默认值或 null + :param mixed $default: 如果未找到值时返回的默认值。 + :returns: 环境变量、默认值或 null。 :rtype: mixed - 用于检索之前设置到环境中的值,如果找不到则返回默认值。会将布尔值格式化为实际的布尔值,而不是字符串表示。 + 用于检索先前设置到环境中的值， + 或在未找到时返回默认值。会将布尔值格式化为实际的布尔值， + 而不是字符串表示形式。 - 结合 **.env** 文件使用时特别有用,可设置特定于环境本身的值,如数据库设置、API 密钥等。 + 当与 **.env** 文件结合使用时特别有用，用于设置 + 特定于环境本身的值，如数据库 + 设置、API 密钥等。 .. php:function:: esc($data[, $context = 'html'[, $encoding]]) - :param string|array $data: 要转义的信息 - :param string $context: 转义上下文。默认为 'html' - :param string $encoding: 字符串的字符编码 - :returns: 转义后的数据 + :param string|array $data: 要转义的信息。 + :param string $context: 转义上下文。默认为 'html'。 + :param string $encoding: 字符串的字符编码。 + :returns: 转义后的数据。 :rtype: mixed - 为了帮助防止 XSS 攻击,对要包含在网页中的数据进行转义。这使用 Laminas Escaper 库来实际过滤数据。 + 转义要包含在网页中的数据，以帮助防止 XSS 攻击。 + 这使用 Laminas Escaper 库来处理实际的数据过滤。 - 如果 $data 是字符串,则简单转义并返回它。如果 $data 是数组,则遍历它,转义每个键/值对的 'value'。 + 如果 $data 是字符串，则简单地转义并返回它。 + 如果 $data 是数组，则循环遍历它，转义每个键/值对的 '值'。 - 有效的 context 值: ``html``, ``js``, ``css``, ``url``, ``attr``, ``raw`` + 有效的上下文值：``html``、``js``、``css``、``url``、``attr``、``raw`` .. php:function:: helper($filename) - :param string|array $filename: 要加载的辅助器文件名,或文件名数组 + :param string|array $filename: 要加载的辅助函数文件名，或名称数组。 - 加载辅助器文件。 + 加载辅助函数文件。 - 有关完整详细信息,请参阅 :doc:`辅助器 ` 页面。 + 详情请参阅 :doc:`辅助函数` 页面。 .. php:function:: lang($line[, $args[, $locale]]) - :param string $line: 需要检索的语言文件名和文本 key。 + :param string $line: 语言文件名和要检索的文本键。 :param array $args: 用于替换占位符的数据数组。 - :param string $locale: 指定使用当前区域设置之外的区域设置。 + :param string $locale: 指定要使用的不同区域设置，而不是当前区域设置。 :returns: 语言文件中的文本 :rtype: list|string 从语言文件中检索文本。 - 更多信息，请参见 :ref:`language-localization`。 + 详情请参阅 :ref:`language-localization`。 .. php:function:: model($name[, $getShared = true[, &$conn = null]]) - :param string $name: 模型类名 - :param boolean $getShared: 是否返回共享实例 - :param ConnectionInterface|null $conn: 数据库连接 + :param string $name: 模型类名。 + :param boolean $getShared: 是否返回共享实例。 + :param ConnectionInterface|null $conn: 数据库连接。 :returns: 模型实例 :rtype: object - 获取模型实例的更简单方法。 + 获取模型实例的更简单方式。 - ``model()`` 在内部使用 ``Factories::models()``。有关第一个参数 ``$name`` 的详细信息,请参阅 :ref:`factories-loading-class`。 + ``model()`` 内部使用 ``Factories::models()``。 + 有关第一个参数 ``$name`` 的详细信息，请参阅 :ref:`factories-loading-class`。 另请参阅 :ref:`使用 CodeIgniter 的模型 `。 .. php:function:: old($key[, $default = null,[, $escape = 'html']]) - :param string $key: 要检查的旧表单数据的名称 - :param string|null $default: 如果 $key 不存在,返回的默认值 - :param false|string $escape: `转义 <#esc>`_ 上下文或设置 false 禁用它 - :returns: 定义键的值或默认值 + :param string $key: 要检查的旧表单数据名称。 + :param string|null $default: 如果 $key 不存在时返回的默认值。 + :param false|string $escape: `转义 <#esc>`_ 上下文或 false 以禁用它。 + :returns: 定义键的值，或默认值。 :rtype: array|string|null 提供了一种简单的方式来访问提交表单后的“旧输入数据”。 - 例子: + 示例： .. literalinclude:: common_functions/002.php -.. note:: 如果你在 :doc:`表单辅助函数 ` 中使用了 :php:func:`set_value()`、:php:func:`set_select()`、:php:func:`set_checkbox()` 和 :php:func:`set_radio()` 函数，这个功能已经内置了。只有在不使用表单辅助函数时才需要使用此函数。 +.. note:: 如果你正在使用 :php:func:`set_value()`、:php:func:`set_select()`、 + :php:func:`set_checkbox()` 和 :php:func:`set_radio()` 函数（位于 + :doc:`表单辅助函数 ` 中），此功能已内置。只有 + 在不使用表单辅助函数时才需要使用此函数。 .. php:function:: session([$key]) - :param string $key: 要检查的会话项目名称 - :returns: 如果没有 $key,则是 Session 对象的实例;如果有 $key,则是会话中为 $key 找到的值,如果找不到则为 null + :param string $key: 要检查的会话项名称。 + :returns: 如果没有提供 $key，则返回 Session 对象实例；如果提供了 $key，则返回会话中 $key 对应的值，或 null。 :rtype: mixed - 提供了方便访问 session 类和检索存储值的方法。有关更多信息,请参阅 :doc:`会话 ` 页面。 + 提供了一种便捷的方式来访问会话类并检索存储的值。详情请参阅 :doc:`会话 ` 页面。 .. php:function:: timer([$name]) - :param string $name: 基准点的名称 + :param string $name: 基准点的名称。 :returns: Timer 实例 :rtype: CodeIgniter\Debug\Timer - 方便地快速访问 Timer 类的方法。你可以将基准点的名称作为唯一参数传递。这将从此点开始计时,或如果已运行具有此名称的计时器,则停止计时。 + 一种便捷方法，可快速访问 Timer 类。你可以将基准点的名称作为唯一参数传入。 + 这将从此点开始计时，或者如果已存在同名计时器则停止计时。 - 例子: + 示例： .. literalinclude:: common_functions/003.php .. php:function:: view($name[, $data[, $options]]) - :param string $name: 要加载的文件的名称 - :param array $data: 要在视图中可用的键/值对数组 - :param array $options: 将传递给渲染类的选项数组 - :returns: 来自视图的输出 + :param string $name: 要加载的文件名 + :param array $data: 键/值对数组，使其在视图内可用。 + :param array $options: 将传递给渲染类的选项数组。 + :returns: 视图的输出。 :rtype: string - 获取当前的 RendererInterface 兼容类（默认为 :doc:`视图 <../outgoing/view_renderer>` 类），并告诉它渲染指定的视图。这仅仅提供了一个方便的方法，可以在控制器、库以及在路由闭包中使用。 + 获取当前与 RendererInterface 兼容的类 + （默认为 :doc:`视图 <../outgoing/view_renderer>` 类） + 并告诉它渲染指定的视图。仅提供 + 一种便捷方法，可在控制器、 + 库和路由闭包中使用。 - 当前,这些选项可用于 ``$options`` 数组中: + 目前，``$options`` 数组中可使用以下选项： - - ``saveData`` 指定数据在同一请求内对 ``view()`` 的多次调用之间持久化。如果不想持久化数据,请指定 false。 - - ``cache`` 指定缓存视图的秒数。有关详细信息,请参阅 :ref:`caching-views`。 - - ``debug`` 可以设置为 false 以禁用为 :ref:`Debug 工具栏 ` 添加调试代码。 + - ``saveData`` 指定数据将在同一请求内的多次 ``view()`` 调用间保持。如果你不希望保持，请指定 false。 + - ``cache`` 指定缓存视图的秒数。详情请参阅 :ref:`caching-views`。 + - ``debug`` 可设置为 false 以禁用 :ref:`调试工具栏 ` 的调试代码添加。 - ``$option`` 数组主要是为了方便与 Twig 等库的第三方集成。 + ``$option`` 数组主要用于促进与 + Twig 等库的第三方集成。 - 例子: + 示例： .. literalinclude:: common_functions/004.php - 有关更多详细信息,请参阅 :doc:`视图 <../outgoing/views>` 和 :doc:`../outgoing/view_renderer` 页面。 + 详情请参阅 :doc:`视图 <../outgoing/views>` 和 + :doc:`../outgoing/view_renderer` 页面。 .. php:function:: view_cell($library[, $params = null[, $ttl = 0[, $cacheName = null]]]) @@ -187,145 +206,159 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 :param null $params: :param integer $ttl: :param string|null $cacheName: - :returns: 视图单元用于在视图中插入由其他类管理的 HTML 块。 + :returns: 视图单元用于在视图中插入由其他类管理的 HTML 片段。 :rtype: string - 更多详情请参考 :doc:`视图单元 ` 页面。 + 详情请参阅 :doc:`视图单元 ` 页面。 -杂项函数 +其他函数 ======================= .. php:function:: app_timezone() - :returns: 应用程序设置要显示日期的时区 + :returns: 应用程序设置的显示日期的时区。 :rtype: string - 返回应用程序设置要显示日期的时区。 + 返回应用程序设置的显示日期的时区。 .. php:function:: csp_script_nonce() - :returns: 脚本标签的 CSP 随机数属性 + :returns: script 标签的 CSP nonce 属性。 :rtype: string - 返回脚本标签的随机数属性。例如:``nonce="Eskdikejidojdk978Ad8jf"``。请参阅 :ref:`內容安全策略 `。 + 返回 script 标签的 nonce 属性。例如：``nonce="Eskdikejidojdk978Ad8jf"``。 + 请参阅 :ref:`内容安全策略 `。 .. php:function:: csp_style_nonce() - :returns: 样式标签的 CSP 随机数属性 + :returns: style 标签的 CSP nonce 属性。 :rtype: string - 返回样式标签的随机数属性。例如:``nonce="Eskdikejidojdk978Ad8jf"``。请参阅 :ref:`內容安全策略 `。 + 返回 style 标签的 nonce 属性。例如：``nonce="Eskdikejidojdk978Ad8jf"``。 + 请参阅 :ref:`内容安全策略 `。 .. php:function:: csrf_token() - :returns: 当前 CSRF 令牌的名称 + :returns: 当前 CSRF 令牌的名称。 :rtype: string 返回当前 CSRF 令牌的名称。 .. php:function:: csrf_header() - :returns: 当前 CSRF 令牌的标头名称 + :returns: 当前 CSRF 令牌的头部名称。 :rtype: string - 当前 CSRF 令牌的标头名称。 + 当前 CSRF 令牌的头部名称。 .. php:function:: csrf_hash() - :returns: 当前 CSRF 哈希值 + :returns: 当前 CSRF 哈希值。 :rtype: string 返回当前 CSRF 哈希值。 .. php:function:: csrf_field() - :returns: 包含所有必需 CSRF 信息的隐藏输入的 HTML 字符串 + :returns: 包含所有必需 CSRF 信息的隐藏输入 HTML 字符串。 :rtype: string - 返回包含所有必需 CSRF 信息的隐藏输入:: + 返回一个已插入 CSRF 信息的隐藏输入:: .. php:function:: csrf_meta() - :returns: 包含所有必需 CSRF 信息的 meta 标签的 HTML 字符串 + :returns: 包含所有必需 CSRF 信息的 meta 标签 HTML 字符串。 :rtype: string - 返回包含所有必需 CSRF 信息的 meta 标签:: + 返回一个已插入 CSRF 信息的 meta 标签:: .. php:function:: force_https($duration = 31536000[, $request = null[, $response = null]]) - :param int $duration: 浏览器应将此资源的链接转换为 HTTPS 的秒数 - :param RequestInterface $request: 当前 Request 对象的实例 - :param ResponseInterface $response: 当前 Response 对象的实例 + :param int $duration: 浏览器应将此资源的链接转换为 HTTPS 的秒数。 + :param RequestInterface $request: 当前 Request 对象的实例。 + :param ResponseInterface $response: 当前 Response 对象的实例。 - 检查当前页面是否通过 HTTPS 访问。如果是，则不执行任何操作。如果不是，则将用户重定向回当前 URI，但通过 HTTPS 进行访问。将设置 HTTP 严格传输安全（HTST）头，指示现代浏览器将任何 HTTP 请求自动修改为 HTTPS 请求，持续时间为 ``$duration``。 + 检查页面当前是否通过 HTTPS 访问。如果是，则 + 不会发生任何事情。如果不是，则将用户重定向回当前 URI， + 但通过 HTTPS。将设置 HTTP Strict Transport Security (HTST) 头部，指示 + 现代浏览器在 ``$duration`` 期间自动将任何 HTTP 请求修改为 HTTPS 请求。 - .. note:: 当你将 ``Config\App:$forceGlobalSecureRequests`` 设置为 true 时，也会使用此函数。 + .. note:: 此函数也在你将 + ``Config\App:$forceGlobalSecureRequests`` 设置为 true 时使用。 .. php:function:: function_usable($functionName) :param string $functionName: 要检查的函数 - :returns: 如果函数存在且可安全调用则为 true,否则为 false + :returns: 如果函数存在且可以安全调用则返回 true，否则返回 false。 :rtype: bool .. php:function:: is_cli() - :returns: 如果脚本是从命令行执行的则为 true,否则为 false + :returns: 如果脚本从命令行执行则返回 true，否则返回 false。 :rtype: bool .. php:function:: is_really_writable($file) - :param string $file: 被检查的文件名 - :returns: 如果可以写入文件则为 true,否则为 false + :param string $file: 要检查的文件名。 + :returns: 如果可以写入文件则返回 true，否则返回 false。 :rtype: bool .. php:function:: is_windows([$mock = null]) - :param bool|null $mock: 如果给出且为布尔值,则将其用作返回值 + :param bool|null $mock: 如果给定且为布尔值，则将用作返回值。 :rtype: bool - 检测平台是否在 Windows 下运行。 + 检测平台是否在 Windows 上运行。 - .. note:: 提供给 $mock 的布尔值将在后续调用中持久化。要重置此模拟值,用户必须为函数调用显式传递 ``null``。这将刷新函数以使用自动检测。 + .. note:: 提供给 $mock 的布尔值将在后续调用中保持。要重置此 + 模拟值，用户必须在函数调用中显式传递 ``null``。这将 + 刷新函数以使用自动检测。 .. literalinclude:: common_functions/012.php .. php:function:: log_message($level, $message [, $context]) :param string $level: 严重级别 - :param string $message: 要记录的消息 + :param string $message: 要记录的消息。 :param array $context: 应在 $message 中替换的标签及其值的关联数组 :returns: void :rtype: bool - .. note:: 自 v4.5.0 起，返回值被固定为兼容 PSR Log。在以前的版本中，如果日志记录成功则返回 ``true``，如果有问题则返回 ``false``。 + .. note:: 从 v4.5.0 开始，返回值已修复为与 PSR + Log 兼容。在以前的版本中，如果成功记录则返回 ``true``， + 如果记录时出现问题则返回 ``false``。 - 使用 **app/Config/Logger.php** 中定义的日志处理程序记录消息。 + 使用 **app/Config/Logger.php** 中定义的日志处理器记录消息。 - 日志级别可以是以下值之一：``emergency``、``alert``、``critical``、``error``、``warning``、``notice``、``info`` 或 ``debug``。 + 级别可以是以下值之一：``emergency``、``alert``、``critical``、``error``、``warning``、 + ``notice``、``info`` 或 ``debug``。 - 上下文可以用来在消息字符串中替换值。有关完整详细信息,请参阅 :doc:`日志记录信息 ` 页面。 + 上下文可用于替换消息字符串中的值。详情请参阅 + :doc:`日志记录信息 ` 页面。 .. php:function:: redirect(string $route) - :param string $route: 要重定向用户的路由名称或 Controller::method + :param string $route: 要重定向用户的路由名称或 Controller::method。 :rtype: RedirectResponse - 返回 RedirectResponse 实例,可轻松创建重定向。详情请参阅 :ref:`response-redirect`。 + 返回 RedirectResponse 实例，允许你轻松创建重定向。 + 详情请参阅 :ref:`response-redirect`。 .. php:function:: remove_invisible_characters($str[, $urlEncoded = true]) :param string $str: 输入字符串 - :param bool $urlEncoded: 是否也删除 URL 编码字符 - :returns: 经过清理的字符串 + :param bool $urlEncoded: 是否同时移除 URL 编码的字符 + :returns: 清理后的字符串 :rtype: string - 此函数可防止在 ASCII 字符(如 Java\\0script)之间插入空字符。 + 此函数防止在 ASCII 字符之间插入空字符， + 如 Java\\0script。 - 例子: + 示例： .. literalinclude:: common_functions/007.php @@ -333,8 +366,8 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 .. versionadded:: 4.3.0 - :returns: 共享的 Request 对象 - :rtype: IncomingRequest|CLIRequest + :returns: 共享的 Request 对象。 + :rtype: IncomingRequest|CLIRequest 此函数是 ``Services::request()`` 和 ``service('request')`` 的包装器。 @@ -342,8 +375,8 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 .. versionadded:: 4.3.0 - :returns: 共享的 Response 对象 - :rtype: Response + :returns: 共享的 Response 对象。 + :rtype: Response 此函数是 ``Services::response()`` 和 ``service('response')`` 的包装器。 @@ -351,14 +384,17 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 :param string $method: 路由名称或 Controller::method :param int|string ...$params: 要传递给路由的一个或多个参数。最后一个参数允许你设置区域设置。 - :returns: 路由路径(基于 baseURL 的 URI 相对路径) + :returns: 路由路径（相对于 baseURL 的 URI 路径） :rtype: string - .. note:: 此函数要求控制器/方法必须在 **app/Config/Routes.php** 中定义路由。 + .. note:: 此函数要求 controller/method 在 **app/Config/Routes.php** 中定义了路由。 - .. important:: ``route_to()`` 返回一个 *路由* 路径,而不是站点的完整 URI 路径。如果你的 **baseURL** 包含子文件夹,返回值与链接的 URI 并不相同。在这种情况下,请改用 :php:func:`url_to()`。另请参阅 :ref:`urls-url-structure`。 + .. important:: ``route_to()`` 返回的是 *路由* 路径，而不是你网站的完整 URI 路径。 + 如果你的 **baseURL** 包含子目录，则返回值与链接的 URI 不同。 + 在这种情况下，请改用 :php:func:`url_to()`。 + 另请参阅 :ref:`urls-url-structure`。 - 根据 controller::method 组合为你生成路由。将根据提供的参数生成路由。 + 根据控制器::方法组合为你生成路由。如果提供参数，将考虑参数的影响。 .. literalinclude:: common_functions/009.php @@ -366,48 +402,52 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 .. literalinclude:: common_functions/010.php - 从 v4.3.0 开始,当你在路由中使用 ``{locale}`` 时,可以可选地将区域设置值作为最后一个参数指定。 + 从 v4.3.0 开始，当你在路由中使用 ``{locale}`` 时，可以选择将区域设置值作为最后一个参数指定。 .. literalinclude:: common_functions/011.php .. php:function:: service($name[, ...$params]) :param string $name: 要加载的服务名称 - :param mixed $params: 要传递给服务方法的一个或多个参数 - :returns: 指定的服务类的实例 + :param mixed $params: 要传递给服务方法的一个或多个参数。 + :returns: 指定的服务类实例。 :rtype: mixed - 提供对系统中定义的任何 :doc:`服务 <../concepts/services>` 的简单访问。这将始终返回该类的共享实例,因此无论在单次请求期间调用多少次,都只会创建一个类实例。 + 提供对系统中定义的任何 :doc:`服务 <../concepts/services>` 的便捷访问。 + 这将始终返回类的共享实例，因此无论在单个请求期间调用多少次， + 都只会创建一个类实例。 - 例子: + 示例： .. literalinclude:: common_functions/008.php .. php:function:: single_service($name [, ...$params]) :param string $name: 要加载的服务名称 - :param mixed $params: 要传递给服务方法的一个或多个参数 - :returns: 指定的服务类的实例 + :param mixed $params: 要传递给服务方法的一个或多个参数。 + :returns: 指定的服务类实例。 :rtype: mixed - 与上面描述的 **service()** 函数相同,但此函数的所有调用都将返回一个新的类实例,而 **service** 每次都返回相同的实例。 + 与上面描述的 **service()** 函数相同，只是对此函数的 + 所有调用都将返回类的新实例，而 **service** 每次都返回相同的 + 实例。 .. php:function:: slash_item ( $item ) - :param string $item: 配置项目名称 - :returns: 配置项目或如果项目不存在则为 null + :param string $item: 配置项名称 + :returns: 配置项，如果项不存在则返回 null :rtype: string|null - 获取附加斜杠的配置文件项目(如果不为空) + 获取配置文件项并在末尾添加斜杠（如果不为空） .. php:function:: stringify_attributes($attributes [, $js]) :param mixed $attributes: 字符串、键值对数组或对象 - :param boolean $js: 如果值不需要引号(Javascript 风格)则为 true - :returns: 逗号分隔的包含属性键/值对的字符串 + :param boolean $js: 如果值不需要引号（JavaScript 风格）则为 true + :returns: 包含属性键/值对的字符串，以逗号分隔 :rtype: string - 将字符串、数组或属性对象转换为字符串的辅助函数。 + 辅助函数，用于将字符串、数组或对象的属性转换为字符串。 ================ 全局常量 @@ -424,7 +464,7 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 .. php:const:: ROOTPATH - 项目根目录的路径。刚好在 ``APPPATH`` 之上。 + 项目根目录的路径。就在 ``APPPATH`` 上方。 .. php:const:: SYSTEMPATH @@ -432,7 +472,7 @@ CodeIgniter 提供了一些全局定义的函数和变量,在任何时候都可 .. php:const:: FCPATH - 保存前端控制器的目录的路径。 + 包含前端控制器的目录路径。 .. php:const:: WRITEPATH diff --git a/source/general/configuration.rst b/source/general/configuration.rst index fa2d8e401..c127940a7 100755 --- a/source/general/configuration.rst +++ b/source/general/configuration.rst @@ -2,35 +2,36 @@ 配置 ############# -每个框架都使用配置文件来定义许多参数和初始设置。CodeIgniter 配置文件定义了简单的类,其中所需的设置是公共属性。 +每个框架都使用配置文件来定义众多参数和初始设置。CodeIgniter 的配置文件定义了简单的类，其中所需的设置是公共属性。 -与许多其他框架不同,CodeIgniter 的可配置项不包含在单个文件中。相反,每个需要可配置项的类都有一个与使用它的类同名的配置文件。你可以在 **app/Config** 文件夹中找到应用程序配置文件。 +与许多其他框架不同，CodeIgniter 的可配置项并不包含在单个文件中。相反，每个需要可配置项的类都会有一个与其使用的类同名的配置文件。你可以在 **app/Config** 文件夹中找到应用程序的配置文件。 .. contents:: :local: :depth: 2 + 什么是配置类？ ******************************* -配置类用于定义系统默认配置值。系统配置值通常是*静态*的。配置类旨在保留配置应用程序操作方式的设置，而不是响应每个用户的个别设置。 +配置类用于定义系统默认的配置值。系统配置值通常是 *静态的*。配置类旨在保留配置应用程序运行方式的设置，而不是响应每个用户的个人设置。 -不建议在配置类实例化后，在执行期间修改值。换句话说，建议将配置类视为不可变或只读的类。这尤其重要，如果你使用 :ref:`factories-config-caching`。 +不建议在配置类实例化期间设置的值在后续执行过程中进行修改。换句话说，建议将配置类视为不可变或只读类。如果你使用 :ref:`factories-config-caching`，这一点尤为重要。 配置值可以在类文件中硬编码，也可以在实例化时从环境变量中获取。 使用配置文件 -********************************** +******************************** 获取配置对象 ======================= 你可以通过几种不同的方式访问类的配置文件。 -使用 new 关键字 ---------------- +new 关键字 +----------- -使用 ``new`` 关键字创建一个实例: +通过使用 ``new`` 关键字创建实例： .. literalinclude:: configuration/001.php @@ -39,87 +40,85 @@ config() -------- -使用 :php:func:`config()` 函数: +通过使用 :php:func:`config()` 函数： .. literalinclude:: configuration/002.php -如果未提供命名空间，它将首先在 **app/Config** 文件夹中查找文件，如果找不到，则在所有定义的命名空间的 **Config** 文件夹中查找。 - -CodeIgniter 提供的所有配置文件都使用 ``Config`` 命名空间。在你的应用程序中使用这个命名空间将提供最佳性能,因为它确切知道在哪里可以找到这些文件。 +如果没有提供命名空间，它会首先在 **app/Config** 文件夹中查找文件，如果未找到，则在所有已定义命名空间的 **Config** 文件夹中查找。 -你可以通过使用不同的命名空间将配置文件放在任何你想要的文件夹中。这允许你在生产服务器上将配置文件放在一个不可公开访问的文件夹中,同时在开发期间保持其位于 **/app** 下方便访问。 +所有随 CodeIgniter 一起提供的配置文件都使用 ``Config`` 命名空间。在应用程序中使用此命名空间将提供最佳性能，因为它确切知道在哪里找到文件。 -.. note:: 在 v4.4.0 之前，``config()`` 会在有与 shortname 相同的类时，在 **app/Config/** 中查找文件，即使你指定了完全限定的类名，如 ``config(\Acme\Blog\Config\Blog::class)``。在 v4.4.0 中修复了此行为，并返回指定的实例。 +.. note:: 在 v4.4.0 之前，即使你指定了完全限定的类名（如 ``config(\Acme\Blog\Config\Blog::class)``），``config()`` 也会在 **app/Config/** 中查找具有相同短名称的类的文件。此行为已在 v4.4.0 中修复，并返回指定的实例。 获取配置属性 ========================= -所有配置对象属性都是公共的,所以你可以像访问任何其他属性一样访问设置: +所有配置对象属性都是公共的，因此你可以像访问其他任何属性一样访问这些设置： .. literalinclude:: configuration/003.php 创建配置文件 **************************** -当你需要一个新的配置时,首先在所需位置创建一个新文件。默认文件位置(大多数情况下推荐)是 **app/Config**。该类应使用适当的命名空间,并且它应扩展 ``CodeIgniter\Config\BaseConfig`` 以确保它可以接收特定环境的设置。 +当你需要新的配置时，首先在所需位置创建一个新文件。默认文件位置（大多数情况下推荐）是 **app/Config**。 -你可以通过使用不同的命名空间将配置文件放置在任何 **Config** 文件夹中。 +你可以通过使用不同的命名空间将配置文件放在任何 **Config** 文件夹中。 -该类应使用适当的命名空间，并应扩展 ``CodeIgniter\Config\BaseConfig`` 以确保它可以接收特定于环境的设置。 +该类应使用适当的命名空间，并且应继承 ``CodeIgniter\Config\BaseConfig`` 以确保它能够接收特定于环境的设置。 -定义类并用代表你的设置的公共属性填充它: +定义类并用代表你设置的公共属性填充它： .. literalinclude:: configuration/004.php 环境变量 ********************* -今天应用程序设置的最佳实践之一是使用环境变量。原因之一是环境变量可以在不更改任何代码的情况下在部署之间轻松更改。配置在部署之间可能会有很大变化,但代码不会。例如,多个环境(如开发者的本地机器和生产服务器)通常需要针对每个特定设置配置不同的值。 +使用环境变量是当今应用程序设置的最佳实践之一。主要原因是，环境变量可以在不同部署环境之间轻松更改，无需修改任何代码。配置会因部署环境而异，但代码保持不变。例如，开发者的本地机器和生产服务器等不同环境，通常需要为每个特定环境使用不同的配置值。 -环境变量也应该用于任何私人信息,如密码、API 密钥或其他敏感数据。 +环境变量还应该用于任何私密信息，如密码、API 密钥或其他敏感数据。 .. _dotenv-file: Dotenv 文件 =========== -CodeIgniter 通过使用 “dotenv” 文件使设置环境变量变得简单轻松。该术语来源于文件名,文件名以点号开头,然后是 “env”文本。 +CodeIgniter 通过使用 "dotenv" 文件使设置环境变量变得简单无痛。这个术语来自文件名，它在 "env" 文本前以点号开头。 创建 Dotenv 文件 -------------------- -CodeIgniter 期望 **.env** 文件与 **app** 目录一起位于项目的根目录中。 CodeIgniter 中分发了一个位于项目根目录 named 的模板文件 **env** (注意开头没有点号(``.``)?)。 +CodeIgniter 期望 **.env** 文件位于项目根目录中，与 **app** 目录并列。CodeIgniter 分发了一个模板文件，位于项目根目录，名为 **env**（注意开头没有点号（``.``）？）。 -它包含了项目可能会使用的大量变量,并分配了空、虚拟或默认值。你可以通过重命名模板为 **.env** 或复制为名为 **.env** 的副本,将此文件用作应用程序的起点。 +它包含大量你的项目可能使用的变量，这些变量已被分配为空值、虚拟值或默认值。你可以将此文件作为应用程序的起点，方法是将模板重命名为 **.env**，或者复制一份名为 **.env** 的文件。 -.. warning:: 确保 **.env** 文件NOT被你的版本控制系统跟踪。 对于 *git* 来说,这意味着将其添加到 **.gitignore**。 否则可能会导致敏感证书被公开。 +.. warning:: 确保 **.env** 文件未被你的版本控制系统跟踪。对于 *git*，这意味着将其添加到 **.gitignore** 中。如果不这样做，可能会导致敏感凭据暴露给公众。 设置变量 ----------------- -设置以简单的名称/值对的集合存储在 **.env** 文件中,用等号分隔。 +设置在 **.env** 文件中以简单的名称/值对集合形式存储，用等号分隔。 :: S3_BUCKET = dotenv SECRET_KEY = super_secret_key CI_ENVIRONMENT = development -当你的应用程序运行时, **.env** 将自动加载,并将变量放入环境中。如果环境中已经存在一个变量,它将不会被覆盖。 +当你的应用程序运行时，**.env** 将自动加载，变量将被放入环境中。如果环境中已存在变量，则不会被覆盖。 获取变量 ----------------- -加载的环境变量可以使用下列任意一种访问: +加载的环境变量可以通过以下任一方式访问： ``getenv()``、``$_SERVER`` 或 ``$_ENV``。 .. literalinclude:: configuration/005.php -.. warning:: 请注意,来自 **.env** 文件的设置会添加到 ``$_SERVER`` and ``$_ENV`` 中。由此带来的一个副作用是,如果你的 CodeIgniter 应用程序生成一个 ``var_dump($_ENV)`` 或 ``phpinfo()`` (用于调试或其他有效原因) ，或者在 ``development`` 环境中显示了详细的错误报告，**你的安全凭据可能会公开暴露**。 +.. warning:: 注意，你的 **.env** 文件中的设置会被添加到 ``$_SERVER`` 和 ``$_ENV`` 中。作为副作用，这意味着如果你的 CodeIgniter 应用程序（例如）生成 ``var_dump($_ENV)`` 或 ``phpinfo()``（用于调试或其他有效原因），或在 ``development`` 环境中显示详细的错误报告，**你的安全凭据将被公开暴露**。 嵌套变量 ----------------- -为了省去输入,你可以通过在 ``${...}`` 内包装变量名来重用已经在文件中指定的变量: +为了减少输入，你可以通过将变量名包装在 ``${...}`` 中来重用文件中已指定的变量： :: @@ -130,17 +129,17 @@ CodeIgniter 期望 **.env** 文件与 **app** 目录一起位于项目的根目 命名空间变量 -------------------- -有时你会有多个同名变量。系统需要一种方法来确定应使用的正确设置。这通过为变量“命名空间”来解决这个问题。 +有时你会有多个同名的变量。系统需要一种方法来知道正确的设置应该是什么。这个问题通过 "*命名空间*" 变量来解决。 -命名空间变量使用点表示法来限定变量名,以便在合并到环境时它们是唯一的。这是通过在变量名称前面包含区别前缀和点号(.)来完成的。 +命名空间变量使用点符号来限定变量名，使它们在合并到环境变量时保持唯一。这是通过包含一个区分前缀，后跟一个点（.），然后是变量名本身来完成的。 :: - // 非命名空间变量 + // 未命名空间的变量 name = "George" db = my_db - // 命名空间变量 + // 命名空间的变量 address.city = "Berlin" address.country = "Germany" frontend.db = sales @@ -152,7 +151,7 @@ CodeIgniter 期望 **.env** 文件与 **app** 目录一起位于项目的根目 命名空间分隔符 ------------------- -某些环境,例如 Docker、CloudFormation 不允许带点号(``.``)的变量名。在这种情况下,从 v4.1.5 开始,你也可以使用下划线 (``_``) 作为分隔符。 +某些环境（例如 Docker、CloudFormation）不允许变量名包含点号（``.``）。在这种情况下，从 v4.1.5 开始，你也可以使用下划线（``_``）作为分隔符。 :: @@ -165,74 +164,75 @@ CodeIgniter 期望 **.env** 文件与 **app** 目录一起位于项目的根目 配置类和环境变量 *********************************************** -当你实例化一个配置类时,任何 *命名空间* 环境变量都会被考虑合并到配置对象的属性中。 +当你实例化配置类时，任何 *命名空间* 的环境变量都会被考虑合并到配置对象的属性中。 -.. important:: 你无法通过设置环境变量来添加新属性,也不能将标量值改变为数组。请参见 :ref:`env-var-replacements-for-data`。 +.. important:: 你不能通过设置环境变量来添加新属性，也不能将标量值更改为数组。请参阅 :ref:`env-var-replacements-for-data`。 -.. note:: 此功能是在 ``CodeIgniter\Config\BaseConfig`` 类中实现的。因此，它不适用于 **app/Config** 文件夹中的一些文件，这些文件不扩展该类。 +.. note:: 此功能在 ``CodeIgniter\Config\BaseConfig`` 类中实现。因此，对于 **app/Config** 文件夹中不继承该类的少数文件，它将不起作用。 -如果命名空间变量的前缀正好匹配配置类的命名空间,那么设置的尾部(点之后)将被视为配置属性。如果它与现有的配置属性匹配,环境变量的值将替换配置文件中相应的值。如果没有匹配,配置类属性保持不变。在此用法中,前缀必须是类的完整(区分大小写)命名空间。 +如果命名空间变量的前缀与配置类的命名空间完全匹配，则设置的尾部部分（点号之后）将被视为配置属性。如果它与现有的配置属性匹配，环境变量的值将替换配置文件中的相应值。如果没有匹配，配置类属性将保持不变。在此用法中，前缀必须是类的完整（区分大小写）命名空间。 :: Config\App.forceGlobalSecureRequests = true Config\App.CSPEnabled = true -.. note:: 命名空间前缀和属性名均区分大小写。它们必须完全匹配配置类文件中定义的完整命名空间和属性名称。 +.. note:: 命名空间前缀和属性名都是区分大小写的。它们必须与配置类文件中定义的完整命名空间和属性名完全匹配。 -使用仅包含配置类名称的小写版本的 *短前缀* 相同。如果短前缀匹配类名,则 **.env** 中的值将替换配置文件中的值。 +对于 *短前缀*（即仅使用配置类名的小写版本的命名空间）也是如此。如果短前缀与类名匹配，**.env** 中的值将替换配置文件中的值。 :: app.forceGlobalSecureRequests = true app.CSPEnabled = true -从 v4.1.5 开始,你也可以使用下划线:: +从 v4.1.5 开始，你也可以使用下划线编写： + +:: app_forceGlobalSecureRequests = true app_CSPEnabled = true -.. note:: 使用 *短前缀* 时,属性名称仍必须完全匹配类中定义的名称。 +.. note:: 使用 *短前缀* 时，属性名仍必须与类中定义的名称完全匹配。 .. _env-var-replacements-for-data: -作为数据的环境变量 +环境变量作为数据的替换 ============================================== -务必要始终记住，你的 **.env** 文件中的环境变量 **只是现有标量值的替代**。 +始终牢记，**.env** 中包含的环境变量 **仅用于替换现有的标量值**。 -简单来说，你只能通过在 **.env** 文件中设置来更改 Config 类中存在的属性的标量值。 +简单来说，你只能通过在 **.env** 中设置来更改 Config 类中存在的属性的标量值。 1. 你不能添加 Config 类中未定义的属性。 2. 你不能将属性中的标量值更改为数组。 3. 你不能向现有数组中添加元素。 -例如,你不能只是在 **.env** 中放置 ``app.myNewConfig = foo`` 并期望你的 ``Config\App`` 在运行时神奇地拥有该属性和值。 +例如，你不能在 **.env** 中放入 ``app.myNewConfig = foo`` 并期望你的 ``Config\App`` 在运行时神奇地拥有该属性和值。 -当你在 ``Config\Database`` 中有属性 ``$default = ['encrypt' => false]`` 时,即使你在 **.env** 中放置 ``database.default.encrypt.ssl_verify = true``,也不能将 ``encrypt`` 值更改为数组。如果你想这样做，请参阅 :ref:`Database Configuration `。 +当你的 ``Config\Database`` 中有属性 ``$default = ['encrypt' => false]`` 时，即使你在 **.env** 中放入 ``database.default.encrypt.ssl_verify = true``，也不能将 ``encrypt`` 值更改为数组。如果你想这样做，请参阅 :ref:`Database Configuration `。 将环境变量视为数组 ======================================== -可以进一步将命名空间环境变量视为数组。 -如果前缀与配置类匹配,则环境变量名称的其余部分在也包含点时将被视为数组引用。 +命名空间环境变量可以进一步被视为数组。如果前缀与配置类匹配，则环境变量名称的其余部分如果也包含点号，则被视为数组引用。 :: - // 常规命名空间变量 + // 普通命名空间变量 Config\SimpleConfig.name = George // 数组命名空间变量 Config\SimpleConfig.address.city = "Berlin" Config\SimpleConfig.address.country = "Germany" -如果这是指向 SimpleConfig 配置对象,那么上面的示例将被视为: +如果这是引用 SimpleConfig 配置对象，上述示例将被视为： .. literalinclude:: configuration/006.php -``$address`` 属性的任何其他元素保持不变。 +``$address`` 属性的任何其他元素将保持不变。 -你也可以使用数组属性名称作为前缀。如果环境文件包含以下内容,结果与上面相同。 +你也可以使用数组属性名作为前缀。如果环境文件包含以下内容，则结果将与上述相同。 :: @@ -243,66 +243,64 @@ CodeIgniter 期望 **.env** 文件与 **app** 目录一起位于项目的根目 处理不同环境 ******************************* -通过使用带有修改后的值来满足该环境需求的单独 **.env** 文件,可以轻松配置多个环境。 +通过使用单独的 **.env** 文件（其值已修改以满足该环境的需求），可以轻松完成多环境配置。 -该文件不应包含应用程序使用的每个可能的配置类的每一个可能设置。事实上,它应该只包含特定于该环境的项目,以及密码、API 密钥等不应公开暴露的敏感详细信息。但是任何在部署之间更改的都很合适。 +该文件不应包含应用程序使用的所有配置类的每个可能设置。实际上，它应该只包含特定于环境的项目，或者是密码、API 密钥和其他不应暴露的敏感详细信息。但任何在部署之间发生变化的内容都是合理的。 -在每个环境中,将 **.env** 文件放在项目的根目录中。对于大多数设置来说,这将与 ``app`` 目录处于同一级别。 +在每个环境中，将 **.env** 文件放在项目的根文件夹中。对于大多数设置，这将与 ``app`` 目录处于同一级别。 -不要使用版本控制系统跟踪 **.env** 文件。如果这样做,并且存储库被公开,你将在所有人都可以找到的地方放置敏感信息。 +不要使用版本控制系统跟踪 **.env** 文件。如果你这样做，并且存储库是公开的，你就会将敏感信息放在每个人都能找到的地方。 .. _registrars: 注册器 ********** -“注册器”是可以在命名空间和文件之间在运行时提供其他配置属性的任何其他类。 -注册器提供了一种在运行时跨命名空间和文件更改配置的方法。 +"注册器" 是任何可能提供额外配置属性的其他类。注册器提供了一种在运行时跨命名空间和文件更改配置的方法。 -如果在 :doc:`模块 ` 中启用了 :ref:`auto-discovery`，则注册器可以在命名空间和文件之间在运行时更改配置属性。 +如果在 :doc:`Modules ` 中启用了 :ref:`auto-discovery`，注册器就会工作。它在 Config 对象实例化时更改配置属性。 -.. note:: 此功能在 ``CodeIgniter\Config\BaseConfig`` 类中实现。因此，它不适用于 **app/Config** 文件夹中未继承该类的某些文件。 +.. note:: 此功能在 ``CodeIgniter\Config\BaseConfig`` 类中实现。因此，对于 **app/Config** 文件夹中不继承该类的少数文件，它将不起作用。 -有两种实现注册器的方法: **隐式** 和 **显式**。 +有两种实现注册器的方法：**隐式** 和 **显式**。 -.. note:: 来自 **.env** 的值始终优先于注册器。 +.. note:: **.env** 中的值始终优先于注册器。 隐式注册器 =================== -隐式注册器可以更改任何配置类的属性。 +隐式注册器可以更改任何 Config 类属性。 -任何命名空间都可以通过使用 **Config/Registrar.php** 文件定义隐式注册器。这些文件是类，其方法的名称与你希望扩展的每个配置类的名称相同。 +任何命名空间都可以通过使用 **Config/Registrar.php** 文件定义隐式注册器。这些文件是类，其方法以你希望扩展的每个配置类命名。 -例如，第三方模块或 Composer 包可能希望为 ``Config\Pager`` 提供额外的模板，而不会覆盖开发人员已经配置的内容。在 **src/Config/Registrar.php** 中，将有一个名为 ``Registrar`` 的类，其中只有一个 ``Pager()`` 方法（注意大小写敏感）： +例如，第三方模块或 Composer 包可能希望向 ``Config\Pager`` 提供额外的模板，而不会覆盖开发者已经配置的任何内容。在 **src/Config/Registrar.php** 中会有一个 ``Registrar`` 类，其中包含单个 ``Pager()`` 方法（注意大小写敏感）： .. literalinclude:: configuration/007.php -注册方法必须始终返回一个数组,其中的键对应目标配置文件中的属性。存在的值被合并,注册器属性具有覆盖优先级。 +注册器方法必须始终返回一个数组，其键对应于目标配置文件的属性。现有值将被合并，注册器属性具有覆盖优先级。 显式注册器 =================== -显式注册器只能更改其注册的配置类属性。 +显式注册器只能更改它们注册的 Config 类属性。 -配置文件还可以显式指定任意数量的注册器。 -这是通过在配置文件中添加一个 ``$registrars`` 属性来完成的,其中包含候选注册器的名称数组: +配置文件还可以显式指定任意数量的注册器。这是通过在配置文件中添加一个 ``$registrars`` 属性来完成的，该属性包含候选注册器名称的数组： .. literalinclude:: configuration/008.php -为了充当“注册器”,标识的类必须具有一个与配置类同名的静态函数,它应返回一个关联数组的属性设置。 +为了充当 "注册器"，所标识的类必须具有与配置类同名的静态函数，并且应该返回属性设置的关联数组。 -在实例化配置对象时,它将循环遍历 ``$registrars`` 中指定的类。对于这些类中的每个类,它都会调用以配置类命名的方法,并合并任何返回的属性。 +当你的配置对象被实例化时，它将遍历 ``$registrars`` 中指定的类。对于这些类中的每一个，它将调用以配置类命名的方法并合并任何返回的属性。 -针对此设置的配置类示例: +为此设置的示例配置类： .. literalinclude:: configuration/009.php -... 相关的区域销售模型可能如下所示: +... 相关的区域销售模型可能如下所示： .. literalinclude:: configuration/010.php -通过上面的示例,在实例化 ``MySalesConfig`` 时,它将最终具有声明的三个属性,但 ``$target`` 属性的值将通过将 ``RegionalSales`` 视为“注册器”来覆盖。生成的配置属性: +在上述示例中，当 ``MySalesConfig`` 被实例化时，它将最终拥有声明的三个属性，但 ``$target`` 属性的值将通过将 ``RegionalSales`` 视为 "注册器" 而被覆盖。结果配置属性： .. literalinclude:: configuration/011.php @@ -311,9 +309,9 @@ CodeIgniter 期望 **.env** 文件与 **app** 目录一起位于项目的根目 确认配置值 ************************ -实际的 Config 对象属性值在运行时由 :ref:`registrars`、:ref:`环境变量 ` 和 :ref:`factories-config-caching` 进行更改。 +实际的 Config 对象属性值在运行时由 :ref:`registrars` 和 :ref:`Environment Variables ` 以及 :ref:`factories-config-caching` 更改。 -CodeIgniter 有以下 :doc:`命令 <../cli/spark_commands>` 来检查实际的配置值。 +CodeIgniter 具有以下 :doc:`命令 <../cli/spark_commands>` 来检查实际的 Config 值。 .. _spark-config-check: @@ -328,7 +326,7 @@ config:check php spark config:check App -输出结果如下： +输出如下所示： .. code-block:: none @@ -351,6 +349,6 @@ config:check Config Caching: Disabled -你可以看到配置缓存是否已启用。 +你可以看到 Config Caching 是否启用。 -.. note:: 如果启用了配置缓存，则始终使用缓存的值。有关详情，请参阅 :ref:`factories-config-caching`。 +.. note:: 如果启用了 Config Caching，则会永久使用缓存的值。有关详细信息，请参阅 :ref:`factories-config-caching`。 diff --git a/source/general/environments.rst b/source/general/environments.rst index 709239599..774d82046 100755 --- a/source/general/environments.rst +++ b/source/general/environments.rst @@ -1,27 +1,30 @@ ############################## -处理多个环境 +处理多环境 ############################## -开发人员通常希望根据应用程序是在开发还是生产环境中运行来实现不同的系统行为。 -例如,在开发应用程序时,详细的错误输出是有用的,但在“生产环境”时可能也会带来安全问题。在开发环境中,你可能需要加载在生产环境中不需要的其他工具等等。 +开发者通常希望应用程序在开发环境和生产环境中表现出不同的系统行为。 +例如，详细的错误输出在应用开发过程中非常有用，但在“正式上线”后却可能带来安全隐患。 +此外，开发环境可能需要加载一些生产环境不需要的额外工具，诸如此类的情况还有很多。 .. contents:: :local: :depth: 3 ************************ -定义的环境 +预定义的环境 ************************ -默认情况下,CodeIgniter 定义了三个环境。 +默认情况下，CodeIgniter 定义了三种环境。 -- ``production`` 用于生产 -- ``development`` 用于开发 -- ``testing`` 用于 PHPUnit 测试 +- ``production`` - 生产环境 +- ``development`` - 开发环境 +- ``testing`` - PHPUnit 测试环境 -.. important:: 环境 ``testing`` 保留用于 PHPUnit 测试。它在框架的各处内置了一些特殊条件以协助测试。你不能在开发中使用它。 +.. important:: ``testing`` 环境专为 PHPUnit 测试保留。 + 框架在各个位置内置了特殊条件来协助测试。你不能用它来进行开发。 -如果你想要另一个环境,例如用于暂存,你可以添加自定义环境。请参阅 `添加环境`_。 +如果你需要其他环境，例如预发布环境（staging），可以添加自定义环境。 +参见 `添加环境`_。 .. _setting-environment: @@ -34,21 +37,22 @@ ENVIRONMENT 常量 ======================== -要设置环境,CodeIgniter 提供了 ``ENVIRONMENT`` 常量。 -如果设置了 ``$_SERVER['CI_ENVIRONMENT']``,将使用该值,否则默认为 ``production``。 +要设置环境，CodeIgniter 提供了 ``ENVIRONMENT`` 常量。 +如果你设置了 ``$_SERVER['CI_ENVIRONMENT']``，将使用该值， +否则默认为 ``production``。 -根据你的服务器设置,可以通过几种方式设置此值。 +可以根据服务器设置以多种方式设置此变量。 .env ---- -在 :ref:`.env 文件 ` 中设置该变量是最简单的方法。 +设置该变量最简单的方法是在你的 :ref:`.env 文件 ` 中。 .. code-block:: ini CI_ENVIRONMENT = development -.. note:: 你可以通过 ``spark env`` 命令更改 **.env** 文件中的 ``CI_ENVIRONMENT`` 值: +.. note:: 你可以使用 ``spark env`` 命令更改 **.env** 文件中的 ``CI_ENVIRONMENT`` 值： .. code-block:: console @@ -59,7 +63,7 @@ ENVIRONMENT 常量 Apache ------ -可以在 **.htaccess** 文件或 Apache 配置中使用 `SetEnv `_ 设置此服务器变量。 +可以使用 `SetEnv `_ 在你的 **.htaccess** 文件或 Apache 配置中设置此服务器变量。 .. code-block:: apache @@ -71,7 +75,9 @@ Apache Nginx ----- -在 Nginx 下,必须通过 ``fastcgi_params`` 传递环境变量,以便它在 ``$_SERVER`` 变量下显示。这允许它在虚拟主机级别工作,而不是使用 `env` 为整个服务器设置它,尽管这在专用服务器上也可以很好地工作。然后可以将服务器配置修改为类似以下内容: +在 Nginx 下，你必须通过 ``fastcgi_params`` 传递环境变量，使其显示在 ``$_SERVER`` 变量中。 +这样可以在虚拟主机级别工作，而不是使用 `env` 为整个服务器设置，尽管这在专用服务器上也能正常工作。 +然后你需要将服务器配置修改为类似这样： .. code-block:: nginx @@ -86,37 +92,37 @@ Nginx } } -Nginx 和其他服务器可用的替代方法,或者你可以完全删除此逻辑,并根据服务器的 IP 地址设置常量(例如)。 +针对 Nginx 等服务器还有其他替代方案，或者你也可以彻底删掉这部分逻辑，直接通过服务器 IP 地址等方式来设置常量。 -除了影响一些基本框架行为(参见下一节),你还可以在自己的开发中使用此常量来区分正在运行的环境。 +除了影响一些基本的框架行为（参见下一节），你还可以在自己的开发中使用此常量来区分当前运行在哪个环境中。 ******************* 添加环境 ******************* -要添加自定义环境,你只需要为它们添加引导文件。 +要添加自定义环境，只需为它们添加启动文件。 -引导文件 +启动文件 ========== -CodeIgniter 要求与环境名称匹配的 PHP 脚本位于 **APPPATH/Config/Boot** 下。这些文件可以包含你希望针对环境进行的任何自定义,无论是更新错误显示设置、加载其他开发人员工具还是其他任何内容。这些由系统自动加载。在初始安装中已经创建了以下文件: +CodeIgniter 要求在 **APPPATH/Config/Boot** 目录下放置一个与环境名称相匹配的 PHP 脚本。这些文件可以包含你希望针对当前环境进行的任何自定义配置，无论是调整错误显示设置、加载额外的开发工具，还是其他任何操作。系统会自动加载这些文件。在全新安装中，已默认创建了以下文件： * development.php * production.php * testing.php -例如,如果你想添加 ``staging`` 环境用于暂存,你只需要: +例如，如果你想要添加 ``staging`` 环境用于预发布，你需要做的就是： -1. 将 **APPPATH/Config/Boot/production.php** 复制到 **staging.php**。 -2. 如有必要,在 **staging.php** 中自定义设置。 +1. 将 **APPPATH/Config/Boot/production.php** 复制为 **staging.php**。 +2. 如果需要，在 **staging.php** 中自定义设置。 ********************************** 确认当前环境 ********************************** -要确认当前环境,只需打印常量 ``ENVIRONMENT``。 +要确认当前环境，只需输出常量 ``ENVIRONMENT`` 的值。 -你也可以通过 ``spark env`` 命令检查当前环境: +你也可以通过 ``spark env`` 命令检查当前环境： .. code-block:: console @@ -126,10 +132,13 @@ CodeIgniter 要求与环境名称匹配的 PHP 脚本位于 **APPPATH/Config/Boo 对默认框架行为的影响 ************************************* -CodeIgniter 系统中有一些地方使用了 ``ENVIRONMENT`` 常量。本节描述了默认框架行为如何受到影响。 +CodeIgniter 系统中有一些地方使用了 ``ENVIRONMENT`` 常量。 +本节描述了默认框架行为如何受到影响。 错误报告 =============== 将 ``ENVIRONMENT`` 常量设置为 ``development`` 值将导致所有 PHP 错误在发生时渲染到浏览器。 -相反,将常量设置为 ``production`` 将禁用所有错误输出。在生产中禁用错误报告是一项 :doc:`很好的安全实践 `。 +相反，将常量设置为 ``production`` 将禁用所有错误输出。 +在生产环境中禁用错误报告是一种 +:doc:`良好的安全实践 `。 diff --git a/source/general/errors.rst b/source/general/errors.rst index 4916a5049..aba1f9693 100755 --- a/source/general/errors.rst +++ b/source/general/errors.rst @@ -2,9 +2,10 @@ 错误处理 ############## -CodeIgniter 通过异常机制构建了错误报告系统，既包含 `SPL 集合 `_ 中的异常，也提供了框架专属的异常类型。 +CodeIgniter 通过异常机制为你的系统构建错误报告功能，包括 `SPL 集合 `_ 以及框架提供的一些异常。 -根据运行环境的配置，当发生错误或抛出异常时，默认行为是显示详细错误报告（除非应用处于 ``production`` 环境）。在 ``production`` 环境中，会显示更通用的信息以保持最佳用户体验。 +根据你的环境设置， +当抛出错误或异常时，默认操作是显示详细的错误报告，除非应用程序运行在 ``production`` 环境中。在 ``production`` 环境中，会显示更通用的消息，以保持用户的最佳体验。 .. contents:: :local: @@ -13,32 +14,37 @@ CodeIgniter 通过异常机制构建了错误报告系统，既包含 `SPL 集 使用异常 ================ -本节为新手程序员或不熟悉异常使用的开发者提供快速概览。 +本节为新程序员或对使用异常没有经验的开发者提供一个快速概览。 什么是异常 ------------------- +------------------- -异常是当程序 "抛出" 异常时发生的事件。这会中断当前脚本流程，并将执行权转交给错误处理程序以显示相应的错误页面： +异常只是在异常被"抛出"时发生的事件。这会停止脚本的当前流程， +然后将执行权发送给错误处理器，错误处理器会显示相应的错误页面： .. literalinclude:: errors/001.php 捕获异常 ------------------- -当调用可能抛出异常的方法时，可以使用 ``try/catch`` 代码块来捕获异常： +如果你调用的方法可能会抛出异常，可以使用 ``try/catch`` 来捕获该异常： .. literalinclude:: errors/002.php -如果 ``$userModel`` 抛出异常，该异常会被捕获并执行 catch 块中的代码。在此示例中，脚本终止并输出 ``UserModel`` 定义的错误信息。 +如果 ``$userModel`` 抛出异常，它会被捕获，catch 块中的代码会被执行。在这个例子中， +脚本会终止，并输出 ``UserModel`` 定义的错误消息。 捕获特定异常 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -上例中我们捕获所有类型的 Exception。若只需捕获特定类型的异常（如 ``DataException``），可在 catch 参数中指定。其他未被捕获的异常类型将传递给错误处理程序： +在上面的例子中，我们捕获任何类型的异常。如果我们只想监控特定类型的异常， +比如 ``DataException``，可以在 catch 参数中指定。任何其他抛出的异常 +如果不是被捕获异常的子类，将被传递给错误处理器： .. literalinclude:: errors/003.php -这种方式便于自行处理错误或在脚本结束前执行清理操作。若希望错误处理程序按常规方式处理，可在 catch 块中重新抛出异常： +这对于自己处理错误或在脚本结束前执行清理操作很有用。如果你希望 +错误处理器正常工作，可以在 catch 块中抛出新异常： .. literalinclude:: errors/004.php @@ -48,30 +54,38 @@ CodeIgniter 通过异常机制构建了错误报告系统，既包含 `SPL 集 错误报告 --------------- -当 PHP ini 设置中的 ``display_errors`` 启用时，CodeIgniter 将显示包含所有错误的详细报告 +当 PHP ini 设置中的 ``display_errors`` 启用时，CodeIgniter 将显示 +包含所有错误的详细错误报告 -默认情况下，CodeIgniter 在 ``development`` 和 ``testing`` 环境中显示详细错误报告，在 ``production`` 环境中不显示任何错误。 +因此默认情况下，CodeIgniter 会在 ``development`` 和 ``testing`` 环境中 +显示详细的错误报告，在 ``production`` 环境中不显示任何错误。 .. image:: ../images/error.png -可通过设置 ``CI_ENVIRONMENT`` 变量来更改环境配置，详见 :ref:`setting-environment`。 +你可以通过设置 ``CI_ENVIRONMENT`` 变量来更改你的环境。 +参见 :ref:`setting-environment`。 -.. important:: 禁用错误报告不会阻止错误日志的写入。 +.. important:: 禁用错误报告并不会在有错误时停止日志的写入。 -.. warning:: 注意 **.env** 文件中的设置会被添加到 ``$_SERVER`` 和 ``$_ENV``。副作用是当显示详细错误报告时，**你的敏感凭证可能被公开暴露**。 +.. warning:: 请注意，**.env** 文件中的设置会被添加到 ``$_SERVER`` + 和 ``$_ENV`` 中。作为副作用，这意味着如果显示了详细的错误报告， + **你的安全凭据将被公开暴露**。 异常日志记录 ------------------ -默认情况下，除 "404 - 页面未找到" 异常外，所有异常都会被记录。可通过修改 **app/Config/Exceptions.php** 中的 ``$log`` 值来开关此功能： +默认情况下，除了 "404 - Page Not Found" 异常之外的所有异常都会被记录。这可以通过 +设置 **app/Config/Exceptions.php** 中的 ``$log`` 值来开启或关闭： .. literalinclude:: errors/005.php -要忽略其他状态码的日志记录，可在同一文件中设置： +要忽略对其他状态码的日志记录，可以在同一文件中设置要忽略的状态码： .. literalinclude:: errors/006.php -.. note:: 如果当前 :ref:`日志设置 ` 未配置记录 ``critical`` 级别错误（所有异常均按此级别记录），异常可能仍不会被记录。 +.. note:: 如果你当前的 :ref:`日志设置 ` + 没有设置为记录 ``critical`` 错误（所有异常都被记录为此级别）， + 异常的日志记录可能仍然不会发生。 .. _logging_deprecation_warnings: @@ -80,33 +94,43 @@ CodeIgniter 通过异常机制构建了错误报告系统，既包含 `SPL 集 .. versionadded:: 4.3.0 -在 v4.3.0 之前，所有通过 ``error_reporting()`` 报告的错误都会被抛出为 ``ErrorException`` 对象。 +在 v4.3.0 之前，所有由 ``error_reporting()`` 报告的错误都会被抛出为 +``ErrorException`` 对象。 -随着 PHP 8.1+ 的普及，用户可能会遇到因 `向内部函数的非空参数传递 null 值 `_ 导致的异常抛出。 +但随着 PHP 8.1+ 的普及，许多用户可能会看到为 +`向非空内部函数参数传递 null `_ +抛出的异常。 -为简化迁移到 PHP 8.1 的过程，从 v4.3.0 开始，CodeIgniter 新增了仅记录弃用错误（``E_DEPRECATED`` 和 ``E_USER_DEPRECATED``）而不将其作为异常抛出的功能。 +为了简化向 PHP 8.1 的迁移，从 v4.3.0 开始，CodeIgniter 提供了 +只记录弃用错误（``E_DEPRECATED`` 和 ``E_USER_DEPRECATED``） +而不将其作为异常抛出的功能。 -默认情况下，CodeIgniter 在开发环境中仅记录弃用警告而不抛出异常。在生产环境中，既不记录也不抛出异常。 +默认情况下，CodeIgniter 只在开发环境中记录弃用警告而不抛出异常。 +在生产环境中，不会进行日志记录，也不会抛出异常。 配置 ^^^^^^^^^^^^^ -该功能的配置步骤如下： -首先确保 **Config\Exceptions** 已更新并包含以下两个新属性： +此功能的设置如下。 +首先，确保你的 ``Config\Exceptions`` 副本已更新为包含两个新属性， +并按以下方式设置： .. literalinclude:: errors/012.php -其次，根据 ``Config\Exceptions::$deprecationLogLevel`` 设置的日志级别，检查 ``Config\Logger::$threshold`` 定义的日志阈值是否涵盖该级别。如未涵盖需相应调整： +接下来，根据你在 ``Config\Exceptions::$deprecationLogLevel`` 中设置的日志级别， +检查 ``Config\Logger::$threshold`` 中定义的日志记录器阈值是否覆盖了弃用日志级别。 +如果没有，相应地调整它。 .. literalinclude:: errors/013.php -配置完成后，后续弃用警告将按配置记录而不作为异常抛出。 +之后，后续的弃用警告将按配置记录而不会作为异常抛出。 -该功能也支持用户自定义弃用警告： +此功能也适用于用户弃用： .. literalinclude:: errors/014.php -测试应用时若需强制抛出弃用警告，可设置环境变量 ``CODEIGNITER_SCREAM_DEPRECATIONS`` 为真值。 +为了测试应用程序，你可能希望总是在弃用时抛出异常。可以通过 +将环境变量 ``CODEIGNITER_SCREAM_DEPRECATIONS`` 设置为真值来配置此功能。 框架异常 ==================== @@ -116,70 +140,81 @@ CodeIgniter 通过异常机制构建了错误报告系统，既包含 `SPL 集 异常设计 ---------------- -自 v4.6.0 起，框架抛出的所有异常类： +从 v4.6.0 开始，框架抛出的所有异常类： - 实现 ``CodeIgniter\Exceptions\ExceptionInterface`` - 继承 ``CodeIgniter\Exceptions\LogicException`` 或 ``CodeIgniter\Exceptions\RuntimeException`` -.. note:: 框架仅抛出上述类型异常，但 PHP 或其他使用的库可能抛出其他异常。 +.. note:: 框架只抛出上述类型的异常类，但 PHP + 或使用的其他库可能会抛出其他异常。 -框架抛出的两种基础异常类： +框架抛出的异常有两个基类： LogicException -------------- -``CodeIgniter\Exceptions\LogicException`` 继承自 ``\LogicException``。该异常表示程序逻辑错误，应直接通过修改代码修复。 +``CodeIgniter\Exceptions\LogicException`` 继承 ``\LogicException``。 +此异常表示程序逻辑中的错误。这类异常应该直接导致修复你的代码。 RuntimeException ---------------- -``CodeIgniter\Exceptions\RuntimeException`` 继承自 ``\RuntimeException``。该异常在运行时发生错误时抛出。 +``CodeIgniter\Exceptions\RuntimeException`` 继承 ``\RuntimeException``。 +如果发生只能在运行时发现的错误，会抛出此异常。 -其他可用框架异常： +框架还提供以下异常： PageNotFoundException --------------------- -用于触发 404 页面未找到错误： +用于表示 404 Page Not Found 错误： .. literalinclude:: errors/007.php -可传递自定义消息替代默认的 404 页面信息。默认 404 视图文件位置参见 :ref:`http-status-code-and-error-views`。 +你可以向异常传递消息，该消息将显示在 404 页面上替换默认消息。 + +有关默认 404 视图文件位置，请参见 :ref:`http-status-code-and-error-views`。 -如果在 **app/Config/Routing.php** 或 **app/Config/Routes.php** 中配置了 :ref:`404-override`，将调用该覆盖配置而非标准 404 页面。 +如果在 **app/Config/Routing.php** 或 **app/Config/Routes.php** 中指定了 +:ref:`404-override`，则会调用它而不是标准的 404 页面。 ConfigException --------------- -当配置类值无效或配置类类型不符时使用此异常： +当配置类的值无效，或配置类不是正确的类型等情况时，应使用此异常： .. literalinclude:: errors/008.php -该异常提供退出码 3。 +该异常提供退出代码 3。 DatabaseException ----------------- -在数据库连接创建失败或临时丢失等数据库错误时抛出： +为数据库错误抛出此异常，例如无法创建数据库连接， +或连接暂时丢失时： .. literalinclude:: errors/009.php -该异常提供退出码 8。 +该异常提供退出代码 8。 RedirectException ----------------- -.. note:: 自 v4.4.0 起，``RedirectException`` 的命名空间已变更。原为 ``CodeIgniter\Router\Exceptions\RedirectException``，该旧类已在 v4.6.0 移除。 +.. note:: 从 v4.4.0 开始，``RedirectException`` 的命名空间已更改。 + 之前它是 ``CodeIgniter\Router\Exceptions\RedirectException``。 + 之前的类在 v4.6.0 中已被移除。 -此特殊异常允许覆盖其他响应路由并强制重定向到指定 URI： +此异常是一个特殊情况，允许覆盖所有其他响应路由并强制重定向到特定 URI： .. literalinclude:: errors/010.php -``$uri`` 是相对于 baseURL 的 URI 路径。可指定替代默认值（``302``，"临时重定向"）的重定向代码： +``$uri`` 是相对于 baseURL 的 URI 路径。你也可以提供 +重定向代码来代替默认值（``302``，"临时重定向"）： .. literalinclude:: errors/011.php -自 v4.4.0 起，第一个参数可使用实现 ResponseInterface 的对象。此方案适用于需要添加额外头信息或 cookies 的场景： +另外，从 v4.4.0 开始，实现 ResponseInterface 的类的对象可以用作第一个参数。 +此解决方案适用于需要在响应中添加额外头部或 Cookie 的情况。 .. literalinclude:: errors/018.php @@ -190,42 +225,52 @@ RedirectException .. versionadded:: 4.3.0 -自 v4.3.0 起，可通过让异常类实现 ``CodeIgniter\Exceptions\HTTPExceptionInterface`` 来指定 HTTP 状态码。 +从 v4.3.0 开始，你可以为你的异常类指定 HTTP 状态码，以实现 +``CodeIgniter\Exceptions\HTTPExceptionInterface``。 -当 CodeIgniter 异常处理器捕获到实现 ``HTTPExceptionInterface`` 的异常时，异常代码将作为 HTTP 状态码。 +当实现 ``HTTPExceptionInterface`` 的异常被 CodeIgniter 的异常处理器捕获时， +异常代码将成为 HTTP 状态码。 .. _http-status-code-and-error-views: -HTTP 状态码与错误视图 -========================= - -异常处理器会显示与 HTTP 状态码对应的错误视图（如果存在）。 +HTTP 状态码和错误视图 +================================ -例如，``PageNotFoundException`` 实现了 ``HTTPExceptionInterface``，其异常代码 ``404`` 将作为 HTTP 状态码。当该异常被抛出时： +异常处理器显示与 HTTP 状态码对应的错误视图（如果存在）。 -- 网页请求会显示 **app/Views/errors/html** 目录下的 **error_404.php** -- CLI 请求会显示 **app/Views/errors/cli** 目录下的 **error_404.php** +例如，``PageNotFoundException`` 实现了 ``HTTPExceptionInterface``， +所以其异常代码 ``404`` 将是 HTTP 状态码。因此如果它被抛出， +当是 Web 请求时，系统将显示 **app/Views/errors/html** 文件夹中的 +**error_404.php**。如果是通过 CLI 调用，系统将显示 +**app/Views/errors/cli** 文件夹中的 **error_404.php**。 -若无对应 HTTP 状态码的视图文件，将显示 **production.php** 或 **error_exception.php**。 +如果没有与 HTTP 状态码对应的视图文件，将显示 **production.php** +或 **error_exception.php**。 -.. note:: 若 PHP ini 设置中 ``display_errors`` 开启，将选择 **error_exception.php** 并显示详细错误报告。 +.. note:: 如果 PHP ini 设置中的 ``display_errors`` 开启， + 会选择 **error_exception.php** 并显示详细的错误报告。 -建议在 **app/Views/errors/html** 目录下自定义所有错误视图。 +你应该为你的网站自定义 **app/Views/errors/html** 文件夹中的所有错误视图。 -可为特定 HTTP 状态码创建错误视图。例如创建 "400 Bad Request" 错误视图需添加 **error_400.php**。 +你也可以为特定的 HTTP 状态码创建错误视图。例如，如果你想为 +"400 Bad Request" 创建错误视图，添加 **error_400.php**。 -.. warning:: 若存在对应 HTTP 状态码的错误视图文件，异常处理器将始终显示该文件。必须确保视图文件在生产环境中不会自行显示详细错误信息。 +.. warning:: 如果存在具有相应 HTTP 状态码的错误视图文件， + 异常处理器将显示该文件，而不管环境如何。 + 视图文件必须以在生产环境中不显示详细错误消息的方式自行实现。 .. _error-specify-exit-code: -在异常中指定退出码 -============================= +在异常中指定退出代码 +=================================== .. versionadded:: 4.3.0 -自 v4.3.0 起，可通过让异常类实现 ``CodeIgniter\Exceptions\HasExitCodeInterface`` 来指定退出码。 +从 v4.3.0 开始，你可以为你的异常类指定退出代码，以实现 +``CodeIgniter\Exceptions\HasExitCodeInterface``。 -当 CodeIgniter 异常处理器捕获到实现 ``HasExitCodeInterface`` 的异常时，将从 ``getExitCode()`` 方法获取退出码。 +当实现 ``HasExitCodeInterface`` 的异常被 CodeIgniter 的异常处理器捕获时， +从 ``getExitCode()`` 方法返回的代码将成为退出代码。 .. _custom-exception-handlers: @@ -234,24 +279,32 @@ HTTP 状态码与错误视图 .. versionadded:: 4.4.0 -若需更精细控制异常显示方式，可定义自定义处理器并指定其应用场景。 +如果你需要更多控制异常的显示方式，现在可以定义自己的处理器并 +指定它们何时应用。 定义新处理器 ------------------------ -首先创建实现 ``CodeIgniter\Debug\ExceptionHandlerInterface`` 的新类。也可继承 ``CodeIgniter\Debug\BaseExceptionHandler``，该类包含默认异常处理器使用的实用方法。新处理器需实现 ``handle()`` 方法： +第一步是创建一个实现 ``CodeIgniter\Debug\ExceptionHandlerInterface`` 的新类。 +你也可以继承 ``CodeIgniter\Debug\BaseExceptionHandler``。 +这个类包含许多默认异常处理器使用的实用方法。 +新处理器必须实现一个方法：``handle()``： .. literalinclude:: errors/015.php -此示例展示了典型的最小实现：显示视图并以正确退出码终止。``BaseExceptionHandler`` 还提供其他辅助功能和对象。 +这个例子定义了通常需要的最小代码量 - 显示视图并以适当的 +退出代码退出。但是，``BaseExceptionHandler`` 提供了许多其他辅助函数和对象。 配置新处理器 --------------------------- -在 **app/Config/Exceptions.php** 配置文件的 ``handler()`` 方法中指定使用新异常处理器类： +告诉 CodeIgniter 使用你的新异常处理器类是在 **app/Config/Exceptions.php** +配置文件的 ``handler()`` 方法中完成的： .. literalinclude:: errors/016.php -可使用任意逻辑决定是否处理异常，最常见的是检查 HTTP 状态码或异常类型。若应由自定义类处理，则返回该类实例： +你可以使用应用程序需要的任何逻辑来确定是否应该处理异常， +但最常见的是检查 HTTP 状态码或异常类型。如果你的类应该处理它， +则返回该类的新实例： .. literalinclude:: errors/017.php diff --git a/source/general/helpers.rst b/source/general/helpers.rst index 09eb698fa..d8bcc7d7b 100755 --- a/source/general/helpers.rst +++ b/source/general/helpers.rst @@ -7,98 +7,127 @@ :depth: 2 ***************** -什么是辅助函数? +什么是辅助函数？ ***************** -顾名思义，辅助函数可以帮助你完成任务。每个 helper 文件只是某个特定类别的函数集合。有 :doc:`URL 辅助函数 <../helpers/url_helper>`，可以帮助创建链接，有 :doc:`表单辅助函数 <../helpers/form_helper>` 可以帮助创建表单元素，:doc:`文本辅助函数 <../helpers/text_helper>` 执行各种文本格式化，:doc:`Cookie 辅助函数 <../helpers/cookie_helper>` 设置和读取 Cookie，:doc:`文件系统辅助函数 <../helpers/filesystem_helper>` 帮助处理文件等等。 +顾名思义，辅助函数就是帮助你完成任务的函数。每个辅助函数文件都只是某个特定类别中的函数集合。 +:doc:`URL 辅助函数 <../helpers/url_helper>` 可帮助创建链接， +:doc:`表单辅助函数 <../helpers/form_helper>` 可帮助创建表单元素， +:doc:`文本辅助函数 <../helpers/text_helper>` 执行各种文本格式化操作， +:doc:`Cookie 辅助函数 <../helpers/cookie_helper>` 设置和读取 Cookie， +:doc:`文件系统辅助函数 <../helpers/filesystem_helper>` 帮助处理文件等。 -与 CodeIgniter 中的大多数其他系统不同,辅助函数不是面向对象的格式。它们是简单的程序性函数。每个辅助函数执行一个特定的任务,不依赖于其他函数。 +与 CodeIgniter 中的大多数其他系统不同，辅助函数不是以 +面向对象格式编写的。它们是简单的、过程化的函数。每个 +辅助函数执行一个特定任务，不依赖于其他函数。 -CodeIgniter 默认不加载辅助文件,所以使用辅助函数的第一步是加载它。一旦加载,它就可以在你的 :doc:`控制器 <../incoming/controllers>` 和 :doc:`视图 <../outgoing/views>` 中全局使用。 +CodeIgniter 默认不会加载辅助函数文件，所以使用辅助函数的 +第一步是加载它。一旦加载，它就在你的 :doc:`控制器 <../incoming/controllers>` 和 +:doc:`视图 <../outgoing/views>` 中全局可用。 辅助函数通常存储在 **system/Helpers** 或 **app/Helpers** 目录中。 -**************** +*************** 加载辅助函数 -**************** +*************** -.. note:: :doc:`../helpers/url_helper` 总是加载的,所以你不需要自己加载它。 +.. note:: :doc:`../helpers/url_helper` 总是已加载的，所以你不需要自己加载。 -加载单个辅助函数 +加载辅助函数 ================ -使用以下方法加载辅助函数文件非常简单: +使用以下方法加载辅助函数文件非常简单： .. literalinclude:: helpers/001.php 上述代码会加载 **name_helper.php** 文件。 -.. important:: CodeIgniter 辅助函数文件名全部小写。因此,在区分大小写的文件系统(如 Linux)上, ``helper('Name')`` 将无法工作。 +.. important:: CodeIgniter 辅助函数文件名全部是小写。 + 因此，在区分大小写的文件系统（如 Linux）上， + ``helper('Name')`` 将无法工作。 -例如,要加载名为 **cookie_helper.php** 的 :doc:`../helpers/cookie_helper` 文件,你会这样做: +例如，要加载名为 **cookie_helper.php** 的 :doc:`../helpers/cookie_helper` 文件， +你需要这样做： .. literalinclude:: helpers/002.php -.. note:: :php:func:`helper()` 函数不返回值,所以不要试图将其分配给变量。只按上面示例的方式使用它。 +.. note:: :php:func:`helper()` 函数不返回值， + 所以不要尝试将其赋值给变量。只需按所示使用即可。 自动发现和 Composer 包 ------------------------- +------------------------------------ -默认情况下，CodeIgniter 会通过 :ref:`auto-discovery` 在所有定义的命名空间中搜索辅助函数文件。 -你可以使用 spark 命令来检查你定义的命名空间。请参阅 :ref:`confirming-namespaces`。 +默认情况下，CodeIgniter 会通过 :ref:`auto-discovery` 在所有已定义的命名空间中 +搜索辅助函数文件。 +你可以通过 spark 命令检查已定义的命名空间。参见 :ref:`confirming-namespaces`。 -如果你使用了许多 Composer 包，那么你将有许多已定义的命名空间。 +如果你使用了许多 Composer 包，你将有许多已定义的命名空间。 CodeIgniter 默认会扫描所有命名空间。 -为了避免浪费时间扫描不相关的 Composer 包，你可以手动指定要进行自动发现的包。请参阅 :ref:`modules-specify-composer-packages` 了解详细信息。 +为了避免浪费时间扫描不相关的 Composer 包，你可以手动 +指定用于自动发现的包。详细信息参见 :ref:`modules-specify-composer-packages`。 -或者，你可以为要加载的辅助函数 :ref:`指定一个命名空间 `。 +或者你可以为要加载的辅助函数 :ref:`指定命名空间 `。 加载顺序 ---------- -:php:func:`helper()` 函数会扫描通过所有定义的命名空间，并加载所有名称匹配的辅助函数。这样可以加载任何模块的辅助函数，以及你为此应用专门创建的任何辅助函数。 +:php:func:`helper()` 函数会扫描所有已定义的命名空间并加载所有 +名称匹配的辅助函数。这样可以加载任何模块的辅助函数， +以及你专门为这个应用程序创建的任何辅助函数。 加载顺序如下： 1. app/Helpers - 这里的文件总是首先加载。 -2. {namespace}/Helpers - 所有的命名空间都会按照它们定义的顺序依次循环。 +2. {namespace}/Helpers - 所有命名空间按照定义的顺序循环处理。 3. system/Helpers - 基础文件最后加载。 加载多个辅助函数 ======================== -如果你需要一次加载多个辅助函数,可以传递一个文件名数组,它们都会被加载: +如果需要一次加载多个辅助函数，你可以传入一个文件名数组， +所有这些辅助函数都将被加载： .. literalinclude:: helpers/003.php 在控制器中加载 ======================= -可以在控制器方法中的任何位置加载辅助函数(甚至在视图文件中,尽管这不是一个好的实践),只要在使用它之前加载它即可。 +辅助函数可以在控制器方法中的任何地方加载（甚至可以在视图文件中加载， +尽管这不是好的做法），只要在使用之前加载即可。 -你可以在控制器构造函数中加载辅助函数,以使它们自动在任何方法中可用,或者你可以在需要它的特定方法中加载辅助函数。 +你可以在控制器构造函数中加载辅助函数， +这样它们在任何方法中都自动可用，或者也可以在需要它们的 +特定方法中加载辅助函数。 -但是,如果你想在控制器构造函数中加载,则可以改用 Controller 中的 ``$helpers`` 属性。参见 :ref:`控制器 `。 +但是如果你想在控制器构造函数中加载，可以使用 Controller 中的 ``$helpers`` +属性。参见 :ref:`控制器 `。 .. _helpers-loading-from-specified-namespace: 从指定命名空间加载 ================================ -默认情况下，CodeIgniter 会在所有定义的命名空间中搜索辅助函数文件，并加载所有找到的文件。 +默认情况下，CodeIgniter 会在所有已定义的命名空间中搜索辅助函数文件并加载所有找到的文件。 -如果你只想加载特定命名空间中的一个辅助函数，在辅助函数的名称前加上它所在的命名空间作为前缀。在该命名空间目录中，加载器预期它位于一个名为 **Helpers** 的子目录内。以示例来帮助理解这一点。 +如果你只想加载特定命名空间中的辅助函数，可以在辅助函数名称前加上 +可以找到它的命名空间前缀。在该命名空间目录中， +加载器期望它位于名为 **Helpers** 的子目录中。例子将帮助理解这一点。 -对于此示例,假设我们已经将所有与博客相关的代码分组到自己的命名空间 ``Example\Blog`` 中。文件存在于我们的服务器上的 **Modules/Blog/** 中。因此,我们会将博客模块的辅助函数文件放在 **Modules/Blog/Helpers/** 中。**blog_helper** 文件将位于 **Modules/Blog/Helpers/blog_helper.php**。在我们的控制器中,我们可以使用以下命令加载辅助函数: +在这个例子中，假设我们已将所有与博客相关的代码分组到自己的命名空间 ``Example\Blog`` 中。 +文件存在于服务器上的 **Modules/Blog/** 目录中。 +因此，我们将博客模块的辅助函数文件放在 **Modules/Blog/Helpers/** 中。 +**blog_helper** 文件将位于 **Modules/Blog/Helpers/blog_helper.php**。 +在控制器中，我们可以使用以下命令为加载辅助函数： .. literalinclude:: helpers/004.php -你也可以使用以下方式: +你也可以使用以下方式： .. literalinclude:: helpers/007.php -.. note:: 以这种方式加载的文件中的函数并不是真正的命名空间化的。命名空间只是用作方便定位文件的一种方式。 +.. note:: 以这种方式加载的文件中的函数并非真正具有命名空间。 + 命名空间只是作为定位文件的便捷方式。 .. _auto-loading-helpers: @@ -107,20 +136,25 @@ CodeIgniter 默认会扫描所有命名空间。 .. versionadded:: 4.3.0 -如果你发现整个应用程序都需要一个特定的辅助函数,你可以告诉 CodeIgniter 在系统初始化期间自动加载它。 -这是通过打开 **app/Config/Autoload.php** 文件,并将辅助函数添加到 ``$helpers`` 属性来完成的。 +如果你发现需要在整个应用程序中全局使用某个特定的辅助函数， +你可以告诉 CodeIgniter 在系统初始化期间自动加载它。 +这是通过打开 **app/Config/Autoload.php** 文件 +并将辅助函数添加到 ``$helpers`` 属性来完成的。 ************** 使用辅助函数 ************** -一旦你加载了包含要使用的函数的辅助文件,你就可以像调用标准 PHP 函数一样调用它。 +一旦加载了包含你打算使用的函数的辅助函数文件， +你就可以像调用标准 PHP 函数一样调用它。 -例如,要在视图文件中使用 :php:func:`anchor()` 函数创建一个链接,你会这样做: +例如，要在视图文件之一中使用 :php:func:`anchor()` 函数创建链接， +你可以这样做： .. literalinclude:: helpers/005.php -其中 “Click Here” 是链接的名称,“blog/comments” 是你想要链接到的控制器/方法的 URI。 +其中 ``Click Here`` 是链接的名称，``blog/comments`` 是你希望链接到的 +控制器/方法的 URI。 **************** 创建辅助函数 @@ -129,34 +163,42 @@ CodeIgniter 默认会扫描所有命名空间。 创建自定义辅助函数 ======================= -辅助函数文件名是 **辅助函数名** 和 **_helper.php**。 +辅助函数文件名是 **辅助函数名称** 加上 **_helper.php**。 例如，要创建 info 辅助函数，你需要创建一个名为 -**app/Helpers/info_helper.php** 的文件，并向文件中添加一个函数： +**app/Helpers/info_helper.php** 的文件，并向该文件添加一个函数： .. literalinclude:: helpers/008.php -你可以在一个辅助函数文件中添加尽可能多的函数。 +你可以根据需要向单个辅助函数文件添加任意数量的函数。 -“扩展”辅助函数 +"扩展"辅助函数 =================== -要“扩展”辅助函数,请在 **app/Helpers** 文件夹中创建一个与现有辅助函数相同名称的文件。 +要"扩展"辅助函数，请在你的 **app/Helpers** 文件夹中创建一个 +与现有辅助函数同名的文件。 -如果你只需要为现有辅助函数添加一些功能 - 可能添加一个或两个函数,或者更改某个特定辅助函数的工作方式 - 那么用你的版本完全替换整个辅助函数有点过度设计。在这种情况下,最好只是“扩展”辅助函数。 +如果你只需要为现有辅助函数添加一些功能—— +也许添加一两个函数，或更改特定辅助函数函数的操作方式—— +那么用你的版本替换整个辅助函数就太过头了。在这种情况下， +最好简单地"扩展"辅助函数。 -.. note:: 这里“扩展”一词使用很宽松,因为辅助函数是程序性的和离散的,在传统意义上无法扩展。在底层,这为你提供了添加或替换辅助函数提供的函数的能力。 +.. note:: "扩展"这个术语是宽松使用的，因为辅助函数是 + 过程化和离散的，不能在传统的程序意义上进行扩展。 + 在底层，这使你能够添加或替换辅助函数提供的函数。 -例如,要扩展原生的 **Array 辅助函数**,你需要创建一个名为 **app/Helpers/array_helper.php** 的文件,并添加或覆盖函数: +例如，要扩展原生 **Array 辅助函数**，你需要创建一个 +名为 **app/Helpers/array_helper.php** 的文件，并添加或覆盖函数： .. literalinclude:: helpers/006.php .. important:: 不要指定命名空间 ``App\Helpers``。 -参见 `加载顺序`_ 了解辅助函数文件的加载顺序。 +关于辅助函数文件的加载顺序，请参见 `加载顺序`_。 ********* -接下来呢? +下一步？ ********* -在目录中,你会找到所有可用 :doc:`辅助函数 <../helpers/index>` 的列表。浏览每个函数以查看它们的作用。 +在目录中，你会找到所有可用的 :doc:`辅助函数 <../helpers/index>` 列表。 +浏览每个辅助函数以了解它们的功能。 diff --git a/source/general/logging.rst b/source/general/logging.rst index 1783dfbd2..8092645af 100755 --- a/source/general/logging.rst +++ b/source/general/logging.rst @@ -1,5 +1,5 @@ ################### -记录信息 +日志信息记录 ################### .. contents:: @@ -9,72 +9,75 @@ 日志级别 ========== -你可以通过使用 :php:func:`log_message()` 方法将信息记录到本地日志文件中。你必须在第一个参数中提供错误的“级别”,指示消息的类型(调试、错误等)。第二个参数是消息本身: +可以使用 :php:func:`log_message()` 方法将信息记录到本地日志文件中。必须在第一个参数中提供错误的"级别"，以表明这是哪种类型的消息（debug、error 等）。第二个参数是消息本身： .. literalinclude:: logging/001.php -有八种不同的日志级别,与 `RFC 5424 `_ 级别匹配,如下所示: +共有八个不同的日志级别，与 `RFC 5424 `_ 标准级别相匹配，具体如下： =========== ================================================================== 级别 描述 =========== ================================================================== debug 详细的调试信息。 -info 应用程序中的有趣事件,如用户登录、记录 SQL 查询等。 -notice 应用程序中的正常但重要事件。 -warning 非错误的异常事件,如使用废弃的 API、错误使用 API 或其他不一定错误的不可取之处。 -error 不需要立即处理但通常应记录和监控的运行时错误。 -critical 关键状态,如应用程序组件不可用,或意外异常。 -alert 必须立即采取行动,如整个网站关闭、数据库不可用等。 +info 应用程序中的重要事件，如用户登录、记录 SQL 查询等。 +notice 应用程序中的正常但重要的事件。 +warning 异常情况但不是错误，如使用已废弃的 API、不当的 API 使用， + 或其他不一定是错误的不良情况。 +error 不需要立即采取行动但通常应该记录和监控的运行时错误。 +critical 严重状况，如应用程序组件不可用，或出现意外异常。 +alert 必须立即采取行动，如整个网站宕机、数据库不可用等。 emergency 系统无法使用。 =========== ================================================================== -日志系统不提供通知系统管理员或网站管理员这些事件的方法,它仅记录信息。对于许多更关键的事件级别,日志由上述错误处理程序自动完成。 +日志系统不提供向系统管理员或网站管理员发出这些事件警报的方式，它们仅负责记录信息。对于许多更严重的事件级别，日志记录由上述错误处理程序自动进行。 .. _logging-configuration: 配置 ============= -你可以修改实际记录的级别,以及为不同级别分配不同的记录器,都在 **app/Config/Logger.php** 配置文件中完成。 +可以在 **app/Config/Logger.php** 配置文件中修改实际记录的级别，以及为不同的级别分配不同的日志处理器。 -配置文件中的 ``threshold`` 值确定跨应用程序记录的级别。如果应用程序请求记录任何级别,但阈值当前不允许它们记录,则它们将被忽略。使用的最简单方法是将此值设置为你希望记录的最低级别。例如,如果你想记录警告消息而不是信息消息,你应该将阈值设置为 ``5``。级别为 5 或更低(包括运行时错误、系统错误等)的任何日志请求都会被记录,而 info、notice 和 debug 会被忽略: +配置文件中的 ``threshold`` 值决定了整个应用程序中记录哪些级别的日志。如果应用程序请求记录某些级别，但当前阈值不允许它们记录，这些请求将被忽略。最简单的使用方法是将此值设置为想要记录的最低级别。例如，如果想要记录警告消息而不是信息消息，可以将阈值设置为 ``5``。级别为 5 或更低的任何日志请求（包括运行时错误、系统错误等）都将被记录，而 info、notice 和 debug 级别将被忽略： .. literalinclude:: logging/002.php -配置文件中包含完整的级别列表及其对应的阈值以供参考。 +配置文件中提供了完整的级别列表及其对应的阈值供参考。 -你可以通过将日志级别编号的数组分配给阈值来选择要记录的特定级别: +可以通过将日志级别编号的数组赋值给阈值来选择想要记录的特定级别： .. literalinclude:: logging/003.php -使用多个日志处理程序 +使用多个日志处理器 --------------------------- -日志系统可以同时支持运行多个日志处理方法。每个处理程序可以设置为处理特定级别并忽略其余级别。默认安装中提供了三个处理程序: +日志系统可以同时支持多种日志处理方式。每个处理器可以设置为处理特定级别并忽略其余级别。目前，默认安装包含三个处理器： -- **File Handler** 是默认的处理程序,将每天在本地创建一个文件。这是推荐的日志方法。 -- **ChromeLogger Handler** 如果你在 Chrome 网页浏览器中安装了 `ChromeLogger 扩展 `_,则可以使用此处理程序在 Chrome 的控制台窗口中显示日志信息。 -- **Errorlog Handler** 此处理程序将利用 PHP 的原生 ``error_log()`` 函数并将日志写入其中。目前仅支持 ``error_log()`` 的 ``0`` 和 ``4`` 消息类型。 +- **文件处理器** 是默认处理器，将在本地为每一天创建单个文件。这是推荐的日志记录方法。 +- **ChromeLogger 处理器** 如果在 Chrome 网页浏览器中安装了 `ChromeLogger 扩展 `_， + 可以使用此处理器在 Chrome 的控制台窗口中显示日志信息。 +- **Errorlog 处理器** 此处理器将利用 PHP 原生的 ``error_log()`` 函数并在其中写入日志。 + 目前，仅支持 ``error_log()`` 的 ``0`` 和 ``4`` 消息类型。 -主配置文件中的 ``$handlers`` 属性配置了处理程序,它简单地是一个处理程序数组及其配置。每个处理程序通过键指定,即完全限定的类名。值将是特定于每个处理程序的各种属性的数组。每个处理程序部分将有一个共同点:``handles``,这是一个日志级别 *名称* 数组,处理程序将为其记录信息。 +处理器在主配置文件的 ``$handlers`` 属性中配置，这只是一个处理器及其配置的数组。每个处理器通过完全限定的命名空间类名作为键来指定。值将是一个各不相同的属性数组，特定于每个处理器。每个处理器的部分都有一个共同的属性：``handles``，这是一个日志级别 *名称* 的数组，处理器将为这些级别记录日志信息。 .. literalinclude:: logging/004.php 使用上下文修改消息 ================================== -你会经常想根据日志的事件上下文修改消息的详细信息。你可能需要记录用户 id、IP 地址、当前的 POST 变量等。你可以通过在消息中使用占位符来实现这一点。每个占位符必须用大括号包装。在第三个参数中,你必须提供一个占位符名称(不带括号)和它们的值的数组。这些将插入到消息字符串中: +通常需要根据被记录事件的上下文来修改消息的详细信息。可能需要记录用户 ID、IP 地址、当前的 POST 变量等。可以通过在消息中使用占位符来实现这一点。每个占位符必须用大括号包裹。在第三个参数中，必须提供一个包含占位符名称（不带大括号）及其值的数组。这些将被插入到消息字符串中： .. literalinclude:: logging/005.php -如果你想记录异常或错误,可以使用 'exception' 键,值是异常或错误本身。将从该对象生成包含错误消息、文件名和行号的字符串。你仍必须在消息中提供异常占位符: +如果想要记录异常或错误，可以使用 'exception' 键，值是异常或错误本身。将从此对象生成一个包含错误消息、文件名和行号的字符串。仍然必须在消息中提供异常占位符： .. literalinclude:: logging/006.php -根据当前页面请求,存在几个核心占位符将自动为你展开: +存在几个核心占位符，它们将根据当前页面请求自动展开： +----------------+---------------------------------------------------+ -| 占位符 | 插入的值 | +| 占位符 | 插入值 | +================+===================================================+ | {post_vars} | $_POST 变量 | +----------------+---------------------------------------------------+ @@ -82,20 +85,20 @@ emergency 系统无法使用。 +----------------+---------------------------------------------------+ | {session_vars} | $_SESSION 变量 | +----------------+---------------------------------------------------+ -| {env} | 当前环境名称,即 development | +| {env} | 当前环境名称，即 development | +----------------+---------------------------------------------------+ -| {file} | 调用 logger 的文件名 | +| {file} | 调用日志记录器的文件名 | +----------------+---------------------------------------------------+ -| {line} | {file} 中调用 logger 的行 | +| {line} | 在 {file} 中调用日志记录器的行号 | +----------------+---------------------------------------------------+ | {env:foo} | $_ENV 中的 'foo' 值 | +----------------+---------------------------------------------------+ -使用第三方日志器 +使用第三方日志记录器 ========================= -只要它扩展自 ``Psr\Log\LoggerInterface`` 并且与 `PSR-3 `_ 兼容,你就可以使用任何其他你喜欢的日志器。这意味着你可以轻松使用任何兼容 PSR-3 的日志器,或创建你自己的日志器。 +可以使用任何其他喜欢的日志记录器，只要它扩展自 ``Psr\Log\LoggerInterface`` 并且与 `PSR-3 `_ 兼容。这意味着可以轻松使用任何 PSR-3 兼容的日志记录器，或者创建自己的日志记录器。 -你必须确保系统能够找到第三方日志器,方法是将其添加到 **app/Config/Autoload.php** 配置文件中,或通过另一个自动加载器(如 Composer)。接下来,你应该修改 **app/Config/Services.php** 以将 ``logger`` 别名指向新的类名。 +必须确保第三方日志记录器能够被系统找到，方法是将其添加到 **app/Config/Autoload.php** 配置文件中，或者通过其他自动加载器（如 Composer）。接下来，应该修改 **app/Config/Services.php** 将 ``logger`` 别名指向新的类名。 -现在,通过 :php:func:`log_message()` 函数执行的任何调用都将使用你的库。 +现在，通过 :php:func:`log_message()` 函数进行的任何调用都将使用你的库。 diff --git a/source/general/managing_apps.rst b/source/general/managing_apps.rst index b676301d4..6b7077415 100755 --- a/source/general/managing_apps.rst +++ b/source/general/managing_apps.rst @@ -2,7 +2,7 @@ 管理应用程序 ########################## -默认情况下,假设你只打算在 **app** 目录中使用 CodeIgniter 来管理一个应用程序。但是,可以拥有多个共享单个 CodeIgniter 安装的应用程序集,或者重命名或重新定位你的应用程序目录。 +默认情况下，CodeIgniter 假定你只打算使用一个应用程序，该应用程序将在你的 **app** 目录中构建。然而，你也可以拥有多个共享同一个 CodeIgniter 安装的应用程序集合，甚至可以重命名或重新定位你的应用程序目录。 .. contents:: :local: @@ -13,11 +13,11 @@ 重命名或重新定位应用程序目录 ================================================ -如果你想要重命名应用程序目录或者甚至将其移动到服务器上的项目根目录之外的其他位置,请打开主 **app/Config/Paths.php** 文件,并在 ``$appDirectory`` 变量中设置一个 *完整的服务器路径* (约第44行): +如果你想重命名应用程序目录，甚至将其移动到服务器上除项目根目录外的不同位置，请打开你的主 **app/Config/Paths.php** 文件，并在 ``$appDirectory`` 变量中（大约在第 44 行）设置 *完整的服务器路径*： .. literalinclude:: managing_apps/001.php -你需要修改项目根目录中的另外两个文件,以便它们可以找到 **Paths** 配置文件: +你还需要修改项目根目录中的两个额外文件，以便它们能够找到 **Paths** 配置文件： - **spark** 运行命令行应用程序。 @@ -31,12 +31,12 @@ .. _running-multiple-app: -使用一个 CodeIgniter 安装运行多个应用程序 +使用单个 CodeIgniter 安装运行多个应用程序 =============================================================== -如果你想共享一个公共的 CodeIgniter 框架安装来管理几个不同的应用程序,只需将位于应用程序目录内的所有目录都放入自己的(子)目录即可。 +如果你想共享一个通用的 CodeIgniter 框架安装来管理几个不同的应用程序，只需将位于应用程序目录中的所有目录放入它们自己的（子）目录中。 -例如,假设你要创建两个名为 **foo** 和 **bar** 的应用程序。你可以像这样组织应用程序项目目录: +例如，假设你要创建两个名为 **foo** 和 **bar** 的应用程序。你可以这样构建应用程序项目目录结构： .. code-block:: text @@ -62,7 +62,7 @@ composer.json composer.lock -.. note:: 如果你从 Zip 文件安装 CodeIgniter,目录结构将是: +.. note:: 如果你从 Zip 文件安装 CodeIgniter，目录结构将如下所示： .. code-block:: text @@ -70,16 +70,16 @@ bar/ codeigniter4/system/ -这将有两个应用程序 **foo** 和 **bar**,都有标准的应用程序目录和 **public** 文件夹,并共享一个公共的 **codeigniter4/framework**。 +这样就有两个应用程序 **foo** 和 **bar**，它们都拥有标准的应用程序目录和一个 **public** 文件夹，并共享一个通用的 **codeigniter4/framework**。 -每个应用程序内部的 **app/Config/Paths.php** 中的 ``$systemDirectory`` 变量将被设置为指向共享的公共 **codeigniter4/framework** 文件夹: +每个应用程序内部 **app/Config/Paths.php** 文件中的 ``$systemDirectory`` 变量将被设置为指向共享的通用 **codeigniter4/framework** 文件夹： .. literalinclude:: managing_apps/005.php -.. note:: 如果你从 Zip 文件安装 CodeIgniter, ``$systemDirectory`` 将是 ``__DIR__ . '/../../../codeigniter4/system'``。 +.. note:: 如果你从 Zip 文件安装 CodeIgniter，``$systemDirectory`` 将是 ``__DIR__ . '/../../../codeigniter4/system'``。 -并修改每个应用程序内部的 **app/Config/Constants.php** 中的 ``COMPOSER_PATH`` 常量: +并且需要修改每个应用程序内部 **app/Config/Constants.php** 文件中的 ``COMPOSER_PATH`` 常量： .. literalinclude:: managing_apps/004.php -只有在你更改应用程序目录时,请参阅 :ref:`renaming-app-directory` 并修改 **index.php** 和 **spark** 中的路径。 +仅当你更改应用程序目录时，请参考 :ref:`renaming-app-directory` 并修改 **index.php** 和 **spark** 中的路径。 diff --git a/source/general/modules.rst b/source/general/modules.rst index 0b6a1c7b3..c09c5d355 100755 --- a/source/general/modules.rst +++ b/source/general/modules.rst @@ -2,11 +2,11 @@ 代码模块 ############ -CodeIgniter 支持一种代码模块化形式,以帮助你创建可重用的代码。模块通常围绕特定主题展开,可以认为是你更大的应用程序中的微型应用程序。 +CodeIgniter 支持一种代码模块化形式，帮助你创建可重用的代码。模块通常围绕特定主题展开，可以看作是大型应用程序中的小型应用程序。 -框架支持的任何标准文件类型都受支持,如控制器、模型、视图、配置文件、辅助函数、语言文件等。模块可以包含尽可能少或多的这些文件。 +支持框架内的任何标准文件类型，如控制器、模型、视图、配置文件、辅助函数、语言文件等。模块可以包含你想要的任意数量或任意少的这些文件。 -如果你想将一个模块创建为 Composer 包，请参阅 :doc:`../extending/composer_packages`。 +如果要创建 Composer 包形式的模块，请参阅 :doc:`../extending/composer_packages`。 .. contents:: :local: @@ -16,9 +16,12 @@ CodeIgniter 支持一种代码模块化形式,以帮助你创建可重用的代 命名空间 ********** -模块功能的核心元素来自 CodeIgniter 使用的 :doc:`兼容 PSR-4 的自动加载 <../concepts/autoloader>`。虽然任何代码都可以使用 PSR-4 自动加载器和命名空间,但充分利用模块的主要方法是为你的代码添加命名空间并将其添加到 **app/Config/Autoload.php** 中的 ``$psr4`` 属性。 +模块功能的核心元素来自 CodeIgniter 使用的 :doc:`PSR-4 兼容的自动加载 <../concepts/autoloader>`。 +虽然任何代码都可以使用 PSR-4 自动加载和命名空间，但要充分利用模块，主要方法是为代码添加命名空间， +并将其添加到 **app/Config/Autoload.php** 的 ``$psr4`` 属性中。 -例如,假设我们想保留一个简单的博客模块,以便在应用程序之间重用。我们可以创建一个文件夹,名为 Acme,来存储所有的模块。我们将它放在主项目根目录中的 **app** 目录旁边:: +例如，假设我们想要创建一个可以在应用程序之间重用的简单博客模块。我们可以创建一个以公司名称 Acme 命名的文件夹来存储所有模块。 +我们将其直接放在主项目根目录的 **app** 目录旁边:: acme/ // 新模块目录 app/ @@ -27,13 +30,14 @@ CodeIgniter 支持一种代码模块化形式,以帮助你创建可重用的代 tests/ writable/ -打开 **app/Config/Autoload.php** 并将 ``Acme\Blog`` 命名空间添加到 ``$psr4`` 数组属性: +打开 **app/Config/Autoload.php**，将 ``Acme\Blog`` 命名空间添加到 ``$psr4`` 数组属性中： .. literalinclude:: modules/001.php -现在设置好后,我们可以通过 ``Acme\Blog`` 命名空间访问 **acme/Blog** 文件夹中的任何文件。仅此一点就解决了模块工作所需的 80%,所以你应该确保熟悉命名空间并熟练使用它们。通过所有定义的命名空间会自动扫描几种文件类型 - 使用模块的关键组成部分。 +现在设置完成，可以通过 ``Acme\Blog`` 命名空间访问 **acme/Blog** 文件夹内的任何文件。仅此一项就满足了模块正常工作所需的 80% 功能， +因此你需要熟悉命名空间并习惯使用它们。多种文件类型将通过所有已定义的命名空间自动扫描 - 这是使用模块的关键要素。 -模块中的常见目录结构将模拟主应用程序文件夹:: +模块内的常见目录结构将模仿主应用程序文件夹:: acme/ Blog/ @@ -49,15 +53,16 @@ CodeIgniter 支持一种代码模块化形式,以帮助你创建可重用的代 Models/ Views/ -当然,没有什么能强制你使用这个确切的结构,你应该以最适合模块的方式组织它,省略不需要的目录,为实体、接口或存储库等创建新目录。 +当然，并没有强制要求你必须完全照搬这种结构，你应该以最适合模块的方式组织它， +比如省略不需要的目录，为实体（Entities）、接口（Interfaces）或仓库（Repositories）等创建新目录。 *************************** 自动加载非类文件 *************************** -通常,你的模块不仅包含 PHP 类,还包含像程序函数、引导文件、模块常量文件等通常不会像加载类那样加载的文件。一种方法是在使用文件位置的开头 ``require`` 这些文件。 +你的模块通常不仅包含 PHP 类，还会包含过程式函数、引导文件、模块常量文件等，这些文件通常不像类那样被（自动）加载。处理这种情况的一种方法是，在需要使用这些文件的文件开头，直接使用 ``require`` 引入它们。 -CodeIgniter 提供的另一种方法是像自动加载类一样自动加载这些 *非类* 文件。我们需要做的就是提供这些文件路径的列表,并将它们包含在 **app/Config/Autoload.php** 文件的 ``$files`` 属性中。 +CodeIgniter 提供的另一种方法是自动加载这些 *非类* 文件，就像自动加载类一样。我们只需要提供这些文件的路径列表，并将它们包含在 **app/Config/Autoload.php** 文件的 ``$files`` 属性中即可。 .. literalinclude:: modules/002.php @@ -67,34 +72,38 @@ CodeIgniter 提供的另一种方法是像自动加载类一样自动加载这 自动发现 ************** -通常,你需要指定要包含的文件的完全命名空间,但是可以通过自动发现许多不同类型的文件来配置 CodeIgniter,从而使将模块集成到应用程序中更简单,包括: +很多时候，你需要为要包含的文件指定完整的命名空间，但 CodeIgniter 可以配置为通过自动发现多种不同的文件类型， +使模块集成到应用程序中更简单，包括： -- :doc:`Events <../extending/events>` -- :doc:`Filters <../incoming/filters>` +- :doc:`事件 <../extending/events>` +- :doc:`过滤器 <../incoming/filters>` - :ref:`registrars` -- :doc:`Route files <../incoming/routing>` -- :doc:`Services <../concepts/services>` +- :doc:`路由文件 <../incoming/routing>` +- :doc:`服务 <../concepts/services>` -这在文件 **app/Config/Modules.php** 中配置。 +这是在 **app/Config/Modules.php** 文件中配置的。 -自动发现系统通过扫描在 **Config/Autoload.php** 和 Composer 包中定义的 psr4 命名空间下的特定目录和文件来工作。 +自动发现系统通过扫描在 **Config/Autoload.php** 和 Composer 包中定义的 psr4 命名空间中的特定目录和文件来工作。 -例如,发现过程将在路径中查找可以发现的项,并应该找到 **acme/Blog/Config/Routes.php** 中的 routes 文件。 +发现过程将在该路径上查找可发现的项目，例如，应该找到位于 **acme/Blog/Config/Routes.php** 的路由文件。 启用/禁用发现 ======================= -你可以通过系统中的 ``$enabled`` 类变量打开或关闭所有自动发现。False 将禁用所有发现,优化性能,但会消除模块和 Composer 包的特殊功能。 +可以使用 ``$enabled`` 类变量开启或关闭系统中的所有自动发现。False 将禁用所有发现， +优化性能，但会失去模块和 Composer 包的特殊功能。 -指定要发现的项 +指定发现项目 ======================= -使用 ``$aliases`` 选项,你可以指定要自动发现的项。如果不存在该项,则不会为该项执行自动发现,但数组中的其他项仍将被发现。 +使用 ``$aliases`` 选项，可以指定哪些项目被自动发现。如果项目不存在， +则不会对该项目进行自动发现，但数组中的其他项目仍将被发现。 -发现和 Composer +发现与 Composer ====================== -使用 PSR-4 命名空间通过 Composer 安装的包也将默认被发现。使用 PSR-0 命名空间的包将不会被检测到。 +通过 Composer 使用 PSR-4 命名空间安装的包默认也会被发现。 +PSR-0 命名空间的包将不会被检测到。 .. _modules-specify-composer-packages: @@ -103,35 +112,37 @@ CodeIgniter 提供的另一种方法是像自动加载类一样自动加载这 .. versionadded:: 4.3.0 -为避免花时间扫描不相关的 Composer 包,你可以通过编辑 **app/Config/Modules.php** 中的 ``$composerPackages`` 变量手动指定要发现的包: +为避免浪费时间扫描不相关的 Composer 包，可以通过编辑 **app/Config/Modules.php** 中的 ``$composerPackages`` 变量手动指定要发现的包： .. literalinclude:: modules/013.php -或者,你可以指定要从发现中排除的包。 +或者，可以指定要从发现中排除的包。 .. literalinclude:: modules/014.php 禁用 Composer 包发现 ---------------------------------- -如果你不希望在查找文件时扫描 Composer 的所有已知目录,可以通过编辑 **app/Config/Modules.php** 中的 ``$discoverInComposer`` 变量将其关闭: +如果在定位文件时不希望扫描 Composer 的所有已知目录，可以通过编辑 **app/Config/Modules.php** 中的 ``$discoverInComposer`` 变量将其关闭： .. literalinclude:: modules/004.php ****************** -使用文件 +文件操作 ****************** -本节将查看每种文件类型(控制器、视图、语言文件等)以及如何在模块中使用它们。用户指南的相关位置已对其中一些信息进行了更详细的描述,但在此重复以更容易掌握所有部分的关系。 +本节将介绍各种文件类型（如控制器、视图、语言文件等）及其在模块中的使用方法。尽管其中部分内容在用户指南的相关章节中有更详细的说明，但我们仍在此处进行了重述，以便你能更轻松地理解所有组件是如何协同工作的。 路由 ====== -默认情况下,模块内会自动扫描 :doc:`路由 <../incoming/routing>`。可以在上面描述的 **Modules** 配置文件中将其关闭。 +默认情况下，模块内的 :doc:`路由 <../incoming/routing>` 会被自动扫描。可以在上述 **Modules** 配置文件中关闭此功能。 -.. note:: 由于文件被包含到当前作用域中,因此 ``$routes`` 实例已为你定义。如果尝试重新定义该类,则会导致错误。 +.. note:: 由于文件被包含到当前作用域中，``$routes`` 实例已经为你定义。 + 如果尝试重新定义该类，将导致错误。 -使用模块时,如果应用程序中的路由包含通配符,这可能是一个问题。在这种情况下,请参阅 :ref:`routing-priority`。 +使用模块时，如果应用程序中的路由包含通配符可能会出现问题。 +在这种情况下，请参阅 :ref:`routing-priority`。 .. _modules-filters: @@ -140,101 +151,115 @@ CodeIgniter 提供的另一种方法是像自动加载类一样自动加载这 .. deprecated:: 4.4.2 -.. note:: 此功能已被弃用。请改用 :ref:`registrars`，如下所示： +.. note:: 此功能已弃用。请改用 :ref:`registrars`，如下所示： .. literalinclude:: modules/015.php -默认情况下,模块内会自动扫描 :doc:`过滤器 <../incoming/filters>`。可以在上面描述的 **Modules** 配置文件中将其关闭。 +默认情况下，模块内的 :doc:`过滤器 <../incoming/filters>` 会被自动扫描。 +可以在上述 **Modules** 配置文件中关闭此功能。 -.. note:: 由于文件被包含到当前作用域中,因此 ``$filters`` 实例已为你定义。如果尝试重新定义该类,则会导致错误。 +.. note:: 由于文件被包含到当前作用域中，``$filters`` 实例已经为你定义。 + 如果尝试重新定义该类，将导致错误。 -在模块的 **Config/Filters.php** 文件中,你需要定义使用的过滤器的别名: +在模块的 **Config/Filters.php** 文件中，需要定义所使用过滤器的别名： .. literalinclude:: modules/005.php 控制器 =========== -**app/Controllers** 目录之外的控制器无法通过 URI 检测自动路由,而必须在 Routes 文件本身中指定: +主 **app/Controllers** 目录外的控制器无法通过 URI 检测自动路由， +但必须在 Routes 文件本身中指定： .. literalinclude:: modules/006.php -为了减少这里所需的输入量, **group** 路由功能很有用: +为减少此处所需的输入量，**group** 路由功能很有帮助： .. literalinclude:: modules/007.php 配置文件 ============ -使用配置文件时不需要特殊更改。这些仍然是命名空间类,并使用 ``new`` 命令加载: +使用配置文件时不需要特殊更改。这些仍然是带命名空间的类，使用 ``new`` 命令加载： .. literalinclude:: modules/008.php -无论何时使用始终可用的 :php:func:`config()` 函数，并将一个短类名传递给它，配置文件都会被自动发现。 +在使用始终可用的 :php:func:`config()` 函数并向其传递短类名时，配置文件会被自动发现。 -.. note:: 我们不建议在模块中使用相同的短类名。需要覆盖或添加 **app/Config/** 中已知配置的模块应使用 :ref:`Implicit Registrars `。 +.. note:: 我们不建议你在模块中使用相同的短类名。 + 需要覆盖或添加到 **app/Config/** 中已知配置的模块应使用 :ref:`registrars`。 -.. note:: 在 v4.4.0 之前，即使你指定了一个完全限定的类名，如 ``config(\Acme\Blog\Config\Blog::class)``，``config()`` 仍会在 **app/Config/** 中查找文件，只要存在与短类名相同的类。在 v4.4.0 中修复了这个行为，并返回指定的实例。 +.. note:: 在 v4.4.0 之前，当存在相同短名称的类时， + 即使指定像 ``config(\Acme\Blog\Config\Blog::class)`` 这样的完全限定类名， + ``config()`` 也会在 **app/Config/** 中查找文件。 + 此行为已在 v4.4.0 中修复，并返回指定的实例。 迁移 ========== -定义命名空间中的迁移文件将被自动发现。跨所有命名空间找到的所有迁移将在每次运行时都执行。 +迁移文件将在定义的命名空间内自动发现。每次运行时都会执行在所有命名空间中找到的所有迁移。 -种子 -===== +数据填充 +======== -只要提供完全限定的命名空间,就可以从 CLI 和其他种子文件中调用种子文件。如果在 CLI 上调用,则需要提供双反斜杠: +只要提供完整的命名空间，填充文件就可以从 CLI 使用，也可以从其他填充文件中调用。 +如果在 CLI 上调用，需要提供双反斜杠： -For Unix: + +对于 Unix： .. code-block:: console php spark db:seed Acme\\Blog\\Database\\Seeds\\TestPostSeeder -For Windows: +对于 Windows： .. code-block:: console - php spark db:seed Acme\Blog\Database\Seeds\TestPostSeeder + php spark db:seed Acme\\Blog\\Database\\Seeds\\TestPostSeeder 辅助函数 ======== -在使用 :php:func:`helper()` 函数时,定义的命名空间内的辅助函数将被自动发现,只要它们在 **Helpers** 目录内: +使用 :php:func:`helper()` 函数时，只要位于命名空间的 **Helpers** 目录内， +辅助函数将在定义的命名空间内自动发现： .. literalinclude:: modules/009.php -你可以指定命名空间。详情请参阅 :ref:`helpers-loading-from-specified-namespace`。 +可以指定命名空间。详情请参阅 :ref:`helpers-loading-from-specified-namespace`。 语言文件 ============== -只要文件遵循与主应用程序目录相同的目录结构，在使用 :php:func:`lang()` 函数时就会从定义的命名空间自动定位语言文件。 +使用 :php:func:`lang()` 函数时，只要文件遵循与主应用程序目录相同的目录结构， +语言文件就会从定义的命名空间中自动定位。 库 ========= -库总是通过它们的完全限定类名实例化的,所以不提供特殊访问: +库总是通过其完全限定的类名实例化，因此不提供特殊访问： .. literalinclude:: modules/010.php 模型 ====== -如果你通过完全限定的类名用 ``new`` 关键字实例化模型,则不提供特殊访问: +如果通过完全限定的类名使用 ``new`` 关键字实例化模型，不提供特殊访问： .. literalinclude:: modules/011.php -每当使用始终可用的 :php:func:`model()` 函数时,都会自动发现模型文件。 +使用始终可用的 :php:func:`model()` 函数时，模型文件会被自动发现。 -.. note:: 我们不建议在模块中使用相同的短类名。 +.. note:: 我们不建议你在模块中使用相同的短类名。 -.. note:: 在 v4.4.0 之前，即使你指定了一个完全限定的类名，如 ``model(\Acme\Blog\Model\PostModel::class)``，``model()`` 也会在 **app/Models/** 中查找具有相同短名称的类的文件。有关更多信息，请参阅 :ref:`factories-passing-fully-qualified-classname` 中的注释。 +.. note:: 在 v4.4.0 之前，当存在相同短名称的类时， + 即使指定像 ``model(\Acme\Blog\Model\PostModel::class)`` 这样的完全限定类名， + ``model()`` 也会在 **app/Models/** 中查找文件。 + 有关更多信息，请参阅 :ref:`factories-passing-fully-qualified-classname` 中的说明。 视图 ===== -如 :ref:`视图 ` 文档中所述，可以使用类命名空间加载视图： +可以使用类命名空间加载视图，如 :ref:`namespaced-views` 文档中所述： .. literalinclude:: modules/012.php diff --git a/source/general/urls.rst b/source/general/urls.rst index ca6aa641b..6cebe318b 100755 --- a/source/general/urls.rst +++ b/source/general/urls.rst @@ -6,111 +6,118 @@ CodeIgniter URL :local: :depth: 2 -默认情况下,CodeIgniter 的 URL 旨在对搜索引擎和人类友好。它使用基于 **段** 的方法,而不是与动态系统同义的标准“查询字符串”方法:: +默认情况下，CodeIgniter 的 URL 设计旨在对搜索引擎友好，同时也便于人类阅读。它不使用动态系统中常见的标准“查询字符串”形式，而是采用一种基于 **分段** 的方法:: https://example.com/news/article/my_article 你可以使用 :doc:`URI 路由 ` 功能灵活地定义 URL。 -:doc:`URI库 <../libraries/uri>` 和 :doc:`URL辅助函数 <../helpers/url_helper>` 包含可以轻松使用 URI 数据的函数。 +:doc:`URI 库 <../libraries/uri>` 和 :doc:`URL 库 <../helpers/url_helper>` 包含了可以轻松处理 URI 数据的函数。 .. _urls-url-structure: URL 结构 ============= -基本 URL 仅包含主机名 +仅包含主机名的 Base URL ----------------------------------- -当你有基本 URL **https://www.example.com/** 并想象以下 URL 时:: +当你的 Base URL 为 **https://www.example.com/** 时，假设有以下 URL:: https://www.example.com/blog/news/2022/10?page=2 -我们使用以下术语: +我们使用以下术语： ========== ============================ ========================================= -术语 例子 描述 +术语 示例 描述 ========== ============================ ========================================= -基本 URL **https://www.example.com/** 基本 URL 通常表示为 **baseURL**。 -URI 路径 /blog/news/2022/10 -路由路径 /blog/news/2022/10 相对于基本 URL 的 URI 路径。它也称为 **URI 字符串**。 -查询 page=2 +Base URL **https://www.example.com/** Base URL 通常表示为 **baseURL**。 +URI path /blog/news/2022/10 +Route path /blog/news/2022/10 相对于 Base URL 的 URI 路径。 + 也称为 **URI string**。 +Query page=2 ========== ============================ ========================================= -基本 URL 包含子文件夹 +包含子文件夹的 Base URL ----------------------------- -当你有基本 URL **https://www.example.com/ci-blog/** 并想象以下 URL 时:: +当你的 Base URL 为 **https://www.example.com/ci-blog/** 时，假设有以下 URL:: https://www.example.com/ci-blog/blog/news/2022/10?page=2 -我们使用以下术语: +我们使用以下术语： ========== ==================================== ========================================= -术语 例子 描述 +术语 示例 描述 ========== ==================================== ========================================= -基本 URL **https://www.example.com/ci-blog/** 基本 URL 通常表示为 **baseURL**。 -URI 路径 /ci-blog/blog/news/2022/10 -路由路径 /blog/news/2022/10 相对于基本 URL 的 URI 路径。它也称为 **URI 字符串**。 -查询 page=2 +Base URL **https://www.example.com/ci-blog/** Base URL 通常表示为 **baseURL**。 +URI path /ci-blog/blog/news/2022/10 +Route path /blog/news/2022/10 相对于 Base URL 的 URI 路径。 + 也称为 **URI string**。 +Query page=2 ========== ==================================== ========================================= .. _urls-uri-security: -URI 安全性 -========== +URI 安全 +============ .. versionadded:: 4.4.7 .. important:: - 从 v4.4.7 版本之前升级的用户需要在 **app/Config/App.php** 中添加以下内容才能使用此功能:: + 从 v4.4.7 之前的版本升级的用户需要在 **app/Config/App.php** 中添加以下配置 + 才能使用此功能:: public string $permittedURIChars = 'a-z 0-9~%.:_\-'; -为了帮助尽量减少可能将恶意数据传递到你的应用程序的可能性，CodeIgniter 对 URI 字符串（路由路径）允许的字符相当严格。URI 只能包含以下内容： +为了帮助减少恶意数据传递到应用程序的可能性，CodeIgniter 对 URI 字符串（路由路径）中允许使用的字符有相当严格的限制。URI 只能包含下列字符： -- 字母数字文本（仅限拉丁字符） -- 波浪号：``~`` -- 百分号：``%`` -- 句点：``.`` -- 冒号：``:`` -- 下划线：``_`` -- 减号：``-`` -- 空格：`` `` +- 字母数字文本（仅限拉丁字符） +- 波浪号：``~`` +- 百分号：``%`` +- 句点：``.`` +- 冒号：``:`` +- 下划线：``_`` +- 减号：``-`` +- 空格：`` `` .. note:: - 该检查由 ``Router`` 执行。Router 获取由 ``SiteURI`` 类保存的 URL 编码值，对其进行解码，然后检查它是否包含不允许的字符串。 + 此检查由 ``Router`` 执行。Router 接收 ``SiteURI`` 类保存的 URL 编码值， + 解码后检查其是否包含不允许的字符串。 添加允许的字符 ----------------- +--------------------------- -可以通过 ``Config\App::$permittedURIChars`` 更改允许的字符。 +允许的字符可以通过 ``Config\App::$permittedURIChars`` 修改。 -如果你想在 URI 路径中使用 Unicode，请对其进行修改以允许使用这些字符。例如，如果你想使用孟加拉语字符，你需要在 **app/Config/App.php** 中设置以下值:: +如果要在 URI 路径中使用 Unicode，需要修改它以允许使用这些字符。 +例如，如果要使用孟加拉语，需要在 **app/Config/App.php** 中设置以下值:: public string $permittedURIChars = 'a-z 0-9~%.:_\-\x{0980}-\x{09ff}'; -可以在维基百科的 `Unicode block`_ 中找到完整的 Unicode 范围列表。 +完整的 Unicode 范围列表可以在维基百科的 `Unicode block`_ 中找到。 .. _Unicode block: https://en.wikipedia.org/wiki/Unicode_block .. _urls-remove-index-php: -删除 index.php 文件 +移除 index.php 文件 =========================== -当你使用 Apache Web 服务器时，默认情况下，在你的 URL 中需要 **index.php** 文件:: +当使用 Apache Web 服务器时，默认情况下，URL 中需要包含 **index.php** 文件:: example.com/index.php/news/article/my_article -如果你的服务器支持重写 URL,你可以使用 URL 重写轻松删除此文件。这由不同的服务器以不同的方式处理,但我们将在这里展示两个最常见的 Web 服务器的示例。 +如果服务器支持 URL 重写，你可以通过 URL 重写轻松移除这个文件。 +不同的服务器处理方式不同，但这里我们将展示两种最常见的 Web 服务器示例。 .. _urls-remove-index-php-apache: Apache Web 服务器 ----------------- -Apache 必须启用 *mod_rewrite* 扩展。如果是,你可以使用一些简单规则的 ``.htaccess`` 文件。这里是一个这样文件的示例,使用“否定”方法,其中重定向除指定项之外的所有内容: +Apache 必须启用 *mod_rewrite* 扩展。如果已启用，你可以使用 ``.htaccess`` 文件配合一些简单的规则。 +以下是一个示例，它采用了“排除法”：即除了指定项之外，其他所有请求都会被重定向： .. code-block:: apache @@ -119,18 +126,18 @@ Apache 必须启用 *mod_rewrite* 扩展。如果是,你可以使用一些简单 RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.*)$ index.php/$1 [L] -在这个例子中,除了现有目录和现有文件的任何 HTTP 请求都被视为对你的 index.php 文件的请求。 +在此示例中，除了针对现有目录和现有文件的请求外，任何其他 HTTP 请求都会被视为对你的 index.php 文件的请求。 .. note:: 这些特定规则可能不适用于所有服务器配置。 -.. note:: 也要从上述规则中排除你可能需要从外界访问的任何资源。 +.. note:: 确保从上述规则中排除任何需要从外部访问的资源文件。 .. _urls-remove-index-php-nginx: Nginx ----- -在 Nginx 中,你可以定义一个位置块并使用 ``try_files`` 指令来获取与我们在上面的 Apache 配置中相同的效果: +在 Nginx 中，你可以定义一个 location 块并使用 ``try_files`` 指令来实现与上述 Apache 配置相同的效果： .. code-block:: nginx @@ -138,4 +145,5 @@ Nginx try_files $uri $uri/ /index.php$is_args$args; } -这将首先查找与 URI 匹配的文件或目录(从 root 和 alias 指令的设置构造每个文件的完整路径),然后将请求以及任何参数发送到 index.php 文件。 +这将首先查找与 URI 匹配的文件或目录（根据 root 和 alias 指令的设置构造每个文件的完整路径）， +然后将请求连同任何参数一起发送给 index.php 文件。 diff --git a/source/helpers/array_helper.rst b/source/helpers/array_helper.rst index bed6280a7..cbf7e544c 100644 --- a/source/helpers/array_helper.rst +++ b/source/helpers/array_helper.rst @@ -1,8 +1,8 @@ -############## +############ 数组辅助函数 -############## +############ -数组辅助函数提供了几个函数来简化数组的更复杂用法。它不打算重复 PHP 提供的任何现有功能 - 除非是为了极大地简化它们的用法。 +数组辅助函数提供了若干函数，旨在简化较为复杂的数组操作。它无意重复 PHP 现有的任何功能——除非这样做能大幅简化这些功能的使用。 .. contents:: :local: @@ -11,7 +11,7 @@ 加载此辅助函数 =================== -使用以下代码加载此辅助函数: +使用以下代码加载此辅助函数： .. literalinclude:: array_helper/001.php :lines: 2- @@ -19,88 +19,89 @@ 可用函数 =================== -以下函数可用: +提供以下函数： .. php:function:: dot_array_search(string $search, array $values) - :param string $search: 用点表示法描述如何在数组中搜索的字符串 - :param array $values: 要搜索的数组 - :returns: 在数组中找到的值,如果没有找到则为 null + :param string $search: 描述如何搜索数组的点号表示法字符串 + :param array $values: 要搜索的数组 + :returns: 在数组中找到的值，如果没有找到则为 null :rtype: mixed - 该方法允许你使用点表示法在数组中搜索特定键,并允许使用通配符 ``*``。给定以下数组: + 此方法允许你使用点号表示法在数组中搜索特定键，并允许使用 ``*`` 通配符。给定以下数组： .. literalinclude:: array_helper/002.php :lines: 2- - 我们可以使用搜索字符串 ``foo.buzz.fizz`` 定位 ``fizz`` 的值。类似地，可以使用 ``foo.bar.baz`` 找到 ``baz`` 的值: + 我们可以使用搜索字符串 ``foo.buzz.fizz`` 来定位 ``fizz`` 的值。同样，``baz`` 的值可以通过 ``foo.bar.baz`` 找到： .. literalinclude:: array_helper/003.php :lines: 2- - 你可以使用星号（``*``）作为通配符来替换任何段。找到时,它将搜索所有子节点直到找到它。如果你不知道值,或如果你的值具有数值索引,这很方便: + 你可以使用星号 (``*``) 作为通配符来替换任何段。当找到时，它将搜索所有子节点直到找到它。当你不知道值，或者值有数字索引时，这很方便： .. literalinclude:: array_helper/004.php :lines: 2- - 如果数组键包含点（``.``），则可以用反斜杠（``\``）转义键： + 如果数组键包含点号 (``.``)，则该键可以用反斜杠 (``\``) 转义： .. literalinclude:: array_helper/005.php :lines: 2- -.. note:: 在 v4.2.0 之前,由于一个 bug, ``dot_array_search('foo.bar.baz', ['foo' => ['bar' => 23]])`` 返回的是 ``23``。v4.2.0 及更高版本返回 ``null``。 +.. note:: 在 v4.2.0 之前，``dot_array_search('foo.bar.baz', ['foo' => ['bar' => 23]])`` 由于一个错误返回 ``23``。 + v4.2.0 及更高版本返回 ``null``。 .. php:function:: array_deep_search($key, array $array) - :param mixed $key: 目标键 - :param array $array: 要搜索的数组 - :returns: 在数组中找到的值,如果没有找到则为 null + :param mixed $key: 目标键 + :param array $array: 要搜索的数组 + :returns: 在数组中找到的值，如果没有找到则为 null :rtype: mixed - 从一个深度不确定的数组返回具有键值的元素的值 + 返回具有键值的元素在不确定深度数组中的值 .. php:function:: array_sort_by_multiple_keys(array &$array, array $sortColumns) - :param array $array: 要排序的数组(通过引用传递)。 - :param array $sortColumns: 要排序的数组键及各自的 PHP 排序标志的关联数组 - :returns: 排序是否成功 + :param array $array: 要排序的数组（按引用传递）。 + :param array $sortColumns: 要排序的数组键和相应的 PHP 排序标志作为关联数组。 + :returns: 排序是否成功。 :rtype: bool - 此方法以分层方式根据一个或多个键的值对多维数组的元素进行排序。例如,从某个模型的 ``find()`` 函数返回以下数组: + 此方法通过一个或多个键的值以分层方式对多维数组的元素进行排序。采用以下数组，可能从模型的 ``find()`` 函数返回： .. literalinclude:: array_helper/006.php :lines: 2- - 现在按两个键对该数组进行排序。请注意,该方法支持使用点表示法访问更深层数组级别中的值,但不支持通配符: + 现在通过两个键对此数组进行排序。注意，该方法支持点号表示法来访问更深层级的数组值，但不支持通配符： .. literalinclude:: array_helper/007.php :lines: 2- - 现在 ``$players`` 数组已根据每个球员 ``team`` 子数组中的 ``order`` 值排序。如果对几个球员此值相等,则这些球员将根据其 ``position`` 进行排序。结果数组为: + ``$players`` 数组现在按每个玩家的 ``team`` 子数组中的 ``order`` 值排序。如果多个玩家的此值相等，这些玩家将按他们的 ``position`` 排序。结果数组为： .. literalinclude:: array_helper/008.php :lines: 2- - 同样,该方法也可以处理对象数组。在上面的示例中,每个 ``player`` 都可能由一个数组表示,而 ``teams`` 是对象。该方法将检测每个嵌套级别中的元素类型并相应处理。 + 同样，该方法也可以处理对象数组。在上面的示例中，每个 ``player`` 可能是数组，而 ``teams`` 是对象。该方法将检测每个嵌套级别中元素的类型并相应地处理它。 .. php:function:: array_flatten_with_dots(iterable $array[, string $id = '']): array - :param iterable $array: 要打平的多维数组 - :param string $id: 可选的 ID 以添加到外部键前面。内部使用以展平键。 + :param iterable $array: 要扁平化的多维数组 + :param string $id: 可选 ID，用于添加到外部键前。内部用于扁平化键。 :rtype: array - :returns: 打平的数组 + :returns: 扁平化的数组 - 此函数使用点作为键的分隔符,将多维数组展平为单个键值对数组。 + 此函数通过使用点号作为键的分隔符，将多维数组扁平化为单键值数组。 .. literalinclude:: array_helper/009.php :lines: 2- - 检查后, ``$flattened`` 等于: + 检查后，``$flattened`` 等于： .. literalinclude:: array_helper/010.php :lines: 2- - 用户可以自己使用 ``$id`` 参数,但不需要这样做。该函数在内部使用此参数来跟踪展平后的键。如果用户将提供初始 ``$id``,它将添加到所有键前面。 + 用户可以自行使用 ``$id`` 参数，但这不是必需的。该函数在内部使用此参数来跟踪扁平化的键。如果用户提供初始 ``$id``，它将添加到所有键前。 .. literalinclude:: array_helper/011.php :lines: 2- @@ -108,24 +109,25 @@ .. php:function:: array_group_by(array $array, array $indexes[, bool $includeEmpty = false]): array :param array $array: 数据行（很可能来自查询结果） - :param array $indexes: 要按索引值分组的索引。遵循点语法 - :param bool $includeEmpty: 如果为 true，则不过滤掉 ``null`` 和 ``''`` 值 + :param array $indexes: 用于分组值的索引。遵循点号语法 + :param bool $includeEmpty: 如果为 true，``null`` 和 ``''`` 值不会被过滤掉 :rtype: array :returns: 按索引值分组的数组 - 该函数允许你按索引值将数据行分组在一起。返回的数组的深度等于作为参数传递的索引数。 + 此函数允许你按索引值将数据行分组在一起。返回数组的深度等于作为参数传递的索引数量。 - 以下示例显示了一些数据（例如从 API 加载的数据）和嵌套数组。 + 示例显示了一些数据（即从 API 加载的）具有嵌套数组。 .. literalinclude:: array_helper/012.php :lines: 2- - 我们首先想要按 ``gender`` 分组，然后按 ``hr.department`` 分组（最大深度为 2）。首先排除空值的结果如下： + 我们想首先按 ``gender`` 分组，然后按 ``hr.department`` 分组（最大深度 = 2）。 + 首先是排除空值时的结果： .. literalinclude:: array_helper/013.php :lines: 2- - 这里是相同的代码，但这次我们想要包括空值： + 这里是相同的代码，但这次我们想包含空值： .. literalinclude:: array_helper/014.php :lines: 2- diff --git a/source/helpers/cookie_helper.rst b/source/helpers/cookie_helper.rst index 310d012e5..2b601ba26 100755 --- a/source/helpers/cookie_helper.rst +++ b/source/helpers/cookie_helper.rst @@ -2,7 +2,7 @@ Cookie 辅助函数 ############### -Cookie 辅助函数文件包含了帮助处理 cookie 的函数。 +Cookie 辅助函数文件包含协助处理 Cookie 的相关函数。 .. contents:: :local: @@ -11,71 +11,82 @@ Cookie 辅助函数文件包含了帮助处理 cookie 的函数。 加载此辅助函数 =================== -使用以下代码加载此辅助函数: +使用以下代码加载此辅助函数： .. literalinclude:: cookie_helper/001.php 可用函数 =================== -以下函数可用: +提供以下函数： .. php:function:: set_cookie($name[, $value = ''[, $expire = 0[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = false[, $httpOnly = false[, $sameSite = '']]]]]]]]) - :param array|Cookie|string $name: Cookie 名称 *或* 此函数可用的所有参数的关联数组 *或* ``CodeIgniter\Cookie\Cookie`` 的实例 + :param array|Cookie|string $name: Cookie 名称 *或* 包含所有可用参数的关联数组 *或* ``CodeIgniter\Cookie\Cookie`` 实例 :param string $value: Cookie 值 - :param int $expire: 到期秒数。如果设置为 ``0`` 则 cookie 仅在浏览器打开时有效 - :param string $domain: Cookie 域名(通常:.yourdomain.com) + :param int $expire: 过期前的秒数。如果设置为 ``0``，Cookie 仅在浏览器打开期间有效 + :param string $domain: Cookie 域名（通常为：.yourdomain.com） :param string $path: Cookie 路径 - :param string $prefix: Cookie 名称前缀。如果为 ``''``,则使用 **app/Config/Cookie.php** 中的默认值 - :param bool $secure: 是否仅通过 HTTPS 发送 cookie。如果为 ``null``,则使用 **app/Config/Cookie.php** 中的默认值 - :param bool $httpOnly: 是否从 JavaScript 隐藏 cookie。如果为 ``null``,则使用 **app/Config/Cookie.php** 中的默认值 - :param string $sameSite: SameSite cookie 参数的值。如果为 ``null``,则使用 **app/Config/Cookie.php** 中的默认值 + :param string $prefix: Cookie 名称前缀。如果设置为 ``''``，则使用 **app/Config/Cookie.php** 中的默认值 + :param bool $secure: 是否仅通过 HTTPS 发送 Cookie。如果设置为 ``null``，则使用 **app/Config/Cookie.php** 中的默认值 + :param bool $httpOnly: 是否对 JavaScript 隐藏 Cookie。如果设置为 ``null``，则使用 **app/Config/Cookie.php** 中的默认值 + :param string $sameSite: SameSite Cookie 参数的值。如果设置为 ``null``，则使用 **app/Config/Cookie.php** 中的默认值 :rtype: void - .. note:: 在 v4.2.7 之前,由于一个 bug, ``$secure`` 和 ``$httpOnly`` 的默认值是 ``false``, - 从不使用 **app/Config/Cookie.php** 中的值。 + .. note:: 在 v4.2.7 之前，由于一个 bug，``$secure`` 和 ``$httpOnly`` 的默认值为 ``false``， + **app/Config/Cookie.php** 中的这些值从未被使用。 - 该辅助函数为设置浏览器 cookie 提供了更友好的语法。有关其用法的描述,请参阅 - :doc:`Response 库 `,因为此函数是 - :php:meth:`CodeIgniter\\HTTP\\Response::setCookie()` 的别名。 + 此辅助函数提供了更友好的语法来设置浏览器 Cookie。 + 有关其使用的描述，请参阅 :doc:`Response 库 `， + 因为该函数是 :php:meth:`CodeIgniter\\HTTP\\Response::setCookie()` 的别名。 - .. note:: 这个辅助函数只设置全局响应实例的浏览器 Cookie（由 ``Services::response()`` 返回）。所以，如果你创建并返回另一个响应实例（例如，如果你调用 :php:func:`redirect()`），这里设置的 Cookie 不会自动发送。 + .. note:: 此辅助函数仅将浏览器 Cookie 设置到 ``Services::response()`` 返回的全局 Response + 实例中。因此，如果你创建并返回另一个 Response 实例（例如，如果你调用 :php:func:`redirect()`）， + 此处设置的 Cookie 将不会自动发送。 .. php:function:: get_cookie($index[, $xssClean = false[, $prefix = '']]) :param string $index: Cookie 名称 - :param bool $xssClean: 是否对返回的值应用 XSS 过滤 - :param string|null $prefix: Cookie 名称前缀。如果设置为 ``''``,将使用 **app/Config/Cookie.php** 中的默认值。如果设置为 ``null``,则没有前缀 - :returns: cookie 值,如果未找到则为 null + :param bool $xssClean: 是否对返回值应用 XSS 过滤 + :param string|null $prefix: Cookie 名称前缀。如果设置为 ``''``，将使用 **app/Config/Cookie.php** 中的默认值。如果设置为 ``null``，则不使用前缀 + :returns: Cookie 值，如果未找到则返回 null :rtype: mixed - .. note:: 从 v4.2.1 开始,引入了第三个参数 ``$prefix``,并且由于一个错误修复,行为发生了一些变化。详见 :ref:`升级 `。 + .. note:: 自 v4.2.1 起，引入了第三个参数 ``$prefix``，由于 bug 修复，行为发生了一些变化。详情请参阅 :ref:`升级 `。 - 这个辅助函数为你提供了更友好的语法来获取浏览器的 Cookie。有关其使用的详细描述，请参考 :doc:`IncomingRequest 库 `，因为这个函数的行为与 :php:meth:`CodeIgniter\\HTTP\\IncomingRequest::getCookie()` 非常相似，只是它还会在前面添加你在 **app/Config/Cookie.php** 文件中设置的 ``Config\Cookie::$prefix``。 + 此辅助函数提供了更友好的语法来获取浏览器 Cookie。 + 有关其使用的详细描述，请参阅 :doc:`IncomingRequest 库 `， + 因为该函数与 :php:meth:`CodeIgniter\\HTTP\\IncomingRequest::getCookie()` 的行为非常相似， + 不同之处在于它还会在 **app/Config/Cookie.php** 文件中你设置的 + ``Config\Cookie::$prefix`` 前面加上前缀。 - .. warning:: 使用 XSS 过滤是一个不好的做法。它不能完美地防止 XSS 攻击。在视图中建议使用正确 ``$context`` 的 :php:func:`esc()`。 + .. warning:: 使用 XSS 过滤是一种不良实践。它不能完全防止 XSS 攻击。建议在视图中使用正确 ``$context`` 的 :php:func:`esc()` 函数。 .. php:function:: delete_cookie($name[, $domain = ''[, $path = '/'[, $prefix = '']]]) :param string $name: Cookie 名称 - :param string $domain: Cookie 域名(通常:.yourdomain.com) + :param string $domain: Cookie 域名（通常为：.yourdomain.com） :param string $path: Cookie 路径 - :param string $prefix: Cookie 前缀 + :param string $prefix: Cookie 名称前缀 :rtype: void - 允许你删除一个 cookie。除非你设置了自定义路径或其他值,否则只需要 cookie 的名称。 + 允许你删除一个 Cookie。除非你设置了自定义路径或其他值， + 否则只需要 Cookie 的名称即可。 .. literalinclude:: cookie_helper/002.php - 此函数与 :php:func:`set_cookie()` 其他方面相同,只是它没有 ``value`` 和 ``expire`` 参数。 + 此函数在其他方面与 :php:func:`set_cookie()` 完全相同，只是 + 它没有 ``value`` 和 ``expire`` 参数。 - 这也只是为删除全局响应实例（由 ``Services::response()`` 返回）的浏览器 Cookie 设置浏览器 Cookie。 + 这也只是将用于删除 Cookie 的浏览器 Cookie 设置到 + ``Services::response()`` 返回的全局 Response 实例中。 - .. note:: 当你使用 :php:func:`set_cookie()` 时,如果 ``value`` 设置为空字符串且 ``expire`` 设置为 ``0``,则 cookie 将被删除。 - 如果 ``value`` 设置为非空字符串且 ``expire`` 设置为 ``0``,则 cookie 仅在浏览器打开时有效。 + .. note:: 当你使用 :php:func:`set_cookie()` 时， + 如果 ``value`` 设置为空字符串且 ``expire`` 设置为 ``0``，则 Cookie 将被删除。 + 如果 ``value`` 设置为非空字符串且 ``expire`` 设置为 ``0``，则 Cookie 仅在浏览器打开期间有效。 - 你可以在第一个参数中提交值数组,也可以设置离散参数。 + 你可以在第一个参数中提交一个值数组， + 也可以设置离散的参数。 .. literalinclude:: cookie_helper/003.php @@ -86,4 +97,6 @@ Cookie 辅助函数文件包含了帮助处理 cookie 的函数。 :param string $prefix: Cookie 前缀 :rtype: bool - 检查在全局响应实例中（由 ``Services::response()`` 返回）是否存在同名的 Cookie。这是 :php:meth::`CodeIgniter\\HTTP\\Response::hasCookie()` 的别名。 + 检查在 ``Services::response()`` 返回的全局 Response 实例中 + 是否存在指定名称的 Cookie。这是 + :php:meth:`CodeIgniter\\HTTP\\Response::hasCookie()` 的别名。 diff --git a/source/helpers/date_helper.rst b/source/helpers/date_helper.rst index 7938b506f..3c9310dad 100644 --- a/source/helpers/date_helper.rst +++ b/source/helpers/date_helper.rst @@ -1,26 +1,26 @@ -############## +############ 日期辅助函数 -############## +############ -日期辅助函数文件包含了帮助处理日期的函数。 +日期辅助函数文件包含协助处理日期的函数。 .. contents:: :local: :depth: 2 -.. note:: 许多之前在 CodeIgniter 3 ``date_helper`` 中找到的函数已移到 CodeIgniter 4 的 :doc:`Time <../libraries/time>` 类中。 +.. note:: 许多之前在 CodeIgniter 3 ``date_helper`` 中的函数已经移动到 CodeIgniter 4 的 :doc:`Time <../libraries/time>` 类中。 加载此辅助函数 =================== -使用以下代码加载此辅助函数: +使用以下代码加载此辅助函数： .. literalinclude:: date_helper/001.php 可用函数 =================== -以下函数可用: +提供以下函数： .. php:function:: now([$timezone = null]) @@ -28,26 +28,26 @@ :returns: UNIX 时间戳 :rtype: int - .. note:: 建议使用 :doc:`Time <../libraries/time>` 类。使用 ``Time::now()->getTimestamp()`` 来获取当前的 UNIX 时间戳。 + .. note:: 推荐改为使用 :doc:`Time <../libraries/time>` 类。使用 ``Time::now()->getTimestamp()`` 获取当前 UNIX 时间戳。 - 如果未提供时区,它将通过 ``time()`` 返回当前的 UNIX 时间戳。 + 如果没有提供时区，将通过 ``time()`` 返回当前 UNIX 时间戳。 .. literalinclude:: date_helper/002.php - 如果提供任何 PHP 支持的时区,它将返回一个由时差偏移的时间戳。它与当前的 UNIX 时间戳不同。 + 如果提供了任何 PHP 支持的时区，它将返回一个根据时差偏移后的时间戳。这与当前的（标准）UNIX 时间戳不同。 - 如果你不打算将主时间参考设置为任何其他 PHP 支持的时区(如果你运行一个允许每个用户设置自己的时区设置的站点,通常会这样做),那么使用这个函数不会比 PHP 的 ``time()`` 函数有更多的好处。 + 如果你不打算将主时间基准设置为其他 PHP 支持的时区（通常只有在运行允许用户自定义时区的网站时才会这样做），那么使用此函数相比 PHP 原生的 ``time()`` 函数并没有任何优势。 .. php:function:: timezone_select([$class = '', $default = '', $what = \DateTimeZone::ALL, $country = null]) - :param string $class: 可选的要应用于选择字段的类 + :param string $class: 应用于选择字段的可选类 :param string $default: 初始选择的默认值 - :param int $what: DateTimeZone 类常量(参见 `listIdentifiers `_) - :param string $country: 一个与 ISO 3166-1 兼容的两字母国家代码(参见 `listIdentifiers `_) + :param int $what: DateTimeZone 类常量（参见 `listIdentifiers `_） + :param string $country: 两位字母的 ISO 3166-1 兼容的国家代码（参见 `listIdentifiers `_） :returns: 预格式化的 HTML 选择字段 :rtype: string - 生成可用时区的 `select` 表单字段(可选择通过 ``$what`` 和 ``$country`` 过滤)。 - 你可以提供一个选项 class 以方便格式化应用于字段,以及一个默认选择值。 + 生成一个包含可用时区的 `select` 表单字段（即下拉菜单，可根据 ``$what`` 和 ``$country`` 参数进行筛选）。 + 你可以提供一个 CSS 类应用到该字段以简化样式设置，同时也可以指定一个默认选中值。 .. literalinclude:: date_helper/003.php diff --git a/source/helpers/filesystem_helper.rst b/source/helpers/filesystem_helper.rst index 8328ce533..78ce04798 100755 --- a/source/helpers/filesystem_helper.rst +++ b/source/helpers/filesystem_helper.rst @@ -2,7 +2,7 @@ 文件系统辅助函数 ################# -文件系统辅助函数文件包含了帮助处理文件和目录的函数。 +文件系统辅助函数文件包含用于处理文件和目录的函数。 .. contents:: :local: @@ -11,38 +11,41 @@ 加载此辅助函数 =================== -使用以下代码加载此辅助函数: +使用以下代码加载此辅助函数： .. literalinclude:: filesystem_helper/001.php 可用函数 =================== -以下函数可用: +提供以下函数： .. php:function:: directory_map($sourceDir[, $directoryDepth = 0[, $hidden = false]]) :param string $sourceDir: 源目录路径 - :param int $directoryDepth: 遍历的目录深度(``0`` = 完全递归, ``1`` = 当前目录,等等) + :param int $directoryDepth: 需遍历的目录深度（``0`` = 完全递归，``1`` = 仅当前目录，以此类推） :param bool $hidden: 是否包含隐藏路径 :returns: 文件数组 :rtype: array - 示例: + 示例： .. literalinclude:: filesystem_helper/002.php .. note:: 路径几乎总是相对于你的主 **index.php** 文件。 - 包含在目录中的子文件夹也将被映射。如果你希望控制递归深度,可以使用第二个参数(整数)。深度为 ``1`` 只会映射顶级目录: + 目录中包含的子文件夹也会被映射。如果要控制递归深度， + 可以使用第二个参数（整数）来实现。深度为 ``1`` 时只映射顶级目录： .. literalinclude:: filesystem_helper/003.php - 默认情况下,返回的数组中不包括隐藏文件,跳过隐藏目录。要覆盖此行为,可以将第三个参数设置为 ``true`` (布尔值): + 默认情况下，返回的数组中不会包含隐藏文件，并且会跳过隐藏目录。 + 要覆盖此行为，可以将第三个参数设置为 ``true``（布尔值）： .. literalinclude:: filesystem_helper/004.php - 每个文件夹名称将是一个数组索引,其包含的文件将以数字索引。这里是一个典型数组的示例:: + 每个文件夹名称将作为数组索引，而其包含的文件将进行数字索引。 + 这是一个典型数组的示例:: Array ( [libraries] => Array @@ -71,111 +74,120 @@ ) ) - 如果未找到结果,它将返回一个空数组。 + 如果未找到结果，将返回一个空数组。 .. php:function:: directory_mirror($original, $target[, $overwrite = true]) - :param string $original: 原始源目录 - :param string $target: 目标目的目录 - :param bool $overwrite: 是否在冲突时覆盖单个文件 + :param string $original: 源目录 + :param string $target: 目标目录 + :param bool $overwrite: 冲突时是否覆盖单个文件 - 递归复制源目录的文件和目录到目标目录,即“镜像”其内容。 + 递归地将源目录的文件和目录复制到目标目录中，即"镜像"其内容。 - 例子: + 示例： .. literalinclude:: filesystem_helper/005.php - 你可以通过第三个参数选择更改覆盖行为。 + 可以选择通过第三个参数更改覆盖行为。 .. php:function:: write_file($path, $data[, $mode = 'wb']) :param string $path: 文件路径 :param string $data: 要写入文件的数据 :param string $mode: ``fopen()`` 模式 - :returns: 如果写入成功则为 ``true``,如果有错误则为 ``false`` + :returns: 写入成功时返回 ``true``，出错时返回 ``false`` :rtype: bool - 将数据写入路径中指定的文件。如果文件不存在,则该函数将创建它。 + 将数据写入路径中指定的文件。如果文件不存在，函数将创建它。 - 例子: + 示例： .. literalinclude:: filesystem_helper/006.php - 你可以通过第三个参数可选地设置写入模式: + 可以选择通过第三个参数设置写入模式： .. literalinclude:: filesystem_helper/007.php - 默认模式为 ``'wb'``。写入模式选项请参阅 PHP 用户指南的 `fopen() `。 + 默认模式是 ``'wb'``。有关模式选项，请参阅 PHP 手册中的 `fopen() `_。 - .. note:: 为了使此函数能够将数据写入文件,必须设置其权限以使其可写。如果文件不存在,则包含它的目录必须可写。 + .. note:: 为使此函数能够将数据写入文件，其权限必须设置为可写。 + 如果文件尚不存在，则包含它的目录必须可写。 - .. note:: 该路径是相对于你的主站点 **index.php** 文件,而不是你的控制器或视图文件。CodeIgniter 使用前端控制器,因此路径始终相对于主站点 index。 + .. note:: 路径是相对于主站点的 **index.php** 文件，而不是相对于 + 控制器或视图文件。CodeIgniter 使用前端控制器，因此路径 + 始终是相对于主站点索引的。 - .. note:: 此函数在写入文件时对该文件进行排他锁定。 + .. note:: 此函数在写入文件时会获取文件的独占锁。 .. php:function:: delete_files($path[, $delDir = false[, $htdocs = false[, $hidden = false]]]) :param string $path: 目录路径 - :param bool $delDir: 是否也删除目录 + :param bool $delDir: 是否同时删除目录 :param bool $htdocs: 是否跳过删除 .htaccess 和索引页面文件 - :param bool $hidden: 是否也删除隐藏文件(以句点开头的文件) - :returns: 成功为 ``true``,错误为 ``false`` + :param bool $hidden: 是否同时删除隐藏文件（以点开头的文件） + :returns: 成功时返回 ``true``，出错时返回 ``false`` :rtype: bool - 删除提供的路径中包含的所有文件。 + 删除所提供路径中包含的所有文件。 - 例子: + 示例： .. literalinclude:: filesystem_helper/008.php - 如果第二个参数设置为 ``true``,则提供的根路径中包含的任何目录也将被删除。 + 如果第二个参数设置为 ``true``，所提供根路径中包含的任何目录也将被删除。 - 例子: + 示例： .. literalinclude:: filesystem_helper/009.php - .. note:: 文件必须可写或由系统拥有才能被删除。 + .. note:: 文件必须可写或属于系统所有才能被删除。 .. php:function:: get_filenames($sourceDir[, $includePath = false[, $hidden = false[, $includeDir = true]]]) :param string $sourceDir: 目录路径 - :param bool|null $includePath: 是否将路径作为文件名的一部分包含;false 不包含路径,null 包含相对于 ``$sourceDir`` 的路径,true 包含完整路径 - :param bool $hidden: 是否包含隐藏文件(以句点开头的文件) + :param bool|null $includePath: 是否将路径作为文件名的一部分；false 表示不包含路径，null 表示相对于 ``$sourceDir`` 的路径，true 表示完整路径 + :param bool $hidden: 是否包含隐藏文件（以点开头的文件） :param bool $includeDir: 是否在数组输出中包含目录 :returns: 文件名数组 :rtype: array - 获取一个服务器路径作为输入,返回一个包含其中包含的所有文件名的数组。通过将第二个参数设置为 'relative' 获取相对路径,或任何其他非空值以获取完整文件路径,可以选择将文件路径添加到文件名中。 + 接收服务器路径作为输入，并返回包含其中所有文件名称的数组。 + 可以选择将文件路径添加到文件名中，方法是将第二个参数设置为 'relative' + 以获取相对路径，或设置为任何其他非空值以获取完整文件路径。 - .. note:: 在 v4.4.4 之前，由于一个错误，这个函数并未跟随文件夹的符号链接。 + .. note:: 在 v4.4.4 版本之前，由于一个 bug，此函数不会跟随符号链接文件夹。 - 示例: + 示例： .. literalinclude:: filesystem_helper/010.php .. php:function:: get_dir_file_info($sourceDir[, $topLevelOnly = true]) :param string $sourceDir: 目录路径 - :param bool $topLevelOnly: 是否仅查看指定的目录(不包括子目录) - :returns: 包含有关提供目录内容信息的数组 + :param bool $topLevelOnly: 是否仅查看指定目录（排除子目录） + :returns: 包含所提供目录内容信息的数组 :rtype: array - 读取指定的目录并构建一个包含文件名、文件大小、日期和权限的数组。仅当通过将第二个参数设置为 false 强制时,才读取指定路径中包含的子文件夹,因为这可能是一个密集操作。 + 读取指定目录并构建包含文件名、文件大小、日期和权限的数组。 + 只有通过将第二个参数发送为 false 来强制读取指定路径中包含的子文件夹， + 因为这可能是一个密集的操作。 - 示例: + 示例： .. literalinclude:: filesystem_helper/011.php .. php:function:: get_file_info($file[, $returnedValues = ['name', 'server_path', 'size', 'date']]) :param string $file: 文件路径 - :param array|string $returnedValues: 要作为数组或逗号分隔字符串返回的信息类型 - :returns: 包含指定文件的信息的数组,失败为 false + :param array|string $returnedValues: 要返回的信息类型（可作为数组或逗号分隔的字符串传递） + :returns: 包含指定文件信息的数组，失败时返回 false :rtype: array - 根据文件和路径,返回(可选地) *名称*、*路径*、*大小* 和 *修改日期* 信息属性。第二个参数允许你明确声明你想要返回的信息。 + 给定文件和路径，返回（可选）文件的 *名称*、*路径*、*大小* 和 *修改日期* + 信息属性。第二个参数允许明确声明要返回的信息。 - 有效的 ``$returnedValues`` 选项有:``name``、``size``、``date``、``readable``、``writeable``、``executable`` 和 ``fileperms``。 + 有效的 ``$returnedValues`` 选项是：``name``、``size``、``date``、``readable``、``writeable``、 + ``executable`` 和 ``fileperms``。 .. php:function:: symbolic_permissions($perms) @@ -183,7 +195,7 @@ :returns: 符号权限字符串 :rtype: string - 获取数字权限(例如 `fileperms() `_ 返回的)并返回标准符号表示法的文件权限。 + 获取数值形式的权限（例如 `fileperms() `_ 返回的值），并返回文件权限的标准符号表示法。 .. literalinclude:: filesystem_helper/012.php @@ -193,7 +205,7 @@ :returns: 八进制权限字符串 :rtype: string - 获取数字权限(例如 `fileperms() `_ 返回的)并返回三字符八进制表示法的文件权限。 + 获取数值形式的权限（例如 `fileperms() `_ 返回的值），并返回文件权限的三位八进制表示法（字符串）。 .. literalinclude:: filesystem_helper/013.php @@ -201,10 +213,10 @@ :param string $file1: 第一个文件的路径 :param string $file2: 第二个文件的路径 - :returns: 两个文件是否具有相同的哈希值并存在 + :returns: 两个文件是否都存在且哈希值相同 :rtype: boolean - 比较两个文件是否相同(基于它们的 MD5 哈希)。 + 比较两个文件以查看它们是否相同（基于其 MD5 哈希值）。 .. literalinclude:: filesystem_helper/014.php @@ -215,8 +227,9 @@ :returns: 绝对路径 :rtype: string - 此函数将返回没有符号链接或相对目录结构的服务器路径。可选的第二个参数将在无法解析路径时触发错误。 + 此函数将返回一个不含符号链接或相对目录结构的服务器路径。 + 可选的第二个参数将在路径无法解析时触发错误。 - 示例: + 示例： .. literalinclude:: filesystem_helper/015.php diff --git a/source/helpers/form_helper.rst b/source/helpers/form_helper.rst index 810cd1793..a8e25894b 100755 --- a/source/helpers/form_helper.rst +++ b/source/helpers/form_helper.rst @@ -2,7 +2,7 @@ 表单辅助函数 ############ -表单辅助函数文件包含了帮助处理表单的函数。 +表单辅助函数文件包含有助于处理表单的函数。 .. contents:: :local: @@ -12,13 +12,13 @@ 配置 ************* -从 v4.3.0 开始, ``form_helper`` 函数中的空 HTML 元素(如 ````)默认为兼容 HTML5,如果你需要兼容 XHTML,必须在 **app/Config/DocTypes.php** 中将 ``$html5`` 属性设置为 ``false``。 +自 v4.3.0 起，``form_helper`` 函数中的空 HTML 元素（如 ````）默认已更改为 HTML5 兼容模式。如果需要与 XHTML 兼容，必须将 **app/Config/DocTypes.php** 中的 ``$html5`` 属性设置为 ``false``。 ******************* 加载此辅助函数 ******************* -使用以下代码加载此辅助函数: +使用以下代码加载此辅助函数： .. literalinclude:: form_helper/001.php @@ -26,69 +26,75 @@ 转义字段值 ********************* -你可能需要在表单元素中使用 HTML 和诸如引号之类的字符。为了安全地做到这一点,你需要使用 -:doc:`common function <../general/common_functions>` +可能需要在表单元素中使用 HTML 和引号等字符。为了安全地执行此操作，需要使用 +:doc:`通用函数 <../general/common_functions>` :php:func:`esc()`。 -考虑以下示例: +考虑以下示例： .. literalinclude:: form_helper/002.php -由于上面的字符串包含一组引号,它会导致表单中断。:php:func:`esc()` 函数将 HTML 特殊字符转换,以便可以安全使用:: +由于上述字符串包含一组引号，会导致表单损坏。 +:php:func:`esc()` 函数转换 HTML 特殊字符，使其可以安全使用:: -.. note:: 如果使用此页面上列出的任何表单辅助函数,并以关联数组的形式传递值,则表单值将自动转义,因此不需要调用此函数。只有在以字符串形式创建自己的表单元素时,才需要调用它。 +.. note:: 如果使用本页列出的任何表单辅助函数，并以关联数组形式传递值， + 表单值将自动转义，因此无需调用此函数。 + 仅在创建自己的表单元素（以字符串形式传递）时才需要使用它。 ******************* 可用函数 ******************* -以下函数可用: +提供以下函数： .. php:function:: form_open([$action = ''[, $attributes = ''[, $hidden = []]]]) - :param string $action: 表单操作/目标 URI 字符串 - :param mixed $attributes: HTML 属性,作为数组或转义的字符串 - :param array $hidden: 隐藏字段定义的数组 - :returns: 一个 HTML 表单开启标签 + :param string $action: 表单 action/目标 URI 字符串 + :param mixed $attributes: HTML 属性，作为数组或已转义的字符串 + :param array $hidden: 隐藏字段的定义数组 + :returns: HTML 表单起始标签 :rtype: string - 创建一个开启的 form 标签，其 action 的 base 使用你的 ``Config\App::$baseURL`` 值。它将可选地允许你添加表单属性和隐藏输入字段，并且将始终根据你的 **app/Config/App.php** 配置文件中的 ``$charset`` 属性添加 `accept-charset` 属性。 + 创建一个带有 URL 的表单起始标签，该 URL 基于 ``Config\App::$baseURL`` 构建。 + 可以选择添加表单属性和隐藏输入字段，并且会始终根据 + **app/Config/App.php** 配置文件中的 ``$charset`` 属性添加 `accept-charset` 属性。 - 与硬编码你自己的 HTML 相比,使用此标签的主要好处在于,如果你的 URL 改变,它允许你的站点更便携。 + 使用此标签而不是硬编码 HTML 的主要好处是，它允许你的网站在 URL 更改时具有更好的可移植性。 - 这里是一个简单的例子: + 简单示例： .. literalinclude:: form_helper/003.php - 上面的示例将创建一个指向你的站点 URL 加上 “email/send” URI 段的表单,如下:: + 以上示例将创建一个指向你的站点 URL 加上 "email/send" URI 段的表单，如下所示::
- 你也可以像下面这样添加 ``{locale}`` : + 也可以添加 ``{locale}``，如下所示： .. literalinclude:: form_helper/004.php - 上面的示例将创建一个指向你的站点 URL 加上当前请求区域设置和 “email/send” URI 段的表单,如下:: + 以上示例将创建一个指向你的站点 URL 加上当前请求语言环境和 "email/send" URI 段的表单，如下所示:: **添加属性** - 可以通过将关联数组作为第二个参数传递来添加属性,如下所示: + 可以通过向第二个参数传递关联数组来添加属性，如下所示： .. literalinclude:: form_helper/005.php - 或者,你可以将第二个参数指定为字符串: + 或者，可以将第二个参数指定为字符串： .. literalinclude:: form_helper/006.php - 上面的示例将创建一个类似以下的表单:: + 以上示例将创建一个类似如下的表单:: - 如果 :ref:`CSRF ` 过滤器已打开，``form_open()`` 将在表单开头生成 CSRF 字段。你可以通过传递 **csrf_id** 作为 ``$attribute`` 数组的一个元素来指定此字段的 ID： + 如果启用 :ref:`CSRF ` 过滤器，``form_open()`` 将在表单开头生成 CSRF 字段。 + 可以通过将 **csrf_id** 作为 ``$attributes`` 数组的元素来指定此字段的 ID： .. literalinclude:: form_helper/007.php @@ -97,22 +103,22 @@ - .. note:: 要使用 CSRF 字段的自动生成，你需要打开 **app/Config/Filters.php** 文件中的 :ref:`CSRF 过滤器 `。 - 在大多数情况下，表单页面是使用 GET 方法请求的。通常，POST/PUT/DELETE/PATCH 请求需要 CSRF 保护， - 但即使是 GET 请求，对于显示表单的页面也必须启用 CSRF 过滤器。 + .. note:: 要使用 CSRF 字段的自动生成功能，需要在 **app/Config/Filters.php** 文件中启用 :ref:`CSRF 过滤器 `。 + 在大多数情况下，表单页面使用 GET 方法请求。通常，POST/PUT/DELETE/PATCH 请求需要 CSRF 保护， + 但即使对于 GET 请求，显示表单的页面也必须启用 CSRF 过滤器。 - 如果你使用 :ref:`filters-globals` 启用 CSRF 过滤器，它将对所有请求类型生效。 - 但如果你使用 ``public array $methods = ['POST' => ['csrf']];`` 启用 CSRF 过滤器，那么在 GET 请求中不会添加隐藏的 CSRF 字段。 + 如果通过 :ref:`filters-globals` 启用 CSRF 过滤器，它将对所有请求类型有效。 + 但如果使用 ``public array $methods = ['POST' => ['csrf']];`` 启用 CSRF 过滤器，则不会在 GET 请求中添加隐藏的 CSRF 字段。 **添加隐藏输入字段** - 可以通过将关联数组作为第三个参数传递来添加隐藏字段,如下所示: + 可以通过向第三个参数传递关联数组来添加隐藏字段，如下所示： .. literalinclude:: form_helper/008.php - 你可以通过向它传递任何 false 值来跳过第二个参数。 + 可以通过向第二个参数传递任何 false 值来跳过它。 - 上面的示例将创建一个类似以下的表单:: + 以上示例将创建一个类似如下的表单:: @@ -120,34 +126,35 @@ .. php:function:: form_open_multipart([$action = ''[, $attributes = ''[, $hidden = []]]]) - :param string $action: 表单操作/目标 URI 字符串 - :param mixed $attributes: HTML 属性,作为数组或转义的字符串 - :param array $hidden: 隐藏字段定义的数组 - :returns: 一个 HTML 多部分表单开启标签 + :param string $action: 表单 action/目标 URI 字符串 + :param mixed $attributes: HTML 属性，作为数组或已转义的字符串 + :param array $hidden: 隐藏字段的定义数组 + :returns: HTML multipart 表单起始标签 :rtype: string - 此函数与上面的 :php:func:`form_open()` 完全相同,除了它添加了一个 *multipart* 属性,如果你想使用表单上传文件,这是必需的。 + 此函数与上面的 :php:func:`form_open()` 完全相同， + 只是它添加了 *multipart* 属性，如果你想使用表单上传文件，这是必需的。 .. php:function:: form_hidden($name[, $value = '']) :param string $name: 字段名称 :param string $value: 字段值 - :returns: 一个 HTML 隐藏 input 元素 + :returns: HTML 隐藏输入元素 :rtype: string - 让你生成隐藏的输入字段。你可以提交名称/值字符串以创建一个字段: + 生成隐藏输入字段。可以提交名称/值字符串来创建一个字段： .. literalinclude:: form_helper/009.php - ... 或者你可以提交一个关联数组来创建多个字段: + ... 或者可以提交关联数组来创建多个字段： .. literalinclude:: form_helper/010.php - 你也可以将关联数组传递给值字段: + 也可以向值字段传递关联数组： .. literalinclude:: form_helper/011.php - 如果你想要带有额外属性的隐藏输入字段: + 如果要创建带有额外属性的隐藏输入字段： .. literalinclude:: form_helper/012.php @@ -155,32 +162,32 @@ :param array $data: 字段属性数据 :param string $value: 字段值 - :param mixed $extra: 要作为数组或字符串添加到标记的额外属性 - :param string $type: 输入字段的类型。即,'text'、'email'、'number'等 - :returns: 一个 HTML 文本 input 元素 + :param mixed $extra: 要添加到标签的额外属性，作为数组或字面字符串 + :param string $type: 输入字段的类型。例如，'text'、'email'、'number' 等 + :returns: HTML 文本输入元素 :rtype: string - 允许你生成标准的文本输入字段。你可以至少在第一个和第二个参数中传递字段名称和值: + 生成标准文本输入字段。可以最少在第一个和第二个参数中传递字段名称和值： .. literalinclude:: form_helper/013.php - 或者你可以传递一个包含你希望表单包含的任何数据的关联数组: + 或者可以传递包含希望表单包含的任何数据的关联数组： .. literalinclude:: form_helper/014.php - 如果你想要布尔属性,请传递布尔值(``true``/``false``)。在这种情况下,布尔值无关紧要: + 如果需要布尔属性，传递布尔值（``true``/``false``）。在这种情况下，布尔值无关紧要： .. literalinclude:: form_helper/035.php - 如果你希望你的表单包含一些额外的数据,如 JavaScript,你可以将其作为第三个参数中的字符串传递: + 如果希望表单包含一些额外数据，如 JavaScript，可以在第三个参数中将其作为字符串传递： .. literalinclude:: form_helper/015.php - 或者你可以传递它作为数组: + 或者可以将其作为数组传递： .. literalinclude:: form_helper/016.php - 为了支持扩展的 HTML5 输入字段范围,你可以将输入类型作为第四个参数传递: + 为了支持扩展范围的 HTML5 输入字段，可以在第四个参数中传递输入类型： .. literalinclude:: form_helper/017.php @@ -188,96 +195,106 @@ :param array $data: 字段属性数据 :param string $value: 字段值 - :param mixed $extra: 要作为数组或字符串添加到标记的额外属性 - :returns: 一个 HTML 密码 input 元素 + :param mixed $extra: 要添加到标签的额外属性（可以是一个数组或一个字符串） + :returns: HTML 密码输入元素 :rtype: string - 此函数在所有方面与上面的 :php:func:`form_input()` 函数相同,只是它使用 “password” 输入类型。 + 此函数在所有方面都与上面的 :php:func:`form_input()` 函数相同， + 只是它使用 "password" 输入类型。 .. php:function:: form_upload([$data = ''[, $value = ''[, $extra = '']]]) :param array $data: 字段属性数据 :param string $value: 字段值 - :param mixed $extra: 要作为数组或字符串添加到标记的额外属性 - :returns: 一个 HTML 文件上传 input 元素 + :param mixed $extra: 要添加到标签的额外属性（可以是一个数组或一个字符串） + :returns: HTML 文件上传输入元素 :rtype: string - 此函数在所有方面与上面的 :php:func:`form_input()` 函数相同,只是它使用 “file” 输入类型,允许它用于上传文件。 + 此函数在所有方面都与上面的 :php:func:`form_input()` 函数相同， + 只是它使用 "file" 输入类型，允许它用于上传文件。 .. php:function:: form_textarea([$data = ''[, $value = ''[, $extra = '']]]) :param array $data: 字段属性数据 :param string $value: 字段值 - :param mixed $extra: 要作为数组或字符串添加到标记的额外属性 - :returns: 一个 HTML textarea 元素 + :param mixed $extra: 要添加到标签的额外属性（可以是一个数组或一个字符串） + :returns: HTML textarea 元素 :rtype: string - 此函数在所有方面与上面的 :php:func:`form_input()` 函数相同,只是它生成一个 “textarea” 类型。 + 此函数在所有方面都与上面的 :php:func:`form_input()` 函数相同， + 只是它生成 "textarea" 类型。 - .. note:: 与上面的示例中的 *maxlength* 和 *size* 属性不同,你将指定 *rows* 和 *cols*。 + .. note:: 在上面的示例中，需要指定 *rows* 和 *cols* 属性，而不是 *maxlength* 和 *size* 属性。 .. php:function:: form_dropdown([$name = ''[, $options = [][, $selected = [][, $extra = '']]]]) :param string $name: 字段名称 :param array $options: 要列出的选项的关联数组 - :param array $selected: 要标记为 *selected* 属性的字段列表 - :param mixed $extra: 要作为数组或字符串添加到标记的额外属性 - :returns: 一个 HTML select(下拉框) 元素 + :param array $selected: 用 *selected* 属性标记的字段列表 + :param mixed $extra: 要添加到标签的额外属性（可以是一个数组或一个字符串） + :returns: HTML select（下拉框）元素 :rtype: string - 允许你创建一个标准的下拉字段。第一个参数将包含字段的名称,第二个参数将包含选项的关联数组,第三个参数将包含你希望选中的值。你还可以通过第三个参数传递多个项的数组,辅助函数将为你创建一个多选字段。 + 创建标准下拉框字段。第一个参数将包含字段名称，第二个参数将包含选项的关联数组， + 第三个参数将包含希望选择的值。也可以通过第三个参数传递多个项目的数组， + 辅助函数将为你创建多选。 - 示例: + 示例： .. literalinclude:: form_helper/018.php - 如果你希望打开的 标签包含额外数据，如 id 属性或 JavaScript， + 可以在第四个参数中将其作为字符串传递： .. literalinclude:: form_helper/019.php - 或者你可以传入它作为数组: + 或者可以将其作为数组传递： .. literalinclude:: form_helper/020.php - 如果作为 ``$options`` 传递的数组是多维数组,那么 ``form_dropdown()`` 将使用数组键作为标签生产一个 。 + 如果作为 ``$options`` 传递的数组是多维数组，那么 + ``form_dropdown()`` 将生成一个 ，以数组键作为标签。 .. php:function:: form_multiselect([$name = ''[, $options = [][, $selected = [][, $extra = '']]]]) :param string $name: 字段名称 :param array $options: 要列出的选项的关联数组 - :param array $selected: 要标记为 *selected* 属性的字段列表 - :param mixed $extra: 要作为数组或字符串添加到标记的额外属性 - :returns: 一个 HTML 带有 multiple 属性的 select 元素 + :param array $selected: 用 *selected* 属性标记的字段列表 + :param mixed $extra: 要添加到标签的额外属性（可以是一个数组或一个字符串） + :returns: 带有 multiple 属性的 HTML select 元素 :rtype: string - 允许你创建一个标准的多选字段。第一个参数将包含字段的名称,第二个参数将包含选项的关联数组,第三个参数将包含你希望选中的值或值。 + 创建标准多选字段。第一个参数将包含字段名称，第二个参数将包含选项的关联数组， + 第三个参数将包含希望选择的值。 - 参数用法与使用上面的 :php:func:`form_dropdown()` 相同,当然字段名称需要使用 POST 数组语法,例如 foo[]。 + 参数使用与上面的 :php:func:`form_dropdown()` 相同， + 当然，字段名称需要使用 POST 数组语法，例如 foo[]。 .. php:function:: form_fieldset([$legend_text = ''[, $attributes = []]]) - :param string $legend_text: 要放入 标签中的文本 - :param array $attributes: 要在
标签上设置的属性 - :returns: 一个 HTML fieldset 开启标签 + :param string $legend_text: 要放在 标签中的文本 + :param array $attributes: 要设置在
标签上的属性 + :returns: HTML fieldset 开始标签 :rtype: string - 允许你生成 fieldset/legend 字段。 + 生成 fieldset/legend 字段。 - 示例: + 示例： .. literalinclude:: form_helper/021.php - 与其他函数类似,如果你希望设置其他属性,可以在第二个参数中提交关联数组: + 与其他函数类似，如果希望设置额外属性，可以在第二个参数中提交关联数组： .. literalinclude:: form_helper/022.php .. php:function:: form_fieldset_close([$extra = '']) - :param string $extra: 在关闭标签后要追加的任何内容, *原样* - :returns: 一个 HTML fieldset 关闭标签 + :param string $extra: 在闭合标签之后追加的任何内容（*按原样输出*） + :returns: HTML fieldset 闭合标签 :rtype: string - 产生一个关闭的 ``
`` 标签。使用此函数的唯一优点是它允许你向其传递将添加在标签下方的数据。例如 + 生成闭合 ``
`` 标签。使用此函数的唯一好处是，它可以传递数据， + 这些数据将被添加到标签下方。例如 .. literalinclude:: form_helper/023.php @@ -286,25 +303,26 @@ :param array $data: 字段属性数据 :param string $value: 字段值 :param bool $checked: 是否将复选框标记为 *checked* - :param mixed $extra: 要作为数组或字符串添加到标记的额外属性 - :returns: 一个 HTML 复选框 input 元素 + :param mixed $extra: 要添加到标签的额外属性（可以是一个数组或一个字符串） + :returns: HTML 复选框输入元素 :rtype: string - 允许你生成一个复选框字段。简单示例: + 生成复选框字段。简单示例： .. literalinclude:: form_helper/024.php - 第三个参数包含一个布尔值 true/false 以确定是否应选中该框。 + 第三个参数包含布尔值 true/false，以确定是否应该选中复选框。 - 与此辅助函数中的其他表单函数类似,你也可以在第一个参数中传递属性的关联数组: + 与此辅助函数中的其他表单函数类似，也可以向函数传递属性数组： .. literalinclude:: form_helper/025.php - 与其他函数一样,如果你希望标签包含其他数据,如 JavaScript,可以将其作为第四个参数中的字符串传递: + 与其他函数一样，如果希望标签包含如 JavaScript 等额外数据， + 可以在第四个参数中将其作为字符串传递： .. literalinclude:: form_helper/026.php - 或者你可以传递它作为数组: + 或者可以将其作为数组传递： .. literalinclude:: form_helper/027.php @@ -313,27 +331,28 @@ :param array $data: 字段属性数据 :param string $value: 字段值 :param bool $checked: 是否将单选按钮标记为 *checked* - :param mixed $extra: 要作为数组或字符串添加到标记的额外属性 - :returns: 一个 HTML 单选按钮 input 元素 + :param mixed $extra: 要添加到标签的额外属性（可以是一个数组或一个字符串） + :returns: HTML 单选输入元素 :rtype: string - 此函数在所有方面与上面的 :php:func:`form_checkbox()` 函数相同,只是它使用 “radio” 输入类型。 + 此函数在所有方面都与上面的 :php:func:`form_checkbox()` 函数相同， + 只是它使用 "radio" 输入类型。 .. php:function:: form_label([$label_text = ''[, $id = ''[, $attributes = []]]]) - :param string $label_text: 要放入