====== 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. ==== Auto included files ==== 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 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 . 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 [[tools: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. [[:how_to_package_application_and_libraries|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 **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: * [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 $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 [[tools: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 [[tools:Site Manager]]. That information is added to the variable for the commands: * [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 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 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.