[Solar-talk] Project structure layout?

[Paul M Jones]

On Nov 13, 2007, at 6:17 PM, Jeff Moore wrote:

> On Nov 13, 2007, at 8:27 AM, Paul M Jones wrote:
>
>> Comments, criticism, analysis?
>
> One of the things that I think can get lost in organizing files by  
> type is the concept of a working set of files.  For some files, you  
> always work on those files together, even if they are of different  
> types (or different roles in pear speak).  Storing them in separate  
> file system locations can make working with them slightly harder.
>
> For me, the best example of this are the unit test files.  Since  
> you almost always work on both the tests and the code under test at  
> the same time, having both files in the same directory makes  
> opening files during development slightly easier.  It also  
> highlights that relationship between the files and especially  
> highlights missing test code.
>
> Depending on the division of labor at your organization, the same  
> may be true of other kinds of related files, templates and  
> controllers, perhaps.
>
> This desirable locality of reference during development seems to  
> conflict with the need to place different kinds of files in  
> different places for the application to easily and efficiently find  
> them at run time.  If you optimize for locality of reference to  
> make development easier, it makes the code for locating those files  
> at runtime more complicated and the differences between the  
> development and production environment greater.  If you optimize to  
> make it easier for the app to locate its files, you make the system  
> harder for people to understand and work with because files that  
> are worked on at the same time are spread across several directories.

I agree with you on "keeping related files together" and the  
disparity between development-needs and runtime-needs (regarding file  
organization).  I think I presented only part of the problem  
description here, the part for the run-time needs.  Let me back-fill  
a little.

For an individual Vendor class series (think Solar, Lux, 3Hex, Zend,  
etc) I advocate keeping all the files together, in the PEAR-ish way  
we've come to accept:

     trunk/            # svn trunk for the Vendor project
         Vendor.php    # arch-class
         Vendor/       # related classes
         docs/         # documentation files
         tests/        # test series
         and-so-on/    # and so forth

The problem I'm describing arises when you combine various Vendors  
into a single project, say a website like SolarWeb.  In those cases,  
you need not only the SolarWeb stuff, but also the stuff from the  
other vendors.

What I was suggesting was an outline for how to organize those  
combined pieces for the purposes of the larger project, not how to  
organize the individual Vendor file series.  It's supposed to take  
into account just what you said above, that how the files are  
organized in development and distribution may not map 1-to-1 with how  
they're organized in production.

Thus, the separation of the "php" dir (which essentially is the  
include_path) from the "ext" dir (which has the external projects in  
it using svn:externals).  One can use symlinks to make sure the "ext"  
and "php" files appear in the right place for their purpose (e.g.,  
the "www" directory with all the public files for the various Vendor  
apps).


>   Maybe there is no good solution to this conflict.

Or maybe there is more than one competing solution.  ;-)  I think  
this is probably "a" good one, but certainly not "the only" good  
one ... thus the call for comment.

Hope that all makes a little more sense; please let me know if it  
does not.


--

Paul M. Jones  <http://paul-m-jones.com>

Solar: Simple Object Library and Application Repository
for PHP5.  <http://solarphp.com>

Join the Solar community wiki!  <http://solarphp.org>

Savant: The simple, elegant, and powerful solution for
templates in PHP.  <http://phpsavant.com>