Note to namespace characters

[ThomasFinnern]

User description

defining-your-namespace.md: added info about: The first character of the namespace name is restricted to "a-zA-Z_" ....

---

PR Type

Documentation

---

Description

• Added developer note about namespace character restrictions

• Clarifies first character must be "a-zA-Z_" per PHP rules

• Recommends using underscore prefix for names starting with numbers

• Notes Joomla doesn't validate during installation, errors appear at runtime

---

Diagram Walkthrough

flowchart LR
  A["Namespace documentation"] -->|Add developer note| B["Character restriction info"]
  B -->|References| C["PHP valid variable names"]
  B -->|Provides| D["Best practice recommendations"]

Loading

File Walkthrough

Relevant files

Documentation

defining-your-namespace.md Add namespace character restriction developer note              docs/general-concepts/namespaces/defining-your-namespace.md Added developer note box at end of document Explains first character restriction to "a-zA-Z_" Links to PHP documentation for valid variable names Recommends underscore prefix for names starting with numbers Notes runtime errors occur when PHP code executes +8/-1      defining-your-namespace.md Add namespace character restriction developer note              versioned_docs/version-5.4/general-concepts/namespaces/defining-your-namespace.md Added identical developer note box at end of document Explains first character restriction to "a-zA-Z_" Links to PHP documentation for valid variable names Recommends underscore prefix for names starting with numbers Notes runtime errors occur when PHP code executes +8/-1      defining-your-namespace.md Add namespace character restriction developer note              versioned_docs/version-6.0/general-concepts/namespaces/defining-your-namespace.md Added identical developer note box at end of document Explains first character restriction to "a-zA-Z_" Links to PHP documentation for valid variable names Recommends underscore prefix for names starting with numbers Notes runtime errors occur when PHP code executes +8/-1

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Add installer validation instead of documentation Instead of documenting the issue of invalid namespace names, modify the Joomla extension installer to validate them. This would prevent the installation of invalid extensions and provide immediate feedback, which is a more robust solution. Examples: docs/general-concepts/namespaces/defining-your-namespace.md [120] Joomla does not check the extension name in the installation process. However, errors are reported later when the PHP code is executed. Solution Walkthrough: Before: // Current process described by the PR's documentation // 1. Developer defines a namespace starting with a number. // namespace 1MyVendor\MyExtension; // 2. Joomla's installer runs without validation. function Installer.install(package) { // ... no check on namespace validity ... // Installation succeeds. } // 3. At runtime, PHP fails. // PHP Fatal error: '1MyVendor' is not a valid namespace name After: // Suggested process with installer validation // 1. Developer defines a namespace starting with a number. // namespace 1MyVendor\MyExtension; // 2. Joomla's installer validates the namespace. function Installer.install(package) { let namespace = getNamespaceFromManifest(package); if (!isValidNamespace(namespace)) { throw new InstallationError("Invalid namespace name. Namespaces cannot start with a number."); } // Installation is blocked, preventing runtime errors. } Suggestion importance[1-10]: 9 __ Why: This is an excellent high-level suggestion that addresses the root cause of the problem rather than just documenting a workaround, proposing a systemic fix that would significantly improve the framework's robustness.	High
General	Clarify namespace naming rules and link Clarify that each segment of a PHP namespace must start with a letter or underscore, and update the reference link to the PHP manual on constants for better context. docs/general-concepts/namespaces/defining-your-namespace.md [117-119] -Attention: The first character of the namespace name is restricted to "a-zA-Z_" with some additionals. See -[PHP valid variable names](https://www.php.net/manual/en/language.variables.basics.php) -So be careful of company or extension names beginning with a number or other restricted characters. Recommendation: Use '_' as the first character instead. +Attention: Each segment of a PHP namespace must start with a letter or an underscore. See the [PHP manual on valid names](https://www.php.net/manual/en/language.constants.syntax.php) for more details. +So be careful if your company or extension name begins with a number or other restricted character. In such cases, a recommended practice is to prefix the namespace segment with an underscore (`_`). Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies an ambiguity in the documentation and provides a more precise explanation of PHP namespace naming rules, improving the quality and accuracy of the information for developers.	Low
More