Distributing a new or existing web application on La Distribution is really easy. All we have to do is to embed the application in what we call a package. As of today, La Distribution can theoretically support all PHP web applications, this mean there is tons of potential applications to package.
In this tutorial we’re going to package Moonmoon a PHP based PlanetPlanet clone. It’s relatively simple, it’s representative of a typical web application, and better, it’s from my friend Maurice! Frankly, I had no clue if the packaging was possible before starting writing this tutorial, so let’s cross our fingers.
Create the simplest package.
For the first step, we’ll focus on the basics: the deployment procedure. We’ll let the user finishes the installation through the Moonmoon install form.
Let’s start.
-
Create an empty folder named ‘package’ containing 2 sub-folders: ‘application’ and ‘dist’.
-
In the dist folder, create a ‘manifest.xml’ file with the following content.
<package>
<id>moonmoon</id>
<name>Moonmoon</name>
<version>8.12-1</version>
<type>application</type>
</package> -
In the ‘application’ folder, copy all the files of the application you want to package. You can download Moonmoon here.
You should now have the following structure:
-
Now, zip everything in the ‘package’ directory (but not the ‘package’ directory itself). The ‘application’ and ‘dist’ directories must be at the root of the zip archive.
Test the package
-
Log in your La Distribution install, go in the Repositories panel and create a local repository if you don’t have already one.
-
Upload the zip archive you just created.
-
You should now be able to install a new instance of Moonmoon in the Applications panel.
Doh!
The cache directory was not created! I could have fixed that in the tutorial before but I chose to keep it real. It’s a common issue when trying to copy empty directories. One way to fix it is to create a dummy non empty file in the empty directories.
-
Now update your package version in the ‘manifest.xml’ file.
<package>
<id>moonmoon</id>
<name>Moonmoon</name>
<version>8.12-2</version>
<type>application</type>
</package> -
Go on your Repository panel, upload the new version.
-
Go on the Application panel, update the application, it should works now!
Handling advanced installation
Because we want La Distribution to provide the same experience for all applications, we now have to skip Moonmoon install form.
There are generally three approaches to integrate an installation process with La Distribution:
- Use the web installer provided by the application, and interact with it with PHP through HTTP. Isn’t that quirky ? Yes it is, but we don’t have often the choice, and well, you just have to say yourself it’s like using a REST API ;-)
- Use the application libraries to perform the install. It’s currently rare but it’s the best approach, the La Distribution WordPress package has been developed this way for example.
- Code directly in the package the installation procedure, by handling the necessary steps.
For Moonmoon, the install procedure is so simple that we’ll go with the third solution. Generally, it’s always easier to do the first, while the second is the one we have to promote, particularly for complex installs.
Introducing the installer
Basically, an installer is a PHP class that must be added in the ‘dist’ directory, named installer.php and extends the Ld_Installer class provided by La Distribution.
Now, let’s have a quick look at Moonmoon’s install.php file, line 9 to 25. It seems like we’ll just have to create two files. Let’s code that!
class Ld_Installer_Moonmoon extends Ld_Installer
{
public function install($preferences = array())
{
parent::install($preferences);
require_once($this->absolutePath . '/app/classes/Planet.class.php');
$config = array(
'url' => 'readonly',
'name' => $preferences['title'],
'items' => 10,
'shuffle' => 0,
'refresh' => 240,
'cache' => 10,
'nohtml' => 0,
'postmaxlength' => 0,
'cachedir' => './cache'
);
$planet_config = new PlanetConfig($config);
Ld_Files::put($this->absolutePath . '/custom/config.yml',
$planet_config->toYaml()
);
Ld_Files::put($this->absolutePath . '/admin/inc/pwd.inc.php',
'<?php $login="admin"; $password="' .
md5($preferences['admin_password']) .
'"; ?>'
);
}
}
?>
The install method will be automatically called when the user will create a new instance of the application with the La Distributions user interface.
Where does the preferences parameter come from?
The preferences come from the information entered by the user in La Distribution’s install form. By default, only the ‘title’ and ‘path’ preferences are present in this install form but you can add other preferences in the manifest file.
The ‘admin_password’ preference does not exist yet. So we’ll have to declare it in the manifest.
<id>moonmoon</id>
<name>Moonmoon</name>
<version>8.12-3</version>
<type>application</type>
<install>
<preference type="password" label="Admin Password" name="admin_password" value=""/>
</install>
</package>
Don’t forget to increment the version number of the package. Packages are cached and you may become mad if you don’t do it!
Also, you can now delete the install.php file of the Moonmoon application as it is now useless.
Now, create the zip, upload it, test a new installation. Everything perfect!
Next?
In a next tutorial, we’ll see how to handle advanced users integration (SSO and Roles) and UI integration (integrating the permanent bottom bar).
As you can see, with a minimal technical background, creating La Distribution packages is fairly easy, now what are you waiting for to create your owns?
Thanks Benoît for reviewing this tutorial!
Yeah, great!