Re: Re: PEAR2 Coding standards, Autoloading and Namespaces

On Apr 6, 2008, at 8:26 AM, Greg Beaver wrote:

this is incorrect, my previous message discussed this point.

If you're referring to the using the installer, that's a non-starter for 99% of distributed PHP programs. Nobody in PHP land is going to say "download this, then setup PEAR and install packages A, B, and C." I actually brought up embedding the installer in a blog package to handle plugins and language files. I believe the exact quote was "I'm ok with that so far as you can 100% guarantee me that no part of the installation instructions involve "go to the command line and type..."". Like it or not, the people who use PEAR as a means of distributing code are all subscribed to this mailing list. Saying "use the installer" does nothing but limit our potential audience for those packages to the same list.

* The Bar class must refer to Foo with the fully qualified name, new PEAR2::Foo().

Also incorrect. One can easily do "use PEAR2::Foo;" and then use "new Foo"

Yes, that was actually his point I believe. You have to declare that you're in one namespace, then specify that you want to use a class that exists in another namespace that is actually part of the same package. Semantically, there's a disconnect there. You're viewing "namespaces" as a convenient way to alias classes. Jeff and I are looking at them as containers in which to put code.

* The relationship between Foo and Foo::Bar is not clear to automated tools (such as phpDocumentor).

Also incorrect, phpDocumentor doesn't even care or know about namespace as this is not an enforced relationship the way a java package is. Because phpDocumentor (and other tools) are general purpose PHP tools, they can't make any assumption about package, and use @package tags to make these associations explicit. Using namespace would not be difficult, and one could even use prefix (i.e. anything that is PEAR2::Foo*) quite easily, as the actual implementation of namespaces simply stores classnames as strings, with no explicit namespace information.

I believe Jeff was referring to the potential. Being able to drop @package is just one more area where namespaces could help remove duplication within code. I could definitely see it being useful for phpDocumentor to utilize any namespace declarations as packages when not explicitly set.

OK, let's assume we do put packages always within the directory. How do we handle subpackages or external helper packages? For instance, database packages have drivers. Your proposal would have a different file naming standard for subpackages from regular packages.

Actually, no it wouldn't. pear2::mdb2::MDB2 <-- namespace pear2::mdb2; class MDB2 { ... pear2::mdb2::drivers::mysql::MySQL <-- namespace pear2::mdb2::drivers::mysql; class MySQL { ...

Let's think of another example: the PEAR package and the PEAR_PackageFileManager package. These are not subpackages, but are related. Currently PEAR's files go into PEAR/ and PEAR_PackageFileManager class go into PEAR/PackageFileManager. Would you suggest the classname for a similar class be PEAR2::Pyrus_PackageFileManager::PackageFileManager or PEAR2::Pyrus::PackageFileManager::PackageFileManager?

If Jeff and I actually are on the same page (Jeff, please correct me if I'm wrong), then the latter. Though I definitely think the idea of lower-casing all package names helps provide a delineation between what portion of the name is the package and what is the class. Using the lowercase syntax, it would be: <?php namespace pear2::pyrus::packagefilemanager; class PackageFileManager { // ... code and such ... } ?>

Very quickly, we start running into 100 character classnames all for a non-issue of trying to make the directory appearance feel cleaner at the expense of code clarity and package=>classname mapping clarity.

There are two separate points here. I would hope you are not suggesting that character count should be an all consuming goal. Verify quickly packages would be littered with "$a" and "$b" variables. Conciseness should be the aim without regard to how many characters it takes to achieve it. Regarding the "non-issue" of directory appearance, it is one that I've personally run into at multiple companies who have tried to use PEAR packages. Without fail we always end up just lumping them into a ./pear/ directory because it's impossible to put each package in it's own directory. Ideally, each package would sit in its own directory inside a ./vendor/ directory so they could be maintained independently. The current PEAR structure where multiple packages can put files in the same directory actively prevents that.

PEAR users are very used to the idea that the PEAR_PackageFileManager package results in a class named PEAR_PackageFileManager in PEAR/PackageFileManager.php, and it has worked great since 1999 with no complaints since I joined PEAR in 2002.

Very quickly, then I'll move on to the problem: "because we've always done it that way" is the worst possible excuse for not changing if there is a valid reason to change. Based on your next comment, I think the issue is whether or not you believe there to be a valid reason.

I don't see a problem to be fixed here. As already noted, none of the objections you've raised are truly problems for various technical reasons (source repository already separates by directory, the use statement solves the others, automated tools for PHP at large can't depend on any organizing principle beyond what is hard-coded into the language).

The issue is that two packages can put files in the same directory. Version control systems such as Subversion and Git that allow references to outside sources expect that those sources will be contained within a particular directory. This means that if you use Text_CAPTCHA and Text_Wiki, two packages that have a high probability of being used together, you're screwed, from a version control standpoint. If the package maps to a directory and that directory contains classes this becomes much more maintainable from a version control stand point. It also has the nice side benefit of being able to explain a newbie that each package will install files within its directory. Anything in a different directory is part of a different package.

If you all feel strongly about changing this issue even after my strong objections, I suggest you follow the official path and propose an RFC to the PEAR Group for changes to the PEAR2 coding standards (which are up for review, by the way).

I'll work one up... Jeff, if you're able, I would love to have your collaboration with this. Contain me off list. -T