Proposal for new directory structure

32 views
Skip to first unread message

Vance Lucas

unread,
Apr 1, 2011, 6:00:04 PM4/1/11
to Alloy
Currently the directory structure looks like this:

├── app
│   ├── Module
│   ├── Plugin
│   ├── config
│   ├── init.php
│   └── layouts
├── lib
│   ├── Alloy
│   └── App
├── tests
│   ├── AllTests.php
│   └── Test
├── vendor
│   └── Plugin
└── www
├── .htaccess
├── assets
├── index.php
├── robots.txt
└── web.config


The problem with this organization is when Alloy core changes, it is
difficult to upgrade because sometimes there are more changes than
just in the core library, like changes to routes, new config keys that
are added, the layout plugin that ships with Alloy, etc.

I propose a change to the following structure to better separate Alloy
core and user-level applications with custom code:

├── .htaccess
├── alloy
│   ├── LICENSE.txt
│   ├── Plugin
│   ├── README.md
│   ├── config
│   ├── init.php
│   ├── lib
│   └── tests
└── app
├── Module
├── Plugin
├── config
├── layouts
├── lib
└── www
├── .htaccess
├── assets
├── index.php
├── robots.txt
└── web.config

This organization would place all the core alloy files in a new
directory named "alloy", and all the user-space application files in a
directory named "app". Files like config/app.php and config/routes.php
would be in the "alloy" directory, and might be duplicated in the
"app" directory or included/extended in the initial default install.
This would allow easy upgrading through dragging and dropping or a
single folder or updating a single git submodule.

What do you guys think? Is this change worth the short-term headache?

Chris Boden

unread,
Apr 1, 2011, 6:17:19 PM4/1/11
to Alloy
"Is this change worth the short-term headache?" ABSOLUTELY. +1. I'm
juggling three projects with Alloy right now, I want the latest
version in each as they're all in development but it's currently a
pain synchronizing them. Alloy as git submodule would be awesome.

I like the idea of a one-time config file copy (or setup script) vs
double loading config files for one variable change. Or
putting .example files in their place with a .gitignore on the file
-.example (just thinking aloud). Which ever solution works out to be
easy for the user and efficient.

Two possible hiccups?:

1) What happened to vendors/Spot?

2) What about third party plugins bundled with asset (css, javascript,
image) files?

Vance Lucas

unread,
Apr 1, 2011, 6:23:47 PM4/1/11
to allo...@googlegroups.com
To answer your questions:

1) The 'vendor' directory was actually removed for now. vendor/Plugin/Spot was moved to alloy/Plugin/Spot because it ships with Alloy by default as a plugin that is enabled. If you don't use it, just update your own config file in app/config/app.php to remove it/prevent it from loading.

2) There is no real solution for this short of moving the whole Plugin or Module directory above the web root, which I don't really like. I am open for suggestions on this.

--
Vance Lucas
http://vancelucas.com

Chris Boden

unread,
Apr 1, 2011, 6:29:27 PM4/1/11
to Alloy
1) Excellent, I like that more than the vendors directory

2) I haven't thought of a better solution yet either. I agree with
you, I'm not a fan of moving the entire plugin code base into the www
(despite it being the only obvious solution for now)

On Apr 1, 6:23 pm, Vance Lucas <va...@vancelucas.com> wrote:
> To answer your questions:
>
> 1) The 'vendor' directory was actually removed for now. vendor/Plugin/Spot
> was moved to alloy/Plugin/Spot because it ships with Alloy by default as a
> plugin that is enabled. If you don't use it, just update your own config
> file in app/config/app.php to remove it/prevent it from loading.
>
> 2) There is no real solution for this short of moving the whole Plugin or
> Module directory above the web root, which I don't really like. I am open
> for suggestions on this.
>
> --
> Vance Lucashttp://vancelucas.com

K Wasseem

unread,
Apr 2, 2011, 4:33:13 AM4/2/11
to allo...@googlegroups.com
Hi everyone,

My concern is about the WWW folder residing inside the APP:

I do not think it is a good idea to have the folder WWW inside APP. App will contain some business logics and as a rule of thumb you might even be placing APP outside your doc_root on a prod server. WWW should only reside in doc_root. Don't just focus on isolating the core files, you should also think about future Logics of a system coming on top of this core framework.
So, I do not think this new structure, as far as the WWW folder is concerned, makes much sense for the long term..

//Wasseem
--
Best regards,
Khayrattee Wasseem
(http://7php.com)

Chris Boden

unread,
Apr 2, 2011, 9:41:52 AM4/2/11
to Alloy
K,

Keeping the app directory outside the DocumentRoot can be accomplished
by turning FollowSymLinks (in Apache) globally or in the .htaccess
file. You then make a symbolic link from app/www to your
DocumentRoot.

Alternatively, if that's not an option for some reason, .htaccess
files prevent access to the rest of the /app directory if it's in the
DocumentRoot.

K Wasseem

unread,
Apr 2, 2011, 10:01:35 AM4/2/11
to allo...@googlegroups.com
Hi Chris,

that is fine for those of us who likes to get 'our hands dirty'. But since the aim of this framework is also 'ease of use/deployment', i do not think we should go as far as inside httpd.conf to do that. If you have a look at other frameworks, they all (or at least most of those worth their salt) have WWW outside APP or standing independly as the main Public_html for a reason. ;)

Btw, I'm not sure if this is achieved with .htaccess, you will have to adjust httpd.conf

//Wasseem

Chris Boden

unread,
Apr 2, 2011, 10:09:04 AM4/2/11
to Alloy
Hi K,

To enable what I was talking about you can add the following line to
your .htaccess file (or httpd.conf as you suggested).
Options +FollowSymlinks

In fact, I'd recommend Vance put that in Alloy's .htaccess file, as
Apache _requires_ FollowSymlinks on in order for mod_rewrite to work.
(http://httpd.apache.org/docs/current/mod/mod_rewrite.html)

Éber Freitas Dias

unread,
Apr 2, 2011, 10:34:38 AM4/2/11
to allo...@googlegroups.com
My 2 cents about the issue!

I agree with the folder re-organization. About the www folder, I guess that the best solution is to just point your webserver to the www folder, not the app folder itself. You can easily detach the www folder by editing the first line of the index.php file pointing to the app folder.

As far as I know, CakePHP uses a similar folder structure. The only thing I would consider is shipping a "libraries" folder where alloy's core would reside, that way would be easy to plug-in new libraries and frameworks if needed (doctrine for instance, could live inside libraries along with alloy, something like that...).

[]'s

--
Éber



Chris Boden
sábado, 2 de abril de 2011 11:09

Hi K,

To enable what I was talking about you can add the following line to
your .htaccess file (or httpd.conf as you suggested).
Options +FollowSymlinks

In fact, I'd recommend Vance put that in Alloy's .htaccess file, as
Apache _requires_ FollowSymlinks on in order for mod_rewrite to work.
(http://httpd.apache.org/docs/current/mod/mod_rewrite.html)
K Wasseem
sábado, 2 de abril de 2011 11:01

Hi Chris,

that is fine for those of us who likes to get 'our hands dirty'. But since the aim of this framework is also 'ease of use/deployment', i do not think we should go as far as inside httpd.conf to do that. If you have a look at other frameworks, they all (or at least most of those worth their salt) have WWW outside APP or standing independly as the main Public_html for a reason. ;)

Btw, I'm not sure if this is achieved with .htaccess, you will have to adjust httpd.conf

//Wasseem




--
Best regards,
Khayrattee Wasseem
(http://7php.com)


Chris Boden
sábado, 2 de abril de 2011 10:41

K,

Keeping the app directory outside the DocumentRoot can be accomplished
by turning FollowSymLinks (in Apache) globally or in the .htaccess
file. You then make a symbolic link from app/www to your
DocumentRoot.

Alternatively, if that's not an option for some reason, .htaccess
files prevent access to the rest of the /app directory if it's in the
DocumentRoot.
K Wasseem
sábado, 2 de abril de 2011 05:33

Hi everyone,

My concern is about the WWW folder residing inside the APP:

I do not think it is a good idea to have the folder WWW inside APP. App will contain some business logics and as a rule of thumb you might even be placing APP outside your doc_root on a prod server. WWW should only reside in doc_root. Don't just focus on isolating the core files, you should also think about future Logics of a system coming on top of this core framework.
So, I do not think this new structure, as far as the WWW folder is concerned, makes much sense for the long term..

//Wasseem




--
Best regards,
Khayrattee Wasseem
(http://7php.com)


Chris Boden
sexta-feira, 1 de abril de 2011 19:29

Chris Boden

unread,
Apr 2, 2011, 10:40:29 AM4/2/11
to Alloy
Hi Éber,

With the suggested format you would drop Doctrine into /app/lib and
enable it by Kernel()->loader()->registerNamespace('Doctrine',
Kernel()->config('path.lib'));

Upon typing this, I realized there may need to be a new config option
to point to that directory. Perhaps "path.app.lib"?

On Apr 2, 10:34 am, Éber Freitas Dias <eber.frei...@gmail.com> wrote:
> My 2 cents about the issue!
>
> I agree with the folder re-organization. About the www folder, I guess
> that the best solution is to just point your webserver to the www
> folder, not the app folder itself. You can easily detach the www folder
> by editing the first line of the index.php file pointing to the app folder.
>
> As far as I know, CakePHP uses a similar folder structure. The only
> thing I would consider is shipping a "libraries" folder where alloy's
> core would reside, that way would be easy to plug-in new libraries and
> frameworks if needed (doctrine for instance, could live inside libraries
> along with alloy, something like that...).
>
> []'s
>
> --
> Éber
>
>
>
> > ------------------------------------------------------------------------
>
> >    Chris Boden <mailto:cbo...@gmail.com>
> > sábado, 2 de abril de 2011 11:09
>
> > Hi K,
>
> > To enable what I was talking about you can add the following line to
> > your .htaccess file (or httpd.conf as you suggested).
> > Options +FollowSymlinks
>
> > In fact, I'd recommend Vance put that in Alloy's .htaccess file, as
> > Apache _requires_ FollowSymlinks on in order for mod_rewrite to work.
> > (http://httpd.apache.org/docs/current/mod/mod_rewrite.html)
> >    K Wasseem <mailto:kwass...@gmail.com>
> > sábado, 2 de abril de 2011 11:01
>
> > Hi Chris,
>
> > that is fine for those of us who likes to get 'our hands dirty'. But
> > since the aim of this framework is also 'ease of use/deployment', i do
> > not think we should go as far as inside httpd.conf to do that. If you
> > have a look at other frameworks, they all (or at least most of those
> > worth their salt) have WWW outside APP or standing independly as the
> > main Public_html for a reason. ;)
>
> > Btw, I'm not sure if this is achieved with .htaccess, you will have to
> > adjust httpd.conf
>
> > //Wasseem
>
> > --
> > Best regards,
> > Khayrattee Wasseem
> > (http://7php.com)
> > ------------------------------------------------------------------------
>
> >    Chris Boden <mailto:cbo...@gmail.com>
> > sábado, 2 de abril de 2011 10:41
>
> > K,
>
> > Keeping the app directory outside the DocumentRoot can be accomplished
> > by turning FollowSymLinks (in Apache) globally or in the .htaccess
> > file. You then make a symbolic link from app/www to your
> > DocumentRoot.
>
> > Alternatively, if that's not an option for some reason, .htaccess
> > files prevent access to the rest of the /app directory if it's in the
> > DocumentRoot.
> >    K Wasseem <mailto:kwass...@gmail.com>
> > sábado, 2 de abril de 2011 05:33
>
> > Hi everyone,
>
> > My concern is about the WWW folder residing inside the APP:
>
> > I do not think it is a good idea to have the folder WWW inside APP.
> > App will contain some business logics and as a rule of thumb you might
> > even be placing APP outside your doc_root on a prod server. WWW should
> > only reside in doc_root. Don't just focus on isolating the core files,
> > you should also think about future Logics of a system coming on top of
> > this core framework.
> > So, I do not think this new structure, as far as the WWW folder is
> > concerned, makes much sense for the long term..
>
> > //Wasseem
>
> > --
> > Best regards,
> > Khayrattee Wasseem
> > (http://7php.com)
> > ------------------------------------------------------------------------
>
> >    Chris Boden <mailto:cbo...@gmail.com>

Vance Lucas

unread,
Apr 3, 2011, 8:31:25 PM4/3/11
to allo...@googlegroups.com
Wow, great discussion so far. Didn't expect to spark such a heated debate, but I am glad to hear everyone's opinions and concerns.

Regarding the WWW folder inside the APP folder:

Official production deployment recommendations are always going to be setting up a separate vhost for each app, with the WWW folder set as the web-accessible root. With this setup, it does not matter where the WWW folder is at all, as long as all app files are below the web root (non web-accessible), which they still will be.

That being said, direct upload or drag-n-drop installs will also always be supported for those who do not want to mess with setting up vhosts, or those who do not have access to do so, like for shared hosting. Thus hosting an Alloy app from a subfolder or subdirectory will also always be supported by default. The specific way this is accomplished is with an .htaccess file in the default distribution root that rewrites all incoming requests to the www folder. The default distribution is even already setup like that now. The only change in this regard will be the path in the .htaccess file will have to be changed from www to app/www, which is not a big deal at all.

There is also an additional benefit to moving the www folder inside the app folder, and that is that it allows multiple Alloy apps to run alongside each other on the same server, sharing a common Alloy core. The app folders would just be renamed 'myappone', 'myapptwo', etc. and the Alloy core folder would still be 'alloy'.

--
Vance Lucas
http://vancelucas.com



Vance Lucas

unread,
Apr 4, 2011, 7:59:17 PM4/4/11
to Alloy
I created a new branch with the folder re-organization called "dev/
reorg":
https://github.com/alloyphp/alloy/tree/dev/reorg

Feel free to review the code and test it. A lot of the configuration
keys had to change to support the re-organization because we now have
an 'alloy' config and an 'app' config. I also went ahead and moved
Exceptions under their own namespace so there are no more underscores.
These changes will likely break quite a few apps, but I sincerely
believe the change is for the best.

The best way to try this out is to just clone alloy for a new project,
switch to the dev/reorg branch, and then copy all your Modules and
Plugins in along with any specific config keys or values that had been
previously set.

Cheers,

--
Vance Lucas
http://vancelucas.com



On Apr 3, 7:31 pm, Vance Lucas <va...@vancelucas.com> wrote:
> Wow, great discussion so far. Didn't expect to spark such a heated debate,
> but I am glad to hear everyone's opinions and concerns.
>
> Regarding the WWW folder inside the APP folder:
>
> Official production deployment recommendations are always going to be
> setting up a separate vhost for each app, with the WWW folder set as the
> web-accessible root. With this setup, it does not matter where the WWW
> folder is at all, as long as all app files are below the web root (non
> web-accessible), which they still will be.
>
> That being said, direct upload or drag-n-drop installs will also always be
> supported for those who do not want to mess with setting up vhosts, or those
> who do not have access to do so, like for shared hosting. Thus hosting an
> Alloy app from a subfolder or subdirectory will also always be supported by
> default. The specific way this is accomplished is with an .htaccess file in
> the default distribution root that rewrites all incoming requests to the www
> folder. The default distribution is even already setup like that now. The
> only change in this regard will be the path in the .htaccess file will have
> to be changed from www to app/www, which is not a big deal at all.
>
> There is also an additional benefit to moving the www folder inside the app
> folder, and that is that it allows multiple Alloy apps to run alongside each
> other on the same server, sharing a common Alloy core. The app folders would
> just be renamed 'myappone', 'myapptwo', etc. and the Alloy core folder would
> still be 'alloy'.
>
> --
> Vance Lucashttp://vancelucas.com

Chris Boden

unread,
Apr 5, 2011, 9:20:02 AM4/5/11
to Alloy
How is the going to work as a submodule? Will there be a separate
branch updated with just the alloy directory?

On Apr 4, 7:59 pm, Vance Lucas <czar...@gmail.com> wrote:
> I created a new branch with the folder re-organization called "dev/
> reorg":https://github.com/alloyphp/alloy/tree/dev/reorg
>
> Feel free to review the code and test it. A lot of the configuration
> keys had to change to support the re-organization because we now have
> an 'alloy' config and an 'app' config. I also went ahead and moved
> Exceptions under their own namespace so there are no more underscores.
> These changes will likely break quite a few apps, but I sincerely
> believe the change is for the best.
>
> The best way to try this out is to just clone alloy for a new project,
> switch to the dev/reorg branch, and then copy all your Modules and
> Plugins in along with any specific config keys or values that had been
> previously set.
>
> Cheers,
>
> --
> Vance Lucashttp://vancelucas.com

Vance Lucas

unread,
Apr 5, 2011, 10:12:32 AM4/5/11
to allo...@googlegroups.com
I will make a separate git repository with just the alloy core, but unfortunately it will not be a submodule by default. Github does not pull in submodules when building downloads, so downloads will be effectively broken for the default distribution if we use them. I will have to use a git-subtree merging strategy to merge changes to the Alloy core into the default distribution.

In your own setup though, feel free to use submodules if it makes staying up to date easier for you. It just can't be distributed by default that way.

--
Vance Lucas  
http://vancelucas.com



Chris Boden

unread,
Apr 5, 2011, 10:58:37 AM4/5/11
to Alloy
Vance, can you please confirm I understand this correctly?

There will now be https://github.com/alloyphp/alloycore where there
will just be the /alloy directory. Updates will be done here, users
who choose to will use this as their submodule. https://github.com/alloyphp/alloy
will stay as-is and is a full-working base application of Alloy that
people can download and will "work out of the box". You will push
updates from "alloycore" to "alloy"?

On Apr 5, 10:12 am, Vance Lucas <va...@vancelucas.com> wrote:
> I will make a separate git repository with just the alloy core, but
> unfortunately it will not be a submodule by default. Github does not pull in
> submodules when building downloads, so downloads will be effectively broken
> for the default distribution if we use them. I will have to use a
> git-subtree merging strategy to merge changes to the Alloy core into the
> default distribution.
>
> In your own setup though, feel free to use submodules if it makes staying up
> to date easier for you. It just can't be distributed by default that way.
>
> --
> Vance Lucashttp://vancelucas.com

Vance Lucas

unread,
Apr 5, 2011, 11:03:25 AM4/5/11
to allo...@googlegroups.com
Yes, that is pretty much it exactly, only the project "alloy-core" will be just the *contents* of the /alloy directory so it can be a submodule inside that directory in the actual project.

--
Vance Lucas  
http://vancelucas.com

Vance Lucas

unread,
Apr 10, 2011, 11:29:31 PM4/10/11
to Alloy
The new directory structure is in place and a new release v0.7.1 beta
is out.

Alloy repository:
https://github.com/alloyphp/alloy

Alloy "core" repository (contents of the "alloy" folder):
https://github.com/alloyphp/alloy-core

Thanks for all the input guys.

--
Vance Lucas
http://vancelucas.com

On Apr 5, 10:03 am, Vance Lucas <va...@vancelucas.com> wrote:
> Yes, that is pretty much it exactly, only the project "alloy-core" will be
> just the *contents* of the /alloy directory so it can be a submodule inside
> that directory in the actual project.
>
> --
> Vance Lucashttp://vancelucas.com
>
>
>
>
>
>
>
> On Tue, Apr 5, 2011 at 9:58 AM, Chris Boden <cbo...@gmail.com> wrote:
> > Vance, can you please confirm I understand this correctly?
>
> > There will now behttps://github.com/alloyphp/alloycorewhere there
> ...
>
> read more »

Chris Boden

unread,
Apr 12, 2011, 2:14:11 PM4/12/11
to Alloy
Thanks Vance.

Should future Pull Requests go to alloy or alloy-core?

On Apr 10, 11:29 pm, Vance Lucas <czar...@gmail.com> wrote:
> The new directory structure is in place and a new release v0.7.1 beta
> is out.
>
> Alloy repository:https://github.com/alloyphp/alloy
>
> Alloy "core" repository (contents of the "alloy" folder):https://github.com/alloyphp/alloy-core
>
> Thanks for all the input guys.
>
> --
> Vance Lucashttp://vancelucas.com
> ...
>
> read more »

Vance Lucas

unread,
Apr 12, 2011, 7:31:10 PM4/12/11
to allo...@googlegroups.com
Good question. Probably stick with "alloy" for now, because some changes may still be at the app level until we get it all fully sorted out and separated as we get closer to a 1.0 release.

--
Vance Lucas
http://vancelucas.com



Reply all
Reply to author
Forward
0 new messages