Read Me

DIY Framework
http://www.xml.lt/Resources/Framework
info@xml.lt

OVERVIEW

It is an open-source lightweight web application framework based on object-oriented PHP 5, MySQL, and XSLT. It is fully object-oriented and designed following the MVC architecture and REST design principles. The idea behind it is not to reinvent the wheel but instead to combine existing and proven technologies in a convenient and effective way.

The DIY Framework is a compact class library which can be extended and inlcuded by user applications. It puts few restrictions and gives flexibility. In contrast, most of the current web application frameworks are designed inside-out: they define the general structure and only allow your application to fit within their constraints.
For the same reasons, the framework does not contain plugins, scaffolding, routing, AJAX, widgets or other buzzwords. We see them as helper applications at best, not as parts of the framework itself. No frills are included (hence the name) — just precise control over your sever-side code.
Because of the framework's nature, the following descriptions of architecture and file structure should be seen merely as guidelines for applications. They are also used in the included sample files.

Using the DIY Framework, not a single line of SQL or HTML needs to be hardcoded, constructed “by hand” or mixed with the PHP code. Almost no URL hacking or chopping is needed. The UTF-8 encoding is used exclusively.

The framework exploits PHP 5's features such as more advanced object model, type hinting and class autoloading. HTTP request, response and session data is accessed via Java servlet-style OO wrappers. The framework has been straightfordly ported to Java.

It has been successfully used in several small to medium production solutions and is currently used to build a large community-based social website.

For various implementation tips, check our often-updated blog.

The archive contains the framework class library, sample files for building a Model, and documentation. For a full sample application, see DIY Blog. To start from scratch, you will need Propel, unless you are going to use something else as the database abstraction.

ARCHITECTURE

The framework's object-oriented design is based on the MVC pattern.

Model

For generating object-oriented, database-backed Model use Propel ORM, one of the most useful PHP tools you can come across.

Model class structure is totally up to the developer. Using Propel, it has to be defined in schema.xml (it handles inheritance as well) and generated by running Propel generator (see Propel documentation for more information). It will also automatically produce corresponding SQL structure. Model has to be regenerated every time the schema changes.

Model classes should be related to Resources as necessary, e.g. Page would be typically related to a PageResource (by defining a foreign key in schema) an so on.

View

XSLT-based Views render representations of Resources such as XHTML or RSS. XSLT always produces well-formed XML and is the perfect template system in our eyes. No support for other templating systems (such as Smarty) will be included, although you could easily do that yourself.

View is constructed using Resource object for which it will be rendering representation. XML serialization of that Resource is the main XML document for View's XSLT stylesheet to transform (this should be taken care of automatically by the framework).
Views also use the Model by serializing the necessary Model classes (e.g. Post or Comment) to XML documents and passing them to an XSLT stylesheet as arguments. It also sets the content type and takes into account request query parameters if necessary.

Views have to be subclasses of the View class and implement the display() method. For views using XSLT as the template system, there is a special XSLTView that can be subclassed.

Controller

REST and RDF inspired frontal Controller is based on Resources with URIs that implement HTTP methods. Resources are backed by the database and can be easily searched, moved, or given permissions.

Resources should execute the business logic, such as loging in a user or creating a blog post (most likely using data from some kind of Form or plain query parameters), and return an appropriate View. They can be related to Model classes. That helps to create modular code that can be easily moved.

Each Resource class has an URI and implements methods as in HTTP: doGet(), doPost() etc. Controller selects the Resource by matching its URI against HTTP request URI (stripped off of the query parameters), and its method to be executed is the same as the HTTP request method. Resource URIs should be relative to the application host name and not have a leading slash, e. g.: Resources/Framework. They are case-sensitive.
That way, Resources can have meaningful and user-friendly URIs such as Futurama/Characters/Dr+Zoidberg/ with no extra work instead of awkward query parameters as in Futurama/Characters.php?id=236542. They are totally independent of physical files and paths.

Application Resources have to be subclasses of the framework's Resource class. This is achieved by specifying lib.diy-framework.classes.diy-framework.controller.Resource (modify according to your actual framework location) as the baseClass attribute for the application Resource table in schema.xml.
The Resource class can be used to implement logic common for all resources, e. g. checking if the user is logged in. Each application also has to implement subclass of Controller and call the parent process() method, as well as a subclass of ResourceMapping which should wrap the application's ResourcePeer generated by Propel.

There are several helper classes offered by the framework: Forms help to abstract the query parameters of a HTTP request in a more meaningful way, and Commands can be used for complex business logic that does not fit nicely in a Resource.

LIFECYCLE & CONTROL FLOW

   1. app.php receives a HTTP request, includes the neccesary files, and executes the AppController::process()
   2. AppController calls the AppMapping::findByURI() to match the request URI against URIs of AppResources
   3. If a matching AppResource is found, control is passed to it. Otherwise, 404 Not Found is returned.
   4. AppController executes the appropriate method on matched AppResource and retrieves an AppView
   5. AppController executes the AppView object's display() method
   6. AppView renders the AppResource representation from the application's Model data
   7. AppController writes out the AppView's output as the HTTP response and the application lifecycle starts anew

REQUIREMENTS

   1. PHP 5 (not compatible with PHP 4)
   2. PHP's XSL and database (e. g. MySQL) extensions
   3. MySQL (or another database supported by Propel, although this has not been tested)
   4. Propel (with Creole)
   5. URL rewriting enabled on the webserver (e. g. using Apache's mod_rewrite)

FILE STRUCTURE

Suggested file structure follows the MVC architecture. Each application should have its own folder, with View and Controller folders within. Model should have its own folder to be shared by several applications. Also, it is convenient to put your own apllication classes in one folder, and libraries in a separate one. A typical file tree could look like this:

    * classes/ — directory for your own code
          o test-project/ — project with several applications
                + app — one application
                      # controller/
                            * forms/ — directory for application forms
                                  o AppForm1.class.php
                            * exceptions/ — directory for application exceptions
                                  o App1Exception1.class.php
                            * AppController.class.php — application Controller
                            * AppMapping.class.php — application ResourceMapping
                      # view/
                            * specificView1/ — a directory for each specific view
                                  o SpecificView1.class.php — a specific View class
                                  o SpecificView1.xsl— a corresponding XSLT stylesheet
                            * coommon.xsl — XSLT stylesheet for common templates
                            * master.xsl — general (master) XSLT stylesheet, if necessary
                            * AppView.class.php — general application View class
                + app1 — another application, same structure as above
                + model/ — Model shared by applications; generated by Propel
                      # om/
                      # conf/
                            * test-project-conf.php — Propel configuration to include
                      # map/
                      # sql/
                            * schema.sql — Database schema SQL
                      # *.php — Model and Resource classes
                + view/ — View shared by applications
                      # ProjSerializer.class.php — XML serializer for Model objects
    * docs/ — documentation
    * lib/ — libraries
          o creole/ — Creole
          o diy-framework/ — DIY Framework
          o propel/ — Propel
    * static/ — directory for static content (requests to it are not handled by the framework)
          o css/
          o files/
          o images/
    * app.php — the entry point to the Application
    * app1.php — the entry point to the Application 1
    * common.php — for common includes and path settings shared by applications
    * .htaccess — Web server configuration
    * build.properties — Propel project properties
    * runtime-conf.xml — Propel database configuration
    * schema.xml — Model definition for Propel to generate classes and SQL from

Each PHP class has its own file with an extension .class.php.

app.php, app1.php etc. are the very entry points to the applications, which should call their Controllers to start the application lifecycle. These files (as well as some common.php, if necessary) should be used for setting include paths and including libraries.

Resources belong to the Controller but are located in the classes/test-project/model/ folder by default since they are generated by Propel from the schema definition together with the Model classes.
Getting Started

Here, as well as in the File Structure section and in the framework's sample files, we assume that your project name is test-project and it is located under C:/wwwroot/test home folder.

   1. Create your project and application folder structure as described above
   2. Put DIY Framework together with Propel and Creole as libraries by placing them in separate folders under lib/
   3. Copy sample files from the lib/diy-framework/samples/ to the root (home) folder
   4. Define
          * database structure in schema.xml. Define Model classes and subclass Resources. Relate them to each other by defining foreign keys.
          * database settings for Propel in runtime-conf.xml
          * your new project name and home folder and the rest of database settings in build.properties
      See Propel documentation for more information.
   5. Add full paths of lib/propel/runtime/classes and lib/creole/runtime/classes to include_path in your php.ini
   6. Run propel-gen.bat to generate database classes and SQL. They should be placed automatically under classes/test-project/model.
   7. Create database (with the same name as in schema), make it accessible to the user defined in runtime-conf.xml, and execute SQL from classes/test-project/model/sql/schema.sql on it
   8. Insert initial data into the tables (at least to the AppResource, otherwise the Controller will not be able to match any request URIs)
   9. Implement classes
          * AppController as a subclass of the framework's Controller.
            It has to call parent::process().
          * AppMapping as a subclass of the framework's ResourceMapping.
            It has to wrap the AppResourcePeer class, which was generated by Propel.
          * AppView as an abstract subclass of the framework's XSLTView.
            It has to call parent::display().
          * SpecificViews as subclasses of the AppView, each of the them located in its own folder.
            Each of them has to have a corresponding XSLT stylesheet in the same folder and to call parent::display().
          * AppResources (they should be already properly subclassed by Propel generator)
          * Model classes (those you defined in schema)
          * ProjSerializer as a subclass of the framework's Serializer.
            It has to call parent::serialize().
      All of the classes should by autoloaded automatically by app.php except for SpecificViews, since they are located in arbitrary folders. You will have to include them manually or edit the __autoload() function.
      Later you might want to subclass and implement Form and other helper classes.
  10. Change the AppMapping::HOST constant value to your actual full host name with the trailing slash, e. g.: http://localhost/ or http://www.host.com/
  11. Make sure the webserver is configured (e. g. via URL rewriting in the .htaccess file) to let app.php handle all requests for dynamic pages
  12. The site is ready to run!

TO DO

Work needs to be done on:

    * Moving to Propel 1.3
    * Exception handling
    * Autoloading
    * XML serialization
    * Caching

LICENSE

The DIY Framework is released under a LGPL license.
Features

    * MVC design
    * Fully object-oriented PHP 5
    * Focus on RESTful resources and URIs
    * XSLT-based views
    * Database ORM support