xp-framework/rfc — Issue #119: Support self-running XARs
Author: kiesel
Created: 2011-10-17 15:56:15+00:00
State: open
Labels: draft, framework

Scope of Change
====
The framework's core will support running programs straight out
of XAR files with no further infrastructure required (except a
working PHP binary).

Rationale
====
This will faciliate providing single file applications, such as
desktop (GTK) applications and eg. installers.
Further, it'd become possible to ship console programs and even
whole web applications that can be installed by copying over a
single file into the document root.

Functionality
====
Self-running xars are a PHP file with the framework's bootstrap file
lang.base.php's contents at the top and a complete XAR file after the
__halt_compiler(); marker. Additionally the XAR file optionally contains
a special file named META-INF/manifest.ini in it: This file contains
meta-information about the archive and the name of the default
class to run open invocation.

Self-running xars need to be prepared in a special way:
. create xar containing all files:
+ "core" class files
+ application specific files
+ meta information for the runner
. prepend contents of lang.base.php

The final file can be run by just invoking php on it:

```
$ php runner.xar

```

Because the xar is prepended with lang.base.php's contents, it will
be run and detect that it's not running in standard mode, but in
self-running mode.
Unlike in standard mode, lang.base.php will load the class
lang.archive.ArchiveRunner and pass control this class' run method, in
which the program execution is triggered.

Once the program flow returns to lang.base.php, it'll immediately
stop execution with the exit() command.

The lang.archive.ArchiveRunner is responsible for
. determining the sapi
. loading META-INF/manifest.ini, if needed
. depending on the sapi, find the class to run

Determining the class to run is dependent to the sapi due to different
ways how the environment signals users choices which class to run:
+ for a console application, command line arguments may be used
to select the class to run
+ for web applications GET or POST parameters or cookies may have
influence on the decision.

The META-INF/manifest.ini can contain the following information:

```
[sapi::cli]
main-class="fully.qualified.ClassName"

[sapi::web]
main-class="fully.qualified.ClassName"

```

Security considerations
====
n/a

Speed impact
====
It is a requirement that this change does not impact speed of
the framework.

Dependencies
====

Related documents
====
- http://experiments.xp-framework.net/?people,kiesel,php,selfrunning
Prove of concept experiment

- http://xp-framework.net/rfc/0108.rfc.html
xp-framework/rfc #108: Make XAR files runnable by XPCLI