Packages an application

Packages an application

Packages are applications or components ready to be used. It's the way you can deploy your applications, components or library.

To install, upgrade or remove packages we suggest that you use the SiteManager.

When a package is installed it copies the files (queries, events, form, report, webpages, etc…), creates the database structure, inserts records and runs script commands.

Once installed application components or libraries are fully configured and ready to be used.

Prepare your applications

There is not much limitation in what you can put in a package. But for compatibility purposes we have setup a few standards so the packages can be integrated and shared with other applications.

The goal is once the package is installed it's ready to use.

If you need to load classes, set constants or open a database connection you can create a configuration that will be automatically loaded at run time. It's a PHP file that ends with .conf.inc.php and is stored in the includes/ folder.

If you need to set session variables or run queries on the database you can create a postconf.inc.php file in the includes/ folder.

If you need javascript or css libraries to be loaded in the <head> tag of the html pages you can create a .header.inc.php file stored in the includes/ folder.

Documentation

We suggest that all package documentation is stored in the docs/ root directory in a subdirectory that uses the name of the package without versions. For example: docs/phpmyadmin/ for the phpmyadmin packages. Place an index.html file that describes the package in the folder.

Package Description

In the package XML file you have a tag <description>. That tag usually contains information on the package as well as how to start instructions. It also contains links to the user pages and administration pages with the default username and passwords. That should help your users getting started. Also the change logs are often stored in the package description.

Creating the package

Using the package builder

The best way to build a package its to use the package_builder package. It's a step-by-step wizard that will create the package for you taking care of all the file names, xml package description, database dump and zipping.

To use the Package Builder you will need to install it in your project. From the site manager, in the package section install the contentadmin and the package_builder packages.

Then click on the Package Builder link in the tools list to start building your package.

Tutorial on how to use the package builder

Package Naming convention

Packages names follow a naming convention : packagename-majorversion.minorversion for Example : shopingcart-1.23

If it's a package of another application then the naming convention is the following: phpmyadmin_2.6.0-0.3.pkg

The application name and its version are separated with a “_” then the ”-” adds the package version number.

Make sure you don't have a “-” in your package name. The “-” is what separates the package name with its version.

If the application has its own version number always create a package version number. Package version number increments will trigger application updates and allow patches of a same application version to be upgraded.

Commands on install and removed

Commands

The current available commands are : replace, sqlquery, mkdir, mergefile, removefile and copyfile

Commands

replace: replace a string in a file. Used to setup configuration files.

  Usage: replace filename stringfromfile stringtoreplace
  Example: replace config.php @databasename [database]

In the config.php file you have a string @databasename that will be replaced by the value of [database] which is the Database name.

sqlquery: execute an SQL query.

  Usage: sqlquery “sql statement”
  Example : sqlquery “insert into user ('username', 'password') values ('[user_username]', '[user_password]');

mkdir: create a directory

  usage: mkdir dbfiles

mergefile: Merge 2 files into one

  usage: mergefile filename1 filename2 filenameofmerged

removefile: (deletefile) delete a file

  usage: removefile filename

copyfile: copy a file

  usage: copyfile file_or_dir_source file_or_dir_destination

exec: Execute a PHP script in the users project with all the variables in a vars POST array.

  usage: exec my.php_script.php

Variables available in the commands install and remove

Variables available in the commands install and remove:

[absolute_http_path]: Absolute web url to the project: http://www.yourdomain.com/webfusion/projectname/
[relative_http_path]: Web path the project directory: /webfusion/projectname/
[absolute_file_path]: Absolute path to the project: /home/sitecreator/projectname/ files.
[relative_file_path]: Relative path to the project directory, ../projectname
[user_username]: Username, use the database connection login or application username and defaults to “admin” if nothing is found.
[user_password]: Password, use the database connection password or application username and defaults to “sqlfusion” if nothing is found.
[user_password_md5]: “, md5($user_password), $command) ;
[domain_name]: Current Domain name
[projectdir]: Path to the project directory, ../projectname
[abs_projectdir]: Absolute path to the project directory, including subdirectory webfusion/projectname/
[web_dir]: Web friendly directory to the project directory: /webfusion/projectname/
[web_url]: Absolute web url to the project: http://www.yourdomain.com/webfusion/projectname/
[project_dir_fullpath]: Absolute path to the project: /home/sitecreator/projectname/
[project_name]: Name of the project
[server]: Hostname or IP of the database server
[login]: Database login
[password]: Database password
[database]: Database name
[curtime]: Current time stamp
[curdate]: Current date (Y-m-d)
[server_name]: Server Name / Domain name
[password_md5]: Database password encoded in md5
[database_type]: Type of database (mysql/pgsql/sqlite)
[uniqid]: Random uniq id
[refererkey]: Referrer key for remote access authorization.

Examples for 'replace'

Commands on install to set the database information for the phpMyAdmin package:

 replace phpmyadmin/config.inc.php phpmapackageserver [server]
 replace phpmyadmin/config.inc.php phpmapackagedb [database]
 replace phpmyadmin/config.inc.php phpmapackageuniqid [uniqid]

Example for 'exec'

In your install commands you have

  exec pkg_install.php

When the package is installed this script will be executed. It will receive as a POST a serialized array with all the variables.

Example of pkg_install.php to use the variables

<?php  
  /**
   * Package install file
   * This file is called during the package
   * Installation to cleanup the install.
   */
  include_once("config.php");   
 
// If you want to accept GET request as well change this to $_REQUEST['vars']
  if (isset($_POST['vars'])) {
      $vars = unserialize(stripslashes($_POST['vars']));
      $fp = fopen("pkg_install.txt", "w");
      if (is_array($vars)) {
	foreach ($vars as $varkey=>$varvalue) {
           $line = "\n ".$varkey." = ".$varvalue;
           fwrite($fp, $line);
	}
      }
      fclose($fp);
  }
?>

This example just dumps all the variables in a text file. It's up to you to use them to configure or setup applications from your package.

Commands on 'Upload / FTP transfer'

When uploading a project with the FTP and Sync feature of the Site Manager a set of commands are also available with additional Variables from the remote server. This is used to set the absolute file path or remote server name in configuration files for applications that cannot work with relative paths.

Before starting the upload a PHP probe script is uploaded on the remote server and executed, it returns file path and server name information to the Site Manager. That information is added to the variable for the commands:

Additional Variable command during Upload

[remote_absolute_file_path]: Absolute file PATH to the project on the remote server
[remote_relative_http_path]: Relative http / web path to the project on the remote server
[remote_absolute_http_path]: Absolute http / web path, full web address to the project on the remote server
[remote_php_self]: PHP_SELF value from the remote server
[remote_server_name]: full domain name

Upload commands

sqlquery, 
mkdir
setwritable

Selecting Files to upload

With Radria a lot of the development tools are installed in the project itself. When we upload the Application on the live or production server we do not want those tools to be uploaded.

You can choose for each package which files you want to upload during the FTP Sync process.

You have 2 tags in the Package description: HTML Uploads and PHP Uploads. In general always leave the HTML Uploads to none.

You have 3 options for the content of those tags: none, all or a list of files.

none will not upload any files from this package. (files specified in the <files> tag).

all will upload all the files.

Then if you want only a selection of the files add each full file name with one per line. Only those files will be uploaded.

Changing files of an existing package

When you remove a package it will remove all of the files that came with it originally, even if you have modified them. If you have modified a page or an element of a package and then remove the package, your changes will be lost.

The best practice is not to directly modify an element of a package. For Classes, don't modify the original class of the package but extend it. For other elements, make copies of them, with a different name. If you follow these guidelines you'll be able to upgrade packages to newer versions without breaking your application.