Re: Rethink CS for require_once?

On Thu, 02 Dec 2004 14:52:52 +0800, Alan Knowles <alan@akbkhome.com> wrote: > I'm kind of mixed on this - the dirname(__FILE__) is very predicatable, > however I can think of times when I have used the include_path trick to > deliberatly override PEAR package: > > eg. > DB/pgsql.php - had some serious bugs before Daniel started attacking it. > that prevented a couple of projects working. Along with sending the fix > in, I also wanted to ensure that I could continue working so I added an > extra include path, and put a fixed DB/pgsql.php in there.. > > or.. > XML_Tree_Node is really annoying to use with print_r, as the children > and attributes appear before the name - so I have a personal copy with > those elements re-ordered... (and do the same trick as above..) > > I guess it's a question about whether you reduce ??a few?? end user > gotcha's, or reduce the general flexibily offered by depending on the > include_path.. > I agree. It just feels wrong to be using dirname() for includes. Yes, it *may* solve some problems and *may* fix the phar thing (although I thought that could be fixed using an include path?), but it just seems like it's losing flexibility for little reason. > > > Regards > Alan > > Greg Beaver wrote: > > > Hi, > > > > I would like to suggest a simple and compelling change into the CS for > > require_once in PEAR packages. Currently, all internal inclusion of > > PEAR files must be done like > > > > require_once 'Relative/Package/FilePath.php'; > > > > I'd like to revisit this CS and split it into two kinds of includes: > > > > 1) inclusion of internal package files > > 2) inclusion of external package files > > > > definitions: > > 1) internal package files > > drivers > > internal extensions (PEAR_Command commands, PEAR_PackageFile_v1 > > any internal file that must not be changed (can be considered final) > > > > 2) external package files > > *any* file that is not in the package.xml > > any internal file that can be user-customized > > > > So, the new standard would be: > > > > for (1) use dirname(__FILE__) for absolute inclusion > > > > require_once dirname(__FILE__) . '/Foo/Driver.php'; > > > > This means that any supporting files must be included by parents. > > This hypothetical include from Foo/Driver.php would not be allowed: > > > > require_once dirname(dirname(__FILE__)) . '/Foo.php'; > > > > and would instead have to be included in the relative manner > > > > require_once 'Foo.php'; > > > > To be clear: the ONLY new syntax allowed would be including deeper files > > > > from Foo.php > > require_once dirname(__FILE__) . '/Foo/Driver.php'; > > require_once dirname(__FILE__) . '/Foo_Unserializer.php'; > > > > from Foo/Driver.php > > require_once dirname(__FILE__) . '/Driver/Subhelper.php'; > > require_once 'Foo_Unserializer.php'; > > > > no funny business like > > > > require_once dirname(__FILE__) . '../FooUnserializer.php'; > > > > would be allowed either. > > > > for (2) use the old way require_once 'Relative/Path/To/File.php'; > > > > Why? > > > > 1) errors caused by include_path go bye-bye > > > > phpDocumentor has run into trouble when the include_path has a version > > installed by PEAR after a version that is downloaded from sourceforge, > > mainly because of the unnecessary use of relative includes. > > > > In addition it enforces better design. If you are extending DB_mysql > > and putting it in /path/to/home/DB/mysql.php, where PEAR is in > > /usr/local/pear/DB/mysql.php, and you use include_path > > ".:/path/to/home/:/usr/local/pear" it can lead to sudden breakage > > caused by upgrading the server version, and very difficult bugs to > > trace. In addition, how many times have people suddenly gotten > > messages like: > > > > "undefined function fetchRow()" > > > > when they define a file named "DB.php" in the . directory? > > > > Anyone who wants to override Foo::factory() can either extend Foo, or > > Foo could follow the path offered by Log, and attempt to include > > user-designed drivers from a specific path first, and then from local > > directories. > > > > 2) it opens up unique possibilities with Davey's new package and other > > yet-uncoded solutions. > > > > require_once dirname(__FILE__) . '/DB/mysql.php'; > > > > will include 'phar://DB-1.6.8.phar/DB/mysql.php' if DB.php is __FILE__ > > and it was included with require_once 'phar://DB-1.6.8.phar/DB.php'; > > > > 3) performance is notably faster with absolute paths at script > > startup, although this is a distant third. I'm most concerned with > > keeping the include_path cleaner for internal files. This also makes > > include_path less of an issue for packages extracted into a non-PEAR > > environment which is *always* a good thing. > > > > For an example of clean require_once, check out Harry Fueck's Calendar > > code, which raised some flack when he proposed it. Also, check out > > the internal driver inclusion of PEAR's own PEAR_Command (uses > > dirname(__FILE__) unless the user specifies a directory where commands > > reside). > > > > Greg > > > -- Justin Patrin