Directory Layout

[Andrew Short]

Hey all,

As part of the composer stuff I've been playing around with restructuring the directory layout of a SilverStripe application, both in the way the entire application and also individual modules are structured.

None of these changes I'm suggesting will be required for things to work - you can still structure things however you want (within reason). However, this will be the default installed setup, and how the docs suggest things. In short, this will be the recommended/standard application layout. 

Application

	/application
		/src
			Application.php
			Page.php
		modules.yml
		_config.php
	/public
		assets
		index.php
		.htaccess
	/themes
	/vendor
	/composer.json



 There are now the following directories in the root of your app: "application", "public", "themes" and "vendor".

The application folder contains all your custom application code, and replaces the mysite folder. Each application has a subclass of the SilverStripe application class, which registers the modules it uses. There are a number of ways to register modules - you can register them in PHP, from a YAML file, or by scanning a directory. The default setup loads them from a YAML file, and this file is automatically updated when you install a module using composer.

The public folder is the webroot of your application. An important thing to note  is that now your application code no longer lives in the webroot, meaning it is  no longer directly accessible from the web. To make sure that any public URL referenced assets from your application  (eg images, css, js) are still available,  SilverStripe will automatically create the appropriate symlinks (or copies on  windows systems) to make sure these are available from the public folder. 

The way this works is that each module can define a `getAssetDirs` method, which returns a set of directory names to copy across (if they exist). By default it copies the css, javascript, images and thirdparty dirs. If you want other directories to be copied across you will be required to define these explicitly. 

The themes directory still has the same function as previously, however themes are not be auto-discovered - I will probably change this behaviour.

The vendor directory holds all of your composer-installed dependencies. This includes the framework, any modules and themes, as well as thirdparty dependencies.

Modules

The main change here is renaming the `code` folder to the `src` folder, which I think is a more sensible name. Also, I'm going to say in the docs that it's suggested to use PSR-0 style autoloading.

Thoughts?

Andrew Short.

[Anselm Christophersen]

Sounds great.

I've myself just started to keep sensible items out of my web root in my own repos so I very much welcome Silverstripe to dictate this behavior. Only question: is this too much of a change for 3.1?

I would love for this to be included soon -of course given that it works reliably.

Sent from my iPad

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To post to this group, send email to silverst...@googlegroups.com.
To unsubscribe from this group, send email to silverstripe-d...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/silverstripe-dev?hl=en.

[Andrew Short]

The way I've implemented it is backwards compatible - you can still run your application with everything in the web root, it just won't be recommended.

Andrew Short.

[Will Rossiter]

Personally I don't use the themes folder at all, I rather keep everything (php, js, css, templates respectively) under 1 folder ('app') in my case (shorter than application). 

For me it's one less top level directory and keeps everything 'together' but I understand if making SS fit everyones idea is impractical.. we still need to use themes for things like subsites and mobile module.

SilverStripe will automatically create the appropriate symlinks (or copies on  windows systems) to make sure these are available from the public folder. 

When does it create the symlinks?

The public folder is the webroot of your application. An important thing to note  is that now your application code no longer lives in the webroot, meaning it is  no longer directly accessible from the web.

Will an .htaccess be needed in the topmost root? In that case for those users that typically setup WAMP/MAMP and just download SilverStripe to a folder as well as most shared hosts where you have very little if any control on the webroot path.

[Ingo Schommer]

Andrew, this is looking great, thanks so much for seeing this through!

And for being so thorough on the docs: https://github.com/ajshort/sapphire/commit/a4d0aee836237c99fa602e7f5d4080b65279375a

Are you planning to update the "install from source" docs as well?

I guess both "phing update_modules" and "git clone" variations would be deprecated now.

Is there any reason we need to keep them around?

I guess an upgrade guide should have a "migrate to new app structure"

section, right? A few "mv" commands, which strings to search

for in your own code (e.g. hardcoded /assets paths).

Have you tested the setup in a subfolder, e.g. http://localhost/silverstripe-composer-demo?

The Request->extractBaseUrl() doesn't seem to work for me,

which means the <base> tag is pointing to http://localhost/silverstripe-composer-demo

rather than http://localhost/silverstripe-composer-demo/public.

I agree with Will, "app" is shorter than "application", and has the same semantic value.

It means a mismatch between the folder ("app") and the main class in there ("Application"), but I think that's acceptable.

Andrew, I know its configurable, but what do you think, worth changing the default?

When I do "composer.phar install" on your demo project,

it loads everything fine, but barfs on wrong DB credentials

on the post-composer scripts. But I can't really run the SS installer

before I have loaded the dependencies. Bug, or did I overlook something? :)

Lots of questions, but I think we're pretty close!

Ingo

[Andrew Short]

On Mon, Aug 20, 2012 at 6:08 PM, Will Rossiter <will.r...@gmail.com> wrote:

Personally I don't use the themes folder at all, I rather keep everything (php, js, css, templates respectively) under 1 folder ('app') in my case (shorter than application). 

For me it's one less top level directory and keeps everything 'together' but I understand if making SS fit everyones idea is impractical.. we still need to use themes for things like subsites and mobile module.

Yep, I still think we need it. If you install a thirdparty theme it'll end up somewhere inside the vendor directory, so only your application themes will be in the themes directory (and the simple theme for the tutorial).

SilverStripe will automatically create the appropriate symlinks (or copies on  windows systems) to make sure these are available from the public folder. 

When does it create the symlinks?

When you perform a module-altering action using composer (install, update etc) this is done automatically. You can also run it as a task - if you create a new asset directory for example in your application, you'll need to run that task to get it copied across.

The public folder is the webroot of your application. An important thing to note  is that now your application code no longer lives in the webroot, meaning it is  no longer directly accessible from the web.

Will an .htaccess be needed in the topmost root? In that case for those users that typically setup WAMP/MAMP and just download SilverStripe to a folder as well as most shared hosts where you have very little if any control on the webroot path.

The .htaccess file will live by default in the public subfolder. If you want to run the site with the webroot the same as the application root, you need to move index.php and .htaccess up a level, and update your application's getPublicPath method. I'll add a guide on this to the installation docs, which I still have to write.
 

[Andrew Short]

On Tue, Aug 21, 2012 at 4:27 AM, Ingo Schommer <in...@silverstripe.com> wrote:

Andrew, this is looking great, thanks so much for seeing this through!

And for being so thorough on the docs: https://github.com/ajshort/sapphire/commit/a4d0aee836237c99fa602e7f5d4080b65279375a

Are you planning to update the "install from source" docs as well?

I guess both "phing update_modules" and "git clone" variations would be deprecated now.

Is there any reason we need to keep them around?

Yep, I'll be updating the install docs when I update the installer to work with Composer. I can't see any reason to keep these around - composer has the --prefer-source option for downloading development versions.
 

I guess an upgrade guide should have a "migrate to new app structure"

section, right? A few "mv" commands, which strings to search

for in your own code (e.g. hardcoded /assets paths).

Yep.

Have you tested the setup in a subfolder, e.g. http://localhost/silverstripe-composer-demo?

The Request->extractBaseUrl() doesn't seem to work for me,

which means the <base> tag is pointing to http://localhost/silverstripe-composer-demo

rather than http://localhost/silverstripe-composer-demo/public.

I'll fix this up - I reworked the base url stuff a bit and think I broke a few things.
 

I agree with Will, "app" is shorter than "application", and has the same semantic value.

It means a mismatch between the folder ("app") and the main class in there ("Application"), but I think that's acceptable.

Andrew, I know its configurable, but what do you think, worth changing the default?

Sure, it should be pretty easy to do.

When I do "composer.phar install" on your demo project,

it loads everything fine, but barfs on wrong DB credentials

on the post-composer scripts. But I can't really run the SS installer

before I have loaded the dependencies. Bug, or did I overlook something? :)

You need to edit application/_config.php first and add your DB details - eventually this will be taken care of by the installer, just wanted to try and get a demo skeleton out there.
 

[Simon J Welsh]

How will the installer work, especially on shared hosts where you can't really have things outside the web root?

Also, I'm against PSR-0 style autoloading. It just seems to add unnecessary clutter to class names for no gain when we've already got a great manifest.

On 19/08/2012, at 11:01 PM, Andrew Short <andrew...@gmail.com> wrote:

> Hey all,
>
> As part of the composer stuff I've been playing around with
> restructuring the directory layout of a SilverStripe application, both
> in the way the entire application and also individual modules are
> structured.
>
> None of these changes I'm suggesting will be required for things to
> work - you can still structure things however you want (within
> reason). However, this will be the default installed setup, and how
> the docs suggest things. In short, this will be the
> recommended/standard application layout.

> *Application*

> *Modules*

>
> The main change here is renaming the `code` folder to the `src`
> folder, which I think is a more sensible name. Also, I'm going to say
> in the docs that it's suggested to use PSR-0 style autoloading.
>
> Thoughts?
>
> Andrew Short.

---
Simon Welsh
Admin of http://simon.geek.nz/