Haxe/PHP: dissecting "Hello World!"

In this tutorial it is explained how the Haxe/PHP generator deals with a simple "Hello World!" application.
Let's start with a simple class defined in a Test.hx file.

class Test {
    public static function main() {
        trace("Hello World!");
    }
}

The code doesn't really need any explanation; just remember that trace is a special function that is a shortcut for the static function haxe.Log.trace().

The above code can be compiled with the following test.hxml file:

-php www
-main Test

You can compile it by double-clicking on the file if the extension is already associated or type haxe test.hxml from the console/command prompt.

A new folder www is created and filled with sub-directories and a bunch of files. Let see what has been generated and why.

First there is a file index.php; this has been generated because we used the -main switch in the compilation process. index.php is the entry point of our application and it executes just three simple actions: check that our PHP version is up to date (PHP v.5.1.x or higher is required, but most is tested in PHP v.5.2.x). The second thing is to include the Boot class (more on that later) and third invoking our Test.main() method.

Along in the same directory a lib dir is generated. The directory contains the packages and type definitions from out Haxe code. For every type defined in Haxe (classes, enums and interfaces) an individual file is created. So, if you have ten types defined in a single .hx file, you will see 10 PHP files generated in your lib directory. You can deduce the type from the file name. For example the Hash class generates a Hash.class.php file. Note: no files will ever be generated for typedefs.

Packages are generated as folders. Since PHP does not support namespaces or packages (5.3 will introduce this feature) the generated classes are prefixed with the containing package name. So the Log class defined in lib/haxe/Log.class.php is defined in PHP as haxe_Log. Note for users who want to use Reflection: use the names as defined in Haxe not in PHP!

We have talked about the Boot class but what is that and why is needed?

PHP and Haxe are very different in nature. Haxe supports passing functions by reference where PHP supports only passing by name; arrays in Haxe must start at the 0 index and every position between 0 and length must exist even if the value is null, that is not true for PHP. So the Boot class tries to unify those behaviors as much as possible (the very few edge cases will be documented in another tutorial).
Another role of Boot is to enable the autoloading feature. This feature is very important because permits to load just the required classes at runtime avoiding static references to all the files in the lib repository. This also means that potentially you can have Haxe an application that has generated 100 hundred files but uses just a third of them when executed.

So we now know why we have index.php, php/Boot.class.php, haxe/Log.class.php (used by the trace function) and Test.class.php (our entry class). But why are there other seven classes? Where they come from? Well, Haxe/PHP always generates the code for Date, Std and Xml and it happens that those classes requires somewhere the generation of the missing four classes. Since it uses autoloading there is no real impact in your application to have those classes in the lib even if they are not used. Why those classes are always generated is argument for a more advanced tutorial but my advice is to not remove them and always include every file in the lib in your deployment server.

You are probably wondering how can you deploy more than one application without having copies of the same file. Well, if you can make sure that you compile all of your application with the same version of Haxe (and external libraries) you can generate your code always in the same lib dir. Types are generated always in the same way and thus no conflict is possible. Just keep in mind that using Reflection in one application will enable you to use code generated from another application; this can be good or bad.

If you generate more than one application in the same directory you will probably want to create different entry files than index.php. You can do that using the switch --php-front other.php.

version #4713, modified 2008-10-22 12:10:51 by ponticelli