Garden Preview Part II: FileSystem
Garden Preview Part I: Overview
Garden Preview Part II: Filesystem
Garden Preview Part III: Anatomy of a Request
Garden Preview Part IV: Views
Garden Preview Part V: Data
Garden Preview Part VI: Models & Forms
Garden Preview Part VII: Ajax
Garden Preview Part VIII: Plugins
Garden Preview Part IX: Roles & Permissions
Garden Preview Part X: User Registration
Garden Preview Part XI: Structure
Whenever I start looking into how an application works, the first thing I do is browse through the files & folders to see where everything is. And, interestingly enough, where the files and folders reside in Garden have a lot to do with how Garden works.
[Edit - After some good suggestions in the comments of this post, I've made some changes to this post and updated appropriately.]
Let’s start by looking at the root folder of my development version of Garden:
Here’s a breakdown of what each root folder/file is:
applications: The applications folder contains folders, which in turn contain all of the files specific to each application. As you can see, I’ve got four applications listed here. The “garden” application is the base application of the framework that handles signing in, user, role, permission, plugin, and application management. The “scaffolding” application is the first application that I developed with Garden, which you may remember from a few months ago. Sadly, after months of changing how the core Garden libraries work, the Scaffolding application is now very broken. The “skeleton” application is a set of folders and files that represents an empty application. My idea with Skeleton was to have a set of files that a developer could copy as their starting point for a new application (You could also call it an “application template”). The “vanilla” application is, of course, Vanilla!
cache: The cache folder is *currently* used as a general purpose cache. At the time of this writing, it contains cached application settings. These are things like mappings of class names to their location on the filesystem, mappings of locale sources (ie. all “en-CA” definition files from all plugins and applications), etc. There may come a time when there are entirely cached pages or page views, but that will not be present at time of release.
conf: Anyone familiar with Vanilla 1 knows exactly what this folder is. The conf folder contains all of your custom configuration settings in a number of different php files as associative arrays. This folder and the cache folder will need write permissions for PHP.
js: Obviously, like Vanilla 1, this is where all of the javascript in Garden resides. The only difference from Vanilla 1 is that there is a “library” folder within the javascript folder that contains jquery libraries – some of which I’ve written and others that come from the jquery website.
library: This is the core libraries for Garden (aka. “where the magic happens”).
plugins: This folder is the equivalent of the extensions folder in Vanilla 1. It contains folders which, in turn, contain all of the files for a specific plugin. I’ll be getting into Plugins in another Garden Preview.
themes: Similar to themes in Vanilla 1, but far more flexible. I’ll be getting into themes and theming in another Garden preview.
.htaccess, INSTALL.txt, LICENSE.txt: These three files should be self explanatory.
default.php: This is the file that all requests to garden are made through.
So, now that you know what the root folder looks like, let’s take a look at one of the application folders. I’ll use Skeleton since it is a basic representation of any application:
controllers: As previously mentioned, Garden is a Model-View-Controller (MVC) framework. The controllers folder contains all of the controllers for this application. Controllers handle all page, partial-page, rss, or any other kind of requests, and act as an intermediary between the models and the views.
design: Obviously there are themes available in Garden, but each application can also have it’s own set of css and image files – those will be placed in the design folder. I’ll get into more detail on this folder when I talk about theming in another Garden preview.
js: Javascript files specific to this application.
locale: Localization files for this application.
models: Models in garden will interact directly with your data sources (databases, flat configuration files, etc) and perform get, set, and delete operations. As previously mentioned in the first Garden preview, there is a general purpose model that Garden provides so that you don’t need to create a model class to represent every data structure. However, there are times when you need to customize a model to suit the needs of your application. When you do, this folder is where you’ll put those models.
settings: The settings folder for each application is the equivalent of the “appg” folder in Vanilla 1. It contains the default application settings for that specific application. In Garden, it also contains the about.php file – a file which defines all of the information about this application. That information includes things like: Application name, version, author, requirements, licensing info, etc.
views: Of course, this folder represents the Views in the MVC pattern. This is where all of your xhtml for the pages will go, and it relates directly to the controllers that handle them.
bootstrap.php: The bootstrap file for each application is included before any of the major libraries in Garden are loaded. So far, with the three applications I’ve been working on, I haven’t needed to use it very much. But I’m keeping it there just-in-case a need arises.
Conclusion
There is still a lot to explain, but I’ve given you a breakdown of where things are in Garden. In the next Garden Preview I’ll be diving further into the root default.php file, the application request dispatcher, the MVC folders, and explaining how views, master views, and page requests are handled.
I cannot wait to start working with this. Right now I am trying to start working with CakePHP or Symfony and there are a lot of things that I do not like about both, so this is great timing!
If you do some sort of alpha release, please count me in! I would love to help where I can.
Awesome work!
ok i’m confused
Vanilla which is an application build on top of garden resides at the root level rather than an applications folder
So a blog/Calendar/photo application will also reside at the root level and their controllers/view/model have to be in the skeleton folder, and plugins in the plugins folder?
Shouldn’t there be more separation between Garden and Vanilla
Like below.
Application->Vanilla->Plugins
Application->Vanilla->Skeleton->Controller
Application->Calendar->Skeleton->Model
@MySchizoBuddy – First of all, skeleton is an “application template”. It’s the folders & files (bones) that you can use to start building a new application. So, when I wanted to start working on Vanilla, I made a copy of the skeleton folder named “vanilla”, and started adding/editing files therein.
Plugins work for every application – not just one – so the plugin directory is at the root. For example, what if you want to create a plugin that adds the line, “This is the end of the page” to every page of every application? If the plugin folder was specific to each application, you’d have to add that plugin to every application’s plugin folder. In it’s current state, you only need to add it to *one* folder. If, on the other hand, you want to only add that line to Vanilla pages, you would specify that within the plugin somewhere.
As for an “applications” folder, I guess I could have had an “applications” folder in the root, but I did it this way because I liked it this way. I may end up changing it so that applications are in their own “applications” folder before I’m finished. That’s a pretty easy change.
So, here’s how you can imagine it:
Garden->Plugins
Garden->Vanilla->Controller
Garden->Vanilla->Model
Garden->Skeleton->Controller
Garden->Skeleton->Model
Garden->Calendar->Controller
Garden->Calendar->Model
If it doesn’t make sense yet, it will once I go further into how things work.
this will make packaging an application a bit confusing, I now will have to tell users that the Blog folder goes under root, but the plugins (created specially for the blog app) inside the Blog->Plugins need to be moved to the plugins folder in the root. you can imagine tons of support calls cause users forgot to move the plugins in the appropriate directory.
I would like to tell my users extract this zip file and drop the folder named “blog” in the “applications” folder and your done. nothing has to be moved anywhere else.
Plugins that are app specific should go inside the app->plugin folder cause they have no use anywhere else, plugins that are universal should go in the root plugins folder and all my apps will have access to them.
Its up to the developers to decide if a plugin they have made will be usefull to other apps. if yes then have it available as a separate download.
there can be tons of applications, having them nicely inside an applications folder will be great.
Thanks mark
I agree about the applications folder – I will probably make that change soon – like I said, it’s an easy one.
I don’t like the idea of separating the plugins into different places. Just as you say putting the applications in a single place makes sense – same goes for plugins. I could easily see people making the mistake of putting an app-specific plugin into the global plugin folder – or even the wrong application’s folder- and the wondering why it doesn’t work (or worse, why it broke the site).
@MySchizoBuddy – I should also mention that when it comes to plugins, they work in a very different way than extensions did in Vanilla 1. When I explain how they work (in an upcoming preview), you’ll see how this central plugin folder works well.
I would agree with putting any and all applications built with Garden in an applications folder. This would make updating the framework or the applications built with Garden very easy. It also separates any and all framework and application code another degree.
Any ideas of a release date?
I’m hoping for February – but it all depends on how development goes.
all directories inside the skeleton are empty right beside the settings folder which has the about.php file
@MySchizoBuddy – Almost. There are two or three other “shell” files that are there as placeholders. I’ll get into those next week…
Thanks for the suggestions – I’ve updated the core libraries and this post.
where do i put stuff like Amfphp, which is used to communicate between php and flash on the client. Amfphp is a thirdparty library, so where would i put third party libraries?
Well, if you were adding it to the core, we’d probably create a folder within “library” for it. If you were using it in just one application you were developing, you’d put it wherever you wanted within that application.
[...] Click here to read the Garden Preview Part I Click here to read the Garden Preview Part II [...]
amfphp will be used as a library for remote services to be used by all apps. So it will go somewhere in the library folder, and the plugin based on this library for each application will go in the plugins folder.
Can you create a generic folder inside the library folder for all things “third party”. we can call it thirdparty ?
Sure!
btw are you using dependency injection in garden
No. Where do you think it could be implemented?
[...] here to read the Garden Preview Part I Click here to read the Garden Preview Part II Click here to read the Garden Preview Part [...]
[...] here to read the Garden Preview Part I Click here to read the Garden Preview Part II Click here to read the Garden Preview Part III Click here to read the Garden Preview Part [...]
[...] here to read the Garden Preview Part I Click here to read the Garden Preview Part II Click here to read the Garden Preview Part III Click here to read the Garden Preview Part IV Click [...]
[...] here to read the Garden Preview Part I Click here to read the Garden Preview Part II Click here to read the Garden Preview Part III Click here to read the Garden Preview Part IV Click [...]
[...] here to read the Garden Preview Part I Click here to read the Garden Preview Part II Click here to read the Garden Preview Part III Click here to read the Garden Preview Part IV Click [...]
[...] Preview Part I: Overview Garden Preview Part II: Filesystem Garden Preview Part III: Anatomy of a Request Garden Preview Part IV: Views Garden Preview Part V: [...]
[...] Preview Part I: Overview Garden Preview Part II: Filesystem Garden Preview Part III: Anatomy of a Request Garden Preview Part IV: Views Garden Preview Part V: [...]