Textura - a tiny MVC framework
==============================
This is Textura, a very minimal MVC framework written in PHP. The main goals of
this project is purely educational, it is not intended to be used in a
production environment (not yet anyway). Use it at your own risk, I will not
take responsibility for any usage of this project.

Since this is a school project for me new parts will be added to the project as
the course progresses. I don't know exactly what parts of the framework is
needed to pass the course, but my final goal for the term is that this project
will be usable as a starting point for building your own framework.

Licence
=======
Textura is licenced under the GNU GPL (Version 3 or later). Please see the file
COPYING for details about the licence. The licence only applies to the following
files:
router.php in the current directory
All files under the src/textura directory

Please see the section "External dependencies" for the licences of the other
parts of the code base.

Design
======
Textura is designed to be very simple. To get started, you will need just a few
things.

* Place a file called config.yml in the root of the site dir. That file will
  contain all your configuration. For an example on how it should look, you can
  just copy or rename site/config.yml.sample. The configuration file is written
  in YAML format, so for any syntax issues please check out http://www.yaml.org/

* Place your controller classes in site/controllers. All controllers must
  inherit from Textura\Controller in order to be loaded by Textura.

  - When you define a (public) method in a controller class it automatically
    becomes an action that can be called from the outside world. So if you have
    a controller handling /, the method foo will automatically be called when
    the browser visits /foo.

  - In a controller you can automatically create "properties" by using
    $this->property syntax. For instance, $this->username = 'Homer' sets the
    property username to 'Homer'.

  - There are also some "special" properties that are always available in the
    controller.

    - $this->action refers to the current action (a string)
    - $this->application refers to the current application (an instance of the
      Textura\Textura class).
    - $this->controller refers to current controller (an instance of the
      Textura\Controller class). When used in controller context this variable
      simply points to the same object as $this, but it is more usable in view
      context where it can be used to get the current controller.
    - $this->request refers to the current request (an instance of the
      Textura\Request class).
    - $this->response refers to the current response (an instance of the
      Textura\Response class)

    These special properties should be considered *read-only* from
    controller/view code.

  - If you intend to send data directly to the client without using a template,
    you can use $this->response->appendToBody to add content and
    $this->response->setHeader to set headers. Of course you can also use stuff
    like echo and var_dump, but that way of sending data is discouraged as it
    *will* mess up the Content-Length header and therefore might confuse some
    clients.

* Place your views (Haml files) in site/views. The directory structure under the
  views directory should follow the controller mapping, so if you have a
  controller that handles /foo your views for that controller should be placed
  in views/foo. The file name of the template file should match the name of the
  action (method) in your controller. If Textura cannot find a matching template
  it will simply ignore the missing file. For more info about the Haml format,
  please visit http://haml.info/.

  All properties set in the controller can be used in the template. If you use
  $this->username = 'Homer' in your controller code, you can refer to the same
  variable in the HAML template by using the $username variable. Also, all
  "special" controller variables can be used:

  - $action refers to the current action.
  - $application refers to the current application.
  - $controller refers to the current controller.
  - $request refers to the current request.
  - $response referes to the current response.

* Models are only partially implemented. While I work out the details, please
  roll your own.

* Static content should be placed in the site/static folder. Some shortcut
  aliases (/s and /static) are defined in the .htacess file in the top
  level directory. If you want to use additional aliases please define them in
  the same file.

* Intra-application routing is available through the Controller class. The
  following methods are available:

  - Controller->r($controller, $action, array $params) can be used to get a
    route to an action in another controller.
  - Controller->rs($action, array $params) can be used to get a route to an
    action is the current controller.
  - Controller->rst($params) can be used to get a route to content in the
    site/static directory.

Globals
=======
Globals are evil. Textura goes very far when dealing with this problem.

$_GET, $_POST, $_FILES, $_REQUEST, $COOKIES, $_SERVER and $_SESSION are *not*
available when using Textura. The data in those variables can all be fetched
from the Textura\Request object instead.

Plugins
=======
Textura is designed to be a very minimal framwork. Only the bare minimum of
functionality are available in the core classes. In order to extend Textura
without affecting the core functionality a simple plugin system is used for
adding functionaliity. At the moment no "hooks" exist in the framework to let
a plugin add data to the request/response "automatically", so adding a plugin
simply allows some extra classes to be loading without manually requiring them.

At the moment the following plugins are available:

FormBuilder - a plugin for building forms dynamically.
ThemeBuilder - a plugin for building "themes" dynamically.

I you want to write your own Textura plugin, it must implement the
Textura\Plugin interface. Please see the file
src/textura/core/interfaces/Plugin.php for details on what methods you need to
implement in order to transform your class into a Textura plugin.

Loading a plugin is done by adding a reference to the plugin in the
configuration file. Please see the section 'plugins' in the
site/config.yml.sample file for details.

External dependencies
=====================
At the moment Textura depends on some external libraries:

* PHP Html Builder (for building HTML forms) [src/htmlbuilder directory]
  Home page: http://htmlbuilder.history-archiv.net/
  Licence: GNU GPL version 3 (http://opensource.org/licenses/GPL-3.0)

* phamlp (for rendering HAML templates) [src/phamlp directory]
  Home page: http://code.google.com/p/phamlp/
  Licence: BSD 3-Clause (http://opensource.org/licenses/BSD-3-Clause)

* spyc (for parsing YAML files) [src/spyc directory]
  Home page: https://code.google.com/p/spyc/
  Licence: MIT (http://opensource.org/licenses/mit-license.php)



---
Textura is written and maintained by Lars Olsson <[email protected]>