Design

I wanted to create a framework that used the familiar Model/View/Controller design combined with Android's resource management and a few tweaks of my own to make things "fit" better in my mind. I decided to use terms borrowed heavily from theater because that seemed to help me understand what was going on with the framework. I also changed the Model/View/Controller slightly so that they are not tightly coupled; Controllers can load any number of Models and are not restricted in which View will be loaded. I also added a new structure called a Scene that is basically a "messenger" between Controller and View so that while they are decoupled, information can pass freely between them. Typically, a Controller will load whatever Models, if any, it needs to set variables inside the Scene and that Scene is then passed into the View to get processed as a web page (standard HTML/PHP page, not a template).

Consider an audience (users) viewing a play. The stage is the user's browser. The play has one Director that oversees all the Actors and Props for the play. Actors have actions to perform using Props for the Scene of the play resulting in a View of the stage. The URL for a page will map to an Actor::action (Controller). The Actor::action can then load Props (Models) to use, maybe calling upon other Actor::actions before passing processed data via the Scene to a particular View.

Actor = Controller

Business logic for your Views. Much of the behind the scenes work preparing for a page render is handled here. Each public method an Actor defines is an Action that may be called from the URL. Actions are auto-mapped to the URL so merely defining a "public function bar()" inside Actor "foo" results in a URL of "http://mydomain.com/foo/bar/" executing said function.

Props = Models

Models are logical representations of data stored somewhere (usually in a local database). Models and controllers are not 1 to 1, a controller (Actor) may not have any model associated with it and models can, and frequently do, have more than one model open at a time. Each model can work with whatever they want inside their class. They are logical models, and therefore do not need to be restricted to a single SQL table. They could manage several SQL tables, access a different database connection altogether, or not even work with SQL data at all.

Views (of the Stage)

Standard HTML web pages. Most Actor actions will try to render a view with the same name as the Action itself. Views are stored inside the view subfolder as "app/view/Actor/action.php" and will automatically be rendered unless the Action returns a URL to redirect to instead. A special variable inside the Actor class ($this->renderThisView = 'json_response';) can be set inside the Actor class method to cause the View with that name to be rendered instead of the action being processed. This is useful for REST server responses that don't usually render anything but XML or JSON as a result.

Scenes

An extension upon the MVC framework in that a Scene lives between an Actor and its View. A scene will define all the data that is to be shared between the two. A generic Scene class is all that is required, but for complex work, you may wish to descend from it by giving it the same name as the Actor and cause that one to be auto-loaded instead. You can provide Actor-specific features this way.

An Actor references its Scene by using $this->scene->some_var and the View will reference the same variable as either $recite->some_var or $v->some_var. Any number of variables can be created in this manner as well as complex concepts such as properties that trigger functions during set and get.

Views can easily reference configuration settings with $v->_config['category/setting'] or even the global Director with $v->_director.

Director

The Director is the global manager that handles all of the delegation and routing required to load the various Actors, Views, Scenes, Resources, and call the Actions requested by the URL.

Resources

Resources are images, strings, rights definitions, templates, menu definitions, and the like. They are designed to be loaded in a similar manner to how Android handles its resources so that supporting multiple languages can be done easily by separate teams and still operate even if only a partial translation is available.

Costumes

A recent innovation for BitsTheater has been discovering the power of using not only phpDoc @var notations, but also having the Eclipse IDE also recognize regular comments with @var notation. Variable hints regarding what class a variable represents gave birth to the idea of Costumes. ABitsCostume is an abstract base class used to wrap around associative arrays and/or JSON strings. Several helper static methods of ABitsCostume let you freely copy data from arrays and JSON strings. Since they wrap around array data, Costume seemed like a perfect name for these kinds of classes. Once a Costume class is being used and an @var hint is defined, being able to use Code Completion makes PHP coding fun again! The `app/costumes` folder contains all the classes that do not fall into any other folder. Costumes are free to be any class descending from any other class, although, if you want access to the Director object, descending from ABitsCostume would save you some headaches. The Joka communication feature relies heavily on Costumes to make sense of the payloads being moved to and from the database.

Regisseur (Stage Manager)

As the framework gained more features and even execute endpoints as CLI actions, the standard bootstrap code that was not Object Oriented started to run into issues in order to keep website and CLI happy and working well together. A refactor was needed to change all of the bootstrap code to be contained within classes that could be descended from in order to let derivative websites do what they require in addition to the necessary framework requirements during initial environment setup. As a result, the Regisseur class was born to handle defining constants and register class autoloaders. A Regisseur is a theater term for the Stage Manager, as this class is meant to handle all the global defines as well as register all of the class loaders being used by the system. If websites need to descend from this class, you will need to use the BitsTheater namespace and save it in the same folder as this class since the WEBAPP_NAMESPACE definition will not exist until after this class had been loaded and defineConstants() has been called. Also, it is safe to extend from this class as it will have already been loaded and usable by the time your class will be instantiated.