binarycloud is a platform for rapidly developing complex web applications. It includes basic services like authentication, permissions, a template engine, database abstraction etc., an extensive collection of libraries, and a framework for configuring the system and building your own logic. During its six-month gestation period, binarycloud was used in two commercial production cycles, and is (in SourceForge lingo) Production/Stable. Go download it.

What follows is a summary of the installation tree of binarycloud r1:

binarycloud/
     core/
          base/
          bin/
          lib/
     docs/
     user/
          conf/
          db/
          mod/
          tmpl/

core/base/
This is where all the base components live:

• db/ This is a standard metabase installation. Check it out on PHPClasses.
• auth/ The authentication component. Sets a user's permissions.
• perm/ Permissions. This relies on user/conf/file_permissions.conf to determine access rules for php files in htdocs/.
• tmpl/ Template Engine. Our template engine is unique in that it does not use its own keywords, etc. The template engine populates a defined master template with modules at runtime.
• err/ Error Handling. We use a custom error handler to (optionally) log all PHP and binarycloud core errors to the DB.

core/bin/
Any useful 'misc' apps are stored here: webalizer for access log reports, some shell scripts for searching and change propagation, etc. This will expand as utilities are integrated into binarycloud.

core/lib/
This is where all libs live. Libraries are logic-only, they never include markup. A sampling of the libraries included in r1:

• Form builder
• Table builder
• Send mail (can send html & plaintext emails)
• Execution timer
• Shopping cart (from phplib)
• Client Sniffer
• Debugging

docs/
PHPDoc and the written system documentation reside in this directory. The generated API documentation (from code comments) is stored in a module html directory so it can be accessed through the webserver. I intend to convert to an SGML documentation source shortly.

user/conf/
This directory contains all of the systemic configuration files for binarycloud:

• defined_constants.conf is loaded at startup, and defines all of the necessary path and configuration constants. Be very familiar with this file.
• file_permissions.conf controls access to files in htdocs. If a file in htdocs isn't listed here, it won't be executed. This file also contains an array of directory names, so breadcrumbs and other apps can use a 'nice' looking string instead of a path.
• prepend.inc - it all starts with the prepend. Our prepend file loads the execution timer, and defined_constants. Based on the settings in defined_constants it then loads prepend_exclude.conf, and checks to see if the file being executed in htdocs/ is excluded from binarycloud. If it is not, prepend then loads debugging, our error handler, error codes, authentication, and permissions.
• prepend_exclude.conf contains an array of files in htdocs which should not be controlled by binarycloud.
• append.inc stops the execution timer, and prints the execution time - it uses append_exclude.conf in the same way that prepend.inc does - we set it up this way because we can foresee the need to append more logic.
• append_exclude.conf is exactly the same as prepend_exclude.conf, but for the appended logic.
• php.ini - we like to keep it here, but it isn't strictly necessary.

user/db/schema/
This is where all of the xml schema files for the database are stored. Metabase uses a simple xml format for doing schema definition, which greatly simplifies the task of creating database tables. This directory also contains files with the .before extension - these files are extremely important. When you install a schema file in a database, Metabase writes out a .before file, which is a copy of your current schema definition file. When you change the schema file, and install it in the database a second time, Metabase checks to see if there is a .before file. If the .before file is present, Metabase updates the database table. If no .before file is present, Metabase tries to create the table. If the table doesn't exist in the database, the table is created - but if the table already exists, and there is no .before file present, you'll get errors.

user/db/objects/
This is where all the data access objects are stored. As a general rule, we like to have one .schema file in user/db/schema/ for every table, and one dbobject for every table. However, there are no hard-and-fast rules associated with querying multiple tables from a dbobject. Database access objects are central to the binarycloud system design: because we use Vdbobjects to talk to the database, we can change abstraction layers, revise sql, etc., without ever having to touch application logic.

user/db/dump/
This directory is where db dump files go. Metabase can extract all of the data from a database table, and spit it out into an XML file. That XML file can be loaded back up into another database.

user/mod/
This is where 80% of your work will take place - the directory where modules are stored. A module is a piece of logic, usually fairly simple (we like to keep complex logic in libs) that presents some markup to the client. All modules are stored in subdirectories. An "application" is a group of associated modules that share the same markup templates (the knowledgebase app is a good example of this concept).

If you have a look in a few of the module directories you'll notice modules are always pure logic. They include whatever markup they need, and populate that markup with data, but they never contain markup. If markup was integrated with the module logic, changing the look and feel of a module would be nightmarish, and upgrading to a new version would be nearly impossible. With external template files, we can tell the module to use a different markup template depending on the context in htdocs. For example, if you have sections of your website that use different colors and graphics, but you need to use the same module in three different locations, you can make three markup templates and pass the right template to the module at runtime.

user/tmpl/
This contains an arbitrary hierarchy of markup, which is globally accessible. There is no particular structure imposed, but it's a good idea to keep things in directories. Markup that is stored in module directories should be unique to that module. If you think the markup will be used by more than one module, put it here.

It may take you a day or so to get used to the system, and a bit of time after that to master it. The directory structure was carefully designed to make it easy to find things, but you will still need to spend a little time to familiarize yourself with the way everything works, and the relationship between different files.

Have a look at www.binarycloud.com, it has more information about the system, a complete set of documentation, and the download itself.

binarycloud.com:
I have ordered a machine that will serve as the (temp) public CVS repository for binarycloud, and will run binarycloud.com. I am actively seeking volunteers who would like to develop binarycloud.com using the system. Here are some of the features planned for the first rev of the site:

• Complete File Registry
• Developer Registry
• Forums
• Knowledgebase
• Documentation
• File Downloads

Up next for binarycloud:
To get a feel for the future of the binarycloud itself, have a look at the future page on binarycloud.com. That page is a complete to-do list for future system enhancements. I'm also working on standards for CVS checkins, and am thinking about how to implement peer review in the process, so the builds remain stable and high quality.

Modules and Apps:
If you are a part of an opensource PHP project that you would like to make into a binarycloud-compatible module/application, please contact me. I would like to use existing code wherever possible, to rapidly expand the capabilities of the core system, and the number of modules and applications available for it.

If anyone has any questions, etc, please feel free to e-mail me at enigma@turingstudio.com - make sure to include binarycloud in the subject. I get a lot of mail.

-- alex