pear:rfc:pear2_naming_standards

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
pear:rfc:pear2_naming_standards [2008/11/07 17:15] – remove code dufuzpear:rfc:pear2_naming_standards [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 3: Line 3:
 ==== Document Information ==== ==== Document Information ====
   * Title: PEAR2 Package Naming Standard   * Title: PEAR2 Package Naming Standard
-  * Version: 0.1.0 +  * Version: 0.1.1 
-  * Status: Draft+  * Status: Defunct
   * Type: Informative Document   * Type: Informative Document
   * Wiki link: http://wiki.php.net/pear/rfc/PEAR2_Naming_Standards   * Wiki link: http://wiki.php.net/pear/rfc/PEAR2_Naming_Standards
-  * Last updated: June 23th2008+  * Last updated: December 20th2009 
 + 
 +**//This RFC is no longer under consideration, as per the PEAR Group meeting discussion on 12/20/2009.//**
  
 ==== Author(s) Information ==== ==== Author(s) Information ====
Line 28: Line 30:
 ==== Proposed Change ==== ==== Proposed Change ====
   * All namespaces are lowercased   * All namespaces are lowercased
-  * Packages should be named: pear2::<package_name>::<ClassName>+  * Packages should be named: pear2\<package_name>\<ClassName>
   * Packages own all sub-namespaces within their package and can use them however they wish   * Packages own all sub-namespaces within their package and can use them however they wish
   * All underscores (_) in the package name (i.e., everything that's lowercase) will not be translated as anything other than underscores   * All underscores (_) in the package name (i.e., everything that's lowercase) will not be translated as anything other than underscores
Line 36: Line 38:
   * Embedding PEAR1 code within an existing SVN repository is hard   * Embedding PEAR1 code within an existing SVN repository is hard
   * Currently tracking multiple PEAR packages within the same category is hard via svn:externals   * Currently tracking multiple PEAR packages within the same category is hard via svn:externals
-  * There is no differentiation between namespace and class name (i.e., in PEAR2::Pyrus::Installer, is PEAR2 a class, and what about PEAR2::Pryus?)+  * There is no differentiation between namespace and class name (i.e., in PEAR2\Pyrus\Installer, is PEAR2 a class, and what about PEAR2\Pryus?)
  
-Our current structure was born out of a need to segregate files in a logical way with no namespaces and/or packages.  Using the standard "Some_Class" notation was helpful to provide a semi-logical directory structure.  As a side effect, classes ended up with names that did not properly reflect what they did if taken outside of the PHP convention.+Our current structure was born out of a need to segregate files in a logical way with no namespaces and/or packages.  Using the standard "Some_Class" notation was helpful to provide a semi-logical directory structure.  As a side effect, classes ended up with names that did not properly reflect what they did if taken outside of the convention.
  
-For example, MDB2's Driver classes.  The class itself should be called Driver, but in order to keep all drivers in the same directory, they are named along the lines of MDB2_Driver_mysql.  The true package here is a "mysqldriver" with a relation to MDB2.  If the traditional naming scheme is continued in PEAR2 and the _ is replaced with ::, the package name will now be MDB2::Driver::mysql.  Under the proposed naming convention the wording of the names could be reworked to read more like plain English: pear2::mdb2_mysqldriver.   The fully-qualified class name would be pear2::mdb2_mysqldriver::Driver.+For example, MDB2's Driver classes.  The class itself should be called Driver, but in order to keep all drivers in the same directory, they are named along the lines of MDB2_Driver_mysql.  The true package here is a "mysqldriver" with a relation to MDB2.  If the traditional naming scheme is continued in PEAR2 and the _ is replaced with \, the package name will now be MDB2\Driver\mysql.  Under the proposed naming convention the wording of the names could be reworked to read more like plain English: pear2\mdb2_mysqldriver.   The fully-qualified class name would be pear2\mdb2_mysqldriver\Driver.
  
 As the above example demonstrates, this addresses three separate issues: As the above example demonstrates, this addresses three separate issues:
  
- It removes the legacy naming convention that inverts the noun and adjective.  That makes the package name read more like true English.  You have a "mysql driver", not a "driver mysql"+  - It removes the legacy naming convention that inverts the noun and adjective.  That makes the package name read more like true English.  You have a "mysql driver", not a "driver mysql"
-It allows the sub-package to be handled inside its own directory.  With :: being the only portion of the code that is replaced inside its own directory, this puts all of the mdb2 drivers in directories along side the mdb2 package so they can be tracked separately by version control systems such as Subversion and Git via svn:externals or git-submodules without having to first stage the code in a staging directory. +  It allows the sub-package to be handled inside its own directory.  With being the only portion of the code that is replaced inside its own directory, this puts all of the mdb2 drivers in directories along side the mdb2 package so they can be tracked separately by version control systems such as Subversion and Git via svn:externals or git-submodules without having to first stage the code in a staging directory. 
-By changing the package to lowercase it becomes immediately apparent what the instantiable class is.  This removes all ambiguity from a PEAR2::MDB2::Driver::Mysql style of naming.+  By changing the package to lowercase it becomes immediately apparent what the instantiable class is.  This removes all ambiguity from a PEAR2\MDB2\Driver\Mysql style of naming.
  
 ==Definition== ==Definition==
-* namespace - the namespace declared at the top of a file containing a class, function, or variable +  * namespace - the namespace declared at the top of a file containing a class, function, or variable 
-* fully-qualified name - the full name of a class, including its namespace+  * fully-qualified name - the full name of a class, including its namespace
  
 ==Security Considerations== ==Security Considerations==
Line 57: Line 59:
 == Possible Problems== == Possible Problems==
 This section tries to outline any possible problems within this proposal to either: This section tries to outline any possible problems within this proposal to either:
-* Outline ways that they are addressed, or +  * Outline ways that they are addressed, or 
-* Bring them up for discussion+  * Bring them up for discussion
  
-===Handling sub directory organization within a package ===+==Handling sub directory organization within a package==
 Many developers use sub-directories to organize their packages into logical groups of operation.  This becomes necessary as packages become larger.  While we would like to have developers use a modular approach for their packages along the lines of what MDB2 has done, for some packages this type of package, sub-package structure may be overkill. Many developers use sub-directories to organize their packages into logical groups of operation.  This becomes necessary as packages become larger.  While we would like to have developers use a modular approach for their packages along the lines of what MDB2 has done, for some packages this type of package, sub-package structure may be overkill.
  
 To handle multiple directories within a package, this proposal offers two solutions. To handle multiple directories within a package, this proposal offers two solutions.
-  - Each package owns all namespaces within it'package namespace.  pear2::foobar can define any additional sub-namespaces it wishes to and each sub-namespace will follow the same directory naming schema. +  - Each package owns all namespaces within its package namespace.  pear2\foobar can define any additional sub-namespaces it wishes to and each sub-namespace will follow the same directory naming schema. 
-  - The last portion of the fully-qualified name will follow traditional PEAR1 style of _ to DIRECTORY_SEPARATOR replacement.  This means that the pear2::foobar::Foo_Bar class will exist within the pear2/foobar/Foo/Bar.php file; likewise, pear2::foobar::foo:Bar_Foo translates into pear2/foobar/foo/Bar_Foo.  Put more simply, anything that has an uppercase letter in its name (i.e., any class) continues to use the traditional PEAR1 naming-to-directory mapping.+  - The last portion of the fully-qualified name will follow traditional PEAR1 style of _ to DIRECTORY_SEPARATOR replacement.  This means that the pear2\foobar\Foo_Bar class will exist within the pear2/foobar/Foo/Bar.php file; likewise, pear2\foobar\foo\Bar_Foo translates into pear2/foobar/foo/Bar/Foo.php.  Put more simply, anything that has an uppercase letter in its name (i.e., any class) continues to use the traditional PEAR1 naming-to-directory mapping.
  
 ==== Transition to new naming schemas ==== ==== Transition to new naming schemas ====
-Any new naming schema requires transition.  Whether it is replacing _ with ::, or something more involved, any change will require some effort on the part of developers.  Unfortunately, this is an issue that can not be dealt with.  The PEAR Group believes this opportunity to take advantage of the new namespace functionality for updating our naming schema to something more logical is worth any temporary inconvenience to developers while they reprogram their wetware.+Any new naming schema requires transition.  Whether it is replacing ''_'' with ''\'', or something more involved, any change will require some effort on the part of developers.  Unfortunately, this is an issue that can not be dealt with.  The PEAR Group believes this opportunity to take advantage of the new namespace functionality for updating our naming schema to something more logical is worth any temporary inconvenience to developers while they reprogram their wetware.
  
pear/rfc/pear2_naming_standards.1226078136.txt.gz · Last modified: 2017/09/22 13:28 (external edit)