webAppKit blog - news

Zero Dot Nine

J.Ducastel — Tue, 30 Oct 2007 14:10:00 +0100

If you take a look at the roadmap, you'll see some changes. A development branch has been started, numbered 0.9 (odd minor versions numbers will now be for development versions - even for stable ones). The 0.8 still live in the trunk for now. Milestones are set up to 0.14.

So what's new ?

Services have disapperead and are replaced by Tools, which are accessed as Kits members.
Storages are now Tools themselves, provided by webappkit/storages.
Kits API have changed a bit. Most methods are static ones. Kits metadata and libraries are now loaded before Kit instance building, to allow some kits to override the generic webappkit class.
PHP version range compatibility can be defined in Kits metadata.

The help file in the repository have been updated with new tutorials. I hope to release 0.10 rather quickly, has goals previously set for 0.9 have been sparsed over three milestones.

Here is the content of the updated help file :

Using a Kit

Unzip webappkit at the root of your web application. It's probably done as the file you're reading is part of it. It creates a webappkit/ folder. Before retrieving any Kit, put this line into your code :

/**
* getting webappkit core (only once call is necessary)
*/
include('webappkit/include-me.php');

When you need a Kit's resources, let's say ooxmlrpc, load it with :

/**
* loads a kit resources
*/
webappkit::getKit('ooxmlrpc');

If you need only a subkit, let's say http within databeans, get it with :

/**
* loads a subkit's resources
*/
webappkit::getKit('databeans/http');

In this exemple, databeans/http requires databeans/databean, but you don't have to take care about that.

webappkit::getkit($id) returns the kit instance. Always use this method to retrieve a kit, as Kits should be singletons.

Tools

Tools are named object instances taking their configuration data from the kit they belong to.

They are retrieved as kit members like this :

/**
 * retrieving the kit instance.
 */
$kit=&webappkit::getKit('helloworld');
/**
 * calling the method "bar" of the kit's tool named "foo"
 */
$kit->foo->bar();

Storages

Storages are specific Tools. They build and retrieve object instances stored within kits files.

You use them just as any other Tool, as a kit's member. For example, let's get a template from our sample kit :

/**
 * retrieving the kit instance.
 */
$kit=&webappkit::getKit('helloworld');
/**
 * getting the template from the storage, which is named "templates"
 */
$tpl=$kit->templates->getItem('help');
/**
* using the 
*/
echo $tpl->render();

Building a Kit

Let's build a Kit named mykit, which will contain a couple of class definition files.

Create a folder named mykit.wak within your webappkit/ folder.
Put your code files inside, let's say myclass.class.php and mychildclass.class.php which is extending it.

Create an INI file at its root named wak.ini and edit it :

[kit]
; kit-wide meta informations
version = "0.1"
; kit version. Will be used later.
desc = "This is my first kit. It will rocks !"
; a short description. Single line to be INI compliant !
phpversion = "4.3-5.*"
; define which PHP versions range compatibility (optional)
; you can use a single version string with jokers, as 4.*

[load_kits]
; kits to load before self resources, order will be preserved.
; n = "absolute kit id"
0 = "datapath"

[load_files]
; self resources to load, order will be preserved.
; n = "relative/path/to/file"
0 = "myclass.class.php"
1 = "mychildclass.class.php"

This file describe Kit's resources and dependancies. Kits and files will be loaded in the order you defined.

Here we're done with the main kit.

Please note that Kits are singletons and won't be instanciated twice. Hopefully.

PHP version auto-switch

You can have a library file for each PHP versions, and tell the kit to load the appropriate one upon the current PHP version running.

To do this, we will name our files with the specific extensions : .php4 and .php5 , and then edit the kit's INI as this :

[load_files]
; self resources to load, order will be preserved.
; n = "relative/path/to/file"
0 = "myclass.class.php*"
1 = "mychildclass.class.php*"

Using * at the end of the file name will trigger the load of .php4 or .php5, upon the current running PHP version.

Building a subkit

Kits can contain subkits, which can be either optional or loaded by their parent kit.

It will also require another kit, webappkit/datapath, and provide an extension as an optional subkit named mysubkit.

Into mykit.wak/, create a folder named mysubkit.wak
Put its own code files into it, for example anotherclass.php4 and anotherclass.php5, which are PHP4 and PHP5 versions of the same class as seen before.

Create its wak.ini file at its root :

[load_kits]
; kits to load before self resources, order will be preserved.
; n = "absolute kit id"
0 = "mykit"
1 = "pathnodes"

[load_files]
; self resources to load, order will be preserved.
; n = "relative/path/to/file"
0 = "anotherclass.php*"

As you see, this subkit requires its parent kit and another kit, pathnodes. It also requires datapath, but this dependancy is already defined by parent kit.

A subkit may contain itself a subkit and so on.

Subkits auto-loading

If we want the parent kit mykit to load its subkit when loaded itself, we can add this into mykit's wak.ini file :

[load_subkits]
; subkits to load after self resources, order will be preserved
; n = "relative subkit id"
0 = "mysubkit"

The subkit will be loaded after paren'ts kit dependancies and own files.

Adding Tools

Tools have to be declared within kit's wak.ini file :

[load_files]
0 = "worker.class.php"

[tools]
; name = "class"
bob = "worker"

Here we have declared a tool wich will be named bob within the kit and will be an instance of the class worker.

Tools classes have to extends wakTool class. Their definition file can be included within the providing kit or one of its dependencies. Here it's an included one. Let's look at its class definition :

class worker extends wakTool {
        /**
        * a Factory function : every Tool has to declare it
        * @static
        * @param string $kit kit's id
        * @param string $name tool's name within kit
        * @return object worker's instance
        */
        function & factory($kit,$name) {
                return new worker($kit,$name);
        }
        
        /**
        * here is an useful function
        * @return string hairs color
        */
        function getHairs() {
                return $this->cfg['hairs'];
        }
        
        /**
        * @var array the default configuration values
        */
        var $cfg=array('hairs'=>'red');
}

Now, we can get tool bob from our kit and it will have its default config :

$kit=&webappkit::getkit('mykit');
/**
* this will print 'red'
*/
echo $kit->bob->getHairs();

Borrowing tools

But our worker class can now be used in another kit, by declaring it in the kit's wak.ini file :

[kit]
desc = "this is another kit, providing a worker tool borrowed from mykit"

[load_kits]
0 = "mykit"
; we need its "worker" class for alice service

[tools]
alice = "worker"

And let's override its config. Create a file named alice.tool.ini at the anotherkit's root :

; this is the alice tool config file for anotherkit
hairs = "blue"

Let's look at our second tool instance :

$kit2=webappkit::getkit('anotherkit');
/**
 * this will print "blue"
 */
echo $kit2->alice->getHairs();

And you can also have several instances of the same tool within the same kit, each with its own config.

Adding storages

Storages are just specific tools. Just like them, their definition file can be included within their providing kit, or they can just provide a config file for a tool class taken from an external kit dependancy.

They have to extend wakStorage class, which is provided by webappkit/storages kit.

Their function is to retrieve object instances stored in files within the kit.

Here we will get templates from our kit, using a storage class provided by djtpl template engine kit.

Here's our kit's wak.ini :

[load_kits]
; getting dependancies, including the storage class
0 = "djtpl"
; please note that djtpl kit itself require webappkit/storages

[tools]
; declaring storage, name = "class"
templates = "djtplstorage"

And now we override some storage config in templates.tool.ini :

; this is the templates storage config
search = "views/{{lang}}/{{id}}.{{type}}"
; here is the filename template for files search
[critera]
; the defaults values for search criteria
lang = "en"
type = "html"

This settings indicate that template files will be stored within a views/ folder within our kit, having languages subfolders, and that files are named by id.type. The default language is set to en, and default type to html.

Now, let's get a template from our kit. First, we will change the language default value to fr. Then, we want the template having the home id.

/**
 * changing a criteria's default value
 */
$kit->templates->setCriteria('lang','fr');
/**
 * getting a template
 * string criteria will be taken as 'id'
 * or you can provide an associative array for more criteria
 * missing criteria will be taken from current defaults
 * this will build a template instance from views/fr/home.html
 */
$tpl=$kit->templates->getItem('home');
/**
* rendering the template
*/
echo $tpl->render();

doc updated, 0.8.1 onwork

J.Ducastel — Tue, 29 May 2007 19:10:00 +0200

Almost everything is in the title.

Code documentation has been updated and is still available at code.webappkit.net.

Version 0.8.1 is onwork. Here's the news :

Kits resources loading is now separated from kit instance retrieval. Methods $webappkit->load() and webappkit::loadkit($id) have been added, which are not called by webappkit constructor.
webappkit::timecounter() and $webappkit->loadedWeight() have been added to help optimization.
Admin index (when calling url /webappkit from your app root) is not static anymore. It still includes micro tutorials, but provided kits list is now dynamically built from actual kits.
A new pathnodes subpackage is being worked on : webappkit/pathnodes/od which stands for Open Document.

Code documentation - alpha coming

J.Ducastel — Tue, 15 May 2007 18:39:00 +0200

Some code documentation has been generated and is online at code.webappkit.net. It covers the core kit and subkits code. It may be useful to people using provided generic libraries, such as databeans (data structures), pathnodes (filesystem) and Django templating engine php implementation.

I plan to release 0.8.0 as an alpha version sometime soon. The foundation is there, and work have been started on appEngine, the basic framework to be used by the web admin.

Release soon, release often. Any help is welcomed.

more big changes

J.Ducastel — Fri, 13 Apr 2007 23:09:00 +0200

(i'm evil)

As i was not happy with previous packages/resources system, i've trashed and recoded it - again. It was starting to be bloated and complex, and not that agile. So, to summary :

Packages are renamed to kits. A single class, webappkit, is used both as kit instances and global API (through its static methods). Kits can contain kits themselves, and kit names are made upon the physical tree (databeans/datetime for example).

A INI metadatafile, named wak.ini is required at the root of the kit. With this we take care of dependancies, both internal and external. For more flexibility, a wak.init.php may be included, if present, when the kit instance is built. A wak.run.php may also be present, and will be executed upon call of its run() method.

Services and non-code objects storage have to be implemented at this point. But various library packages have been converted to the new standard :

databeans
pathnodes
djangotpl
Spyc

Generic resources

J.Ducastel — Wed, 11 Apr 2007 20:38:00 +0200

The previously announced move has been started. Packages resources will be made generic, so their access and management will not be devoted to packages directly but to type-specific implementations of a generic resource class. Here's a changelist :

A new interface : wakResource, and a first, incomplete, implementation : wakResource_class. wakResource_service, wakResource_template to follow.
Changes have been made to wakPkg methods
The package metadata file format has also changed.
As a side note, the trunk compability will now include both PHP4 and PHP5, with an automatic switch between resource instances. Current move has still to be ported to php5, though.

Discussion group created

J.Ducastel — Thu, 11 Jan 2007 20:22:00 +0100

A google group has been created to discuss webappkit. You'll found it at groups.google.com/group/webappkit. Feel free to discuss the project, which is eagerly awaiting for contributors ! ;)

Some activity

J.Ducastel — Thu, 11 Jan 2007 13:19:00 +0100

In no particular order :

Home page has been updated, with links to googlecode pages.
Branch 0.5 has been added to subversion, for history purposes, and because some web apps are still using it.
Some minor work has been done to the source and wiki documentation.

svn moving to googlecode

J.Ducastel — Thu, 21 Dec 2006 14:31:00 +0100

As a good google slave, i've decided to move webappkit from sourceforge to googlecode, which has been recently improved. => webappkit on googlecode.

Google added a wiki and downloads to their open-source projects hosting offer. Coupled with their faster subversion server, issue tracking and neat web interface, it's now a good choice for project hosting.

I took the chance to change folders struture a bit. Legacy branches are now under branches/ as 0_7_php4 (the old php4, microkernel architecture) and 0_8_php4/ (the new packages architecture, but php4 version). Under trunk/ is the onwork php5, packages architecture, which may be released as 0.8 later.

Additionaly, some pages are available on the google-hosted webappkit wiki. The old, self-hosted one will be trashed soon.

first rebuilt version available

J.Ducastel — Thu, 14 Dec 2006 20:28:00 +0100

I've just added php5 to repository (revision 150). As announced, there are some huge changes in process. Basically, WAK is moving from a generic micro-kernel for web apps, to a packages architecture for web apps.

Packages are the new central interface. A package is a folder containing an index/metadata file (wakpkg.yml) describing provided resources. Thoses resources will be accessed through a wakpkg instance. Resources can be :

class definition files
services (named singleton within the package namespace, extending from wakservice class)

Class dependancies will be handled provided they are described within the metadata file.

Massive refactoring

J.Ducastel — Wed, 06 Dec 2006 11:41:00 +0100

After some doubts on project future, i have decided to keep on working on webappkit rather than dropping it for some existing frameworks. I've been looking at Django, Symfony and CakePHP. Django is by far my favorite, and i use it to practice my python. However PHP is still the most used language, and i think that webappkit approach still makes sense.

But i'm going to rewrite big parts of the project, focusing on packages since the beginning rather than a virtual layer on the top of the internal structure. Packages will have a physical representation as directories, and may provide their own libraries, services etc. They may have their own request handler.

The core components will theirselves be shipped as a package. It will provide a small api giving access to packages, services and libraries. Some basic requests handling libraries and services will be provided, but this task may be forwarded to one or more package(s). Think to webappkit as a meta-framework.

Welcome...

J.Ducastel — Fri, 23 Jun 2006 15:57:00 +0200

...on webappkit blog. Here you will read news about webappkit, a generic kernel for building web-applications with PHP. Not much to say for now, webAppKit is still in alpha stage and won't be released, even beta, anytime soon. But stay tuned !

By the way, we're searching for PHP, object-oriented developpers. You will find some information and documentation on the wiki.