Zurmo – How the Source Code is Organized – Part 1

The recent explosion of interest in open-source software development along with Agile frameworks which emphasize convention over configuration comes with a subtle price tag. Developers must invest valuable time coming to grips with the lay of the land when approaching a new software project.


Our goal today is to help relieve some of the anxiety you may experience upon first contact with the wild and woolly geography of the Zurmo CRM repository. A quote from one of our colleagues illustrates the case succinctly…

“When I first approached Zurmo I saw and understood its end potential, then I looked at the 1,000’s of files that make Zurmo work how it does and immediately thought “I’m in way over my head.” …

And that’s coming from an experienced PHP developer!

So let’s begin at the beginning. Our first foray starts with a high level reconnaissance of the Zurmo repository. You should have a basic familiarity with navigating a modern DSCM (Distributed Source Code Management) System like Bitbucket or Git. If you need a refresher, check out one of my earlier articles posted here at Arvixe titled: “Zurmo – How to browse the source code”.

Here’s what we’re faced with when we type https://www.bitbucket.org/zurmo/zurmo in our browser:

2014-07-28 17_28_10-Bitbucket-zurmo-zurmo

As you can see not too intimidating! (What’s all the fuss then?). Here there are only three directories and six files. Three of the six files which start with “.hg” deal with repository configuration. There’s an obvious licensing file, and the README that contains a description of the project. So that leaves us with index.php.

If we open index.php it boils down to this one-liner. What a beauty!

header("Location: app/index.php");

Herein is the first clue; Smokey, that you might be entering a world of pain. Zurmo code is highly abstracted. Trying to trace the program execution by following these proverbial breadcrumbs is an exercise in futility. In short, you can easily get lost in the nuances of the object model and lose sight of the tree for the forest.

Maybe you’re thinking… “well there’s more than one way to analyze an application, I’ll just have a peek at the database.” Great Idea! Why not try that, we’ll wait here until you’re done having a look.

Oh, hi, what’s that? back already? The database looks like what? “Porcupine love…in a bowl of spaghetti…wrapped in a hairball“™, you say?

Now… what were we talking about again? Oh yes, the file structure.

Aside from the most informative index.php we see the following three directories:

2014-07-28 17_38_09-app-readbean-yii

app – The Zurmo application. Includes your customizations, as well as the Zurmo core, and Zurmo application code.

redbean – An PHP ORM library which lets us avoid all SQL procedural code. Maps php classes and relations to the database. Redbean allows us the freedom to access the database in an object oriented manner. One reason why the database tables seem inscrutable. Provides the M (Model) -> Database behaviors in the Model-View-Controller paradigm.

yii – The Yii framework. Provides underlying VC (View-Controller) mechanism in MVC. Manages the flow of control and screen rendering.

The good news is that you need never touch the redbean and yii directories. Never.

That leaves us with the app/ directory which we will cover in detail in Part 2.

(c) 2014 Windsor Wallaby. All rights reserved.

Tags: , , , , , , , , , , , , , , , , , | Posted under Zurmo | RSS 2.0

Author Spotlight

Windsor Wallaby

Windsor Wallaby is an independent and enthusiastic Zurmo CRM supporter and Open Source contributor. Active on the Zurmo user forums and a regular personality on the weekly Zurmo developer's conference call, Windsor is committed to building helping relationships by Listening, Learning, Doing, and Sharing. Windsor works with Zurmo CRM daily to track business opportunities and contacts. Windsor also integrates Zurmo as a core platform component for in-house and bespoke IT development projects.

Leave a Reply

Your email address will not be published. Required fields are marked *