Uploaded image for project: 'Moodle Community Sites'
  1. Moodle Community Sites
  2. MDLSITE-6087

Require formal namespaces for any new PHP files

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Component/s: Coding style
    • Labels:

      Description

      Policy: Require formal namespaces for any new PHP files

      Since 19th June 2020, this rule applies:

      1. Formal namespaces are required for any new classes in Moodle. The following exceptions apply:
        1. there is no requirement to move existing non-namespaced classes to a namespace; and
        2. where an existing mechanism exists for loading a class, and that mechanism does not support the use of a namespaced class, the existing pseudo-namespaced prefix on the class name will be allowed.
      2. The use of a pseudo-namespace prefix on classnames is deprecated and should only be used in the above situations.
      3. The use of namespaces must conform to the following rules:
        1. Classes belonging to a namespace must be created in a classes directory inside a plugin (e.g. mod/forum/classes), or for core code, in lib/classes or subsystemdir/classes.
        2. The classname and filename for all namespaced classes must conform to the automatic class loading rules. The use of formal PHP namespaces in all new code is required.

       

      Valid examples:

      namespace mod_forum;
      class example {
      }
       
      namespace mod_forum\external;
      class example {
      }
       
      namespace core_user;
      class example {
      }

       

      No longer valid:

      class mod_forum_example {
      }
       
      class mod_forum_external_invalid {
      }
       
      class core_user_example {
      }
      

      Background

      Our coding style currently states:

      Namespaces are not required for any new code and there is no requirement to move non-namespaced classes to namespaces. If namespaces are used - they must conform to these rules.

      Classes belonging to a namespace must be created in a classes directory inside a plugin (e.g. mod/forum/classes), or for core code, in lib/classes or subsystemdir/classes.

      The classname and filename for all namespaced classes must conform to the automatic class loading rules.

      Use at most one namespace declaration per file.

      https://docs.moodle.org/dev/Coding_style#Namespaces

      Conversely, PSR-1 states:

      Code written for PHP 5.3 and after MUST use formal namespaces.

      Proposal

      I would like to propose the following replacement for this paragraph in our current coding style:

      Formal namespaces are required for any new classes in Moodle. The following exceptions apply:

      1. there is no requirement to move existing non-namespaced classes to a namespace; and
      2. where an existing mechanism exists for loading a class, and that mechanism does not support the use of a namespaced class, the existing pseudo-namespaced prefix on the class name will be allowed.

      The use of a pseudo-namespace prefix on classnames is deprecated and should only be used in the above situations.

      The use of namespaces must conform to the following rules:

      1. Classes belonging to a namespace must be created in a classes directory inside a plugin (e.g. mod/forum/classes), or for core code, in lib/classes or
        subsystemdir/classes.
      2. The classname and filename for all namespaced classes must conform to the automatic class loading rules.

      Examples

      Valid

      namespace mod_forum;
      class example {
      }
       
      namespace mod_forum\local\example;
      class foo_bar {
      }
       
      namespace mod_forum\external;
      class example {
      }
       
      namespace core;
      class example {
      }
       
      namespace core_user;
      class example {
      }
      

      No longer valid

      class mod_forum_example {
      }
       
      class mod_forum_external_invalid {
      }
       
      class core_user_example {
      }
      

      Voting

      Two voting options are proposed:

      Vote Accept

      We should accept the new wording proposed and require the use of formal PHP namespaces in all new code, with the previously accepted caveats.

      Vote Reject

      We should not make any change to the coding style with regards the use of formal PHP namespaces.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              dobedobedoh Andrew Nicols
              Reporter:
              dobedobedoh Andrew Nicols
              Participants:
              Component watchers:
              Marina Glancy, Eloy Lafuente (stronk7)
              Votes:
              0 Vote for this issue
              Watchers:
              11 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: