SimpleScripts Script Packaging

Let's take a look at the SimpleScripts Script Packaging Method. We'll also examine best practices when creating a script for distribution.

Basics of a SimpleScripts package

SimpleScripts is really flexible, so not a lot is required on your part. With the following criteria met, SimpleScripts will import your package and configure the rest of the installation.
  • Files should be in the root of the archive. The archive will be extracted within the end user's chosen directory, so an index.php or index.html should be there.
  • SimpleScripts needs a mysql database dump, called data.sql, to also be in the root of the archive. This should have the entire database structure. If you want to have some optional sample data, you can create a sample_data.sql as well.
  • Any specified paths, database connection details (including prefix if supported), admin usernames and passwords, and anything else specified in the Tags section of this document should be replaced with the appropriate tags.
  • The archive should be compressed using tar, tar.gz, or zip.

Organization

SimpleScripts maintains a simple packaging structure. All files are located at the base of the archive. To illustrate this, please see this figure.

Installations

SimpleScripts takes a copy of a given script and divides it into three main parts.
The Script Files, or the core of the application.
The Database, as a SQL dump. This is always "data.sql" for the initial table structure import. A "sample_data.sql" can also be provided with additional SQL data, generally including available module activation, etc. The user can choose whether or not to include the "sample data" during installation.
The Configuration Files, loaded up with standard configuration options and database connection details.
Values in the database and configuration files can be updated using a standard set of keyword tags (see below for a complete list). Files are updated and delivered to the target site as carbon copies, ensuring that one installation will always be the same as the next. This method, along with the SimpleScripts Version Compatibility Checking, alleviates countless hours of troubleshooting in user forums, etc.
Here is a sample database configuration file, such as dbconfig.php, used to illustrate tag placement.
<?php
define('DATABASE_HOST', 'ss_dbhost');
define('DATABASE_USER', 'ss_dbuser');
define('DATABASE_PASS', 'ss_dbpass');
define('DATABASE_NAME', 'ss_dbname');
define('TABLE_PREFIX', 'ss_dbprefix');
?>

Upgrades

Upgrades take place in two stages.
Stage 1: File system updates. This is in the form of a 'Patch' archive, built from a list of 'changed files' from the previous release. Theme changes and plugin system architecture changes almost always break a user's website, so these systems should be abstracted and/or versioned. Core code should be abstracted from any user-modified files.
Stage 2: Database updates. These changes can take place two ways.
A SQL diff file. Changes made here will modify the structure of a database, but data integrity may be in question.
A database_update.php page. This page should be designed to verify and update database structure and data integrity to the latest version available. Access restrictions and javascript updating are not recommended, or if included, should allow bypass through a GET variable, such as admin/db_update.php?nojs=1&force=1. SimpleScripts does not rewrite your updates!

Reference: Keyword Tags for Configuration Replacement

The following is a comprehensive list of keywords used by SimpleScripts in the Database SQL Dump and the Script's Configuration Files.
Path Based Tags
ss_full_urlThe full URL component, minus the http:// (ex. www.yourdomain.com/blog)
ss_full_pathThe full file system path to the installation, with no ending slash. (ex. /home/username/public_html/blog)
ss_site_urlThe full domain target, minus the http:// (ex. www.yourdomain.com)
ss_site_pathThe url target path, minus the domain name and trimmed for slashes. (ex. blog or members/blog)
ss_site_path_slashA variation of ss_site_path, which includes a slash (/) at the end, but will be blank if there is no ss_site_path.
ss_slash_site_pathA variation of ss_site_path, which includes a slash (/) at the beginning, but will be blank if there is no ss_site_path.
Database Tags
ss_dbhostThe host name of the mysql database server.
ss_dbuserThe database username.
ss_dbpassThe database password assigned to the given username.
ss_dbnameThe database name.
ss_dbprefixThe database table prefix.
ss_dbtypeReserved. Not yet in use.
Admin Tags
ss_admin_userThe Admin Username as specified by the user. Defaults to "admin".
ss_admin_passThe encrypted Admin Password as specified by the user, encoded for the specific script. See below for available types.
ss_admin_saltThe salt used to generate the admin password, if required.
ss_admin_pass_plainThe Plain Admin Password as specified by the user.
Additional Tags
ss_random_[i]Generates a random string of length [i]. Useful for creating authentication salts, cookie encoding strings, etc.
ss_sendmail_pathThe full path to sendmail.
ss_footerIf you're feeling generous, we'd love an extra tag for us to add a keyword of our own by your "Powered by" text. This will be something like "Install YourScript" or similar, and really helps us with our Google rankings and getting new users.
ss_host_footerSame as above ss_footer, but helps the host if they've chosen to take advantage of the option.

Reference: Available Password Encryption Types

SimpleScripts can generate an administrator password based on a number of different encryption/hashing types. If you don't see yours listed, please contact us and we'll work with you to put it in.
Plain, MD5, SHA1, SHA256, MySQL, MySQL OLD, HTPasswd, OSCommerce, Magento, Joomla, Joomla 1.5, Gallery, phpBB3, ZenPhoto, Wordpress 2.5+, Mantis, vTiger, DadaMail, Concrete5