[Solar-talk] Project structure layout?

[Paul M Jones]

On Nov 14, 2007, at 4:13 AM, Antti Holvikari wrote:

> On 11/14/07, Jeff Moore <jeff at procata.com> 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.  Maybe there is no good  
>> solution to
>> this conflict.
>
> The example Paul gave was missing a tests dir for the "Project" which
> is the project you are actually working on with that setup (you are
> not working with the ext/ projects neccessarily, they're just external
> dependencies). So, what I suggest is to put the tests for Project into
> the php dir, which would bring the tests "closer".
>
>   php/                    # unified include-path
>         Project.php         # arch-class for this project
>         Project/            # files for this project
>         tests/               # tests for Project
>         ....
>
> Or put then in the top level. Does this make any sense? Any other  
> suggestions?

Yeah, this makes good sense.  The "Project" in this case is not  
distributed as its own separate thing; it's the core of the  
application/site/whatever, so it makes sense to go here.

Alternatively, we could have a "lib" (or other) directory to  
distinguish between "internal" file sets and "external" file sets,  
then symlink just the class files from that "lib" dir into  
"php" (just as we do with "ext" files).  It would end up looking  
something like this:


     ext/                    # svn externals for this project
         solar/              # http://solarphp.com/svn/trunk
             Solar.php
             Solar/
             bin/
             docs/
             tests/
         example/            # http://example.com/svn/trunk
             Example.php
             Example/
             bin/
             docs/
             tests/

     lib/
         Project.php         # arch-class for this project
         Project/            # files for this project
         bin/
         docs/
         tests/

     php/                    # unified include-path
         Project.php         # ln -s ../lib/Project.php
         Project/            # ln -s ../lib/Project
         Solar.php           # ln -s ../ext/solar/Solar.php
         Solar/              # ln -s ../ext/solar/Solar
         Example.php         # ln -s ../ext/example/Example.php
         Example/            # ln -s ../ext/example/Example

     bin/                    # cli scripts for this project

     cfg/                    # config files for this project
         Solar.config.php

     www/                    # link to this from /var/www/htdocs
         index.php           # bootstrap
         public/             # public dir
             Project/        # ln -s ../../php/Project/App/Public
             Solar/          # ln -s ../../ext/solar/Solar/App/Public
             Example/        # ln -s ../../ext/vendor/Vendor/App/Public


Then you don't have the docs/test/etc in the include-path, and those  
project files becomes more ready for separate distribution.

In fact, looking at it now, we could almost combine the "lib" and  
"ext" directories as the class-file sources, and link from just that  
one location to "php", "www", and so on.

Hope that all makes sense.



--

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>