Download from GitHub

Flight Manual

Table of Contents

Section 1 - Introduction [back to top]

1.1 - What is StarbugPHP? [back to top]

StarbugPHP is a free and open-source development framework for PHP. StarbugPHP employs a Model-View design pattern.

Why was it built?

StarbugPHP was concieved out of a lack of satisfaction with other frameworks and the MVC implementation most of them employ.

1.2 - Requirements [back to top]

PHP

StarbugPHP will work on PHP 5.0 and up

MySQL

StarbugPHP will work on MySQL 5.0 and up. However, to manage SQL Triggers with Starbug's migrations, you will need MySQL 5.1.6 or higher.

PHP extensions

The following PHP extensions must be enabled.

Software Packages
Optional Software Packages

1.3 - Features [back to top]

Starbug is a full featured web application framework that is modeled tightly around the HTTP Protocal.

Here are some of it's features

1.4 Basic Terms [back to top]

Here are some basic terms that you will need to know:

1.5 - File Structure [back to top]

Now let's take a high level look at Starbug's file structure.

1.6 - Download [back to top]

First download the Starbug PHP installer.

Simply extract the archive and run make install with root privilages

$ sudo make install

For a development copy, check out our GitHub page.

Section 2 - Getting Started [back to top]

2.1 - Hello World [back to top]

Now You're ready to create you first Starbug PHP application! Use the starbug command to create a new application:

$ starbug myapp

$ cd myapp

With a fresh copy of Starbug ready to go, the first thing you'll want to do is generate a Host file to enter your database info into.

$ sb generate host

This will generate the file etc/Host.php.

The Host file is a container for host specific configuration values such as database credentials, the website URL, and file paths.

Here is an example of the most basic Host file:

By default, the Host file is generated only with required values. Once you've filled these in, you can run setup.

$ sb setup

After setup is done, you should be able to see this in your browser:

Now all we have to do is add the customary touch by editing app/views/home.php to make it say Hello World!

2.2 - Configuration [back to top]

All configuration files are in the folder etc.

The main configuration file is etc/Etc.php. This file and etc/Host.php both contain application constants. The difference is that etc/Host.php is for host/machine specific configuration, while etc/Etc.php is not environment specific.

Values in either of these two files can be accessed throughout the application via the Etc class. For example, your WEBSITE_URL can be retrieved with:

Etc::WEBSITE_URL

Groups & Statuses

Groups and statuses are a fundamental component of the role-based access control (RBAC) system. Every user can be part of zero or more groups and every record can have zero or more statuses. You can add or modify the groups or statuses in the file etc/constraints.php.

Each group and each status is assigned a number. Below is the default set:

Bitwise Operations

You will notice that the numbers are powers of 2. In binary, each of these numbers contains only a single 1 and they are all in different positions. Take the numbers 1, 2, 4 and 8. Here they are in binary:

This means that these numbers can be added together. Take 4 plus 8. That equals 12 right? let's see that in binary.

So in binary we can plainly see that 12 requires 2 powers of 2 to create, and that they are 4 and 8.

Autoload

You can add utilities/modules to the file etc/autoload.php to have them always load when Starbug is initialized.

For more information on utilities, see Section 5: Utilities.

CSS

Starbug has a build system for CSS. This will optimize your CSS and combine multiple files. When Etc::ENVIRONMENT is set to production then the built resources will be used. Otherwise, the unbuilt resources will be used.

The CSS configuration file is at etc/css.json.

Dojo

Starbug PHP integrates the Dojo Toolkit, a modular JavaScript toolkit. Dojo has it's own build system. This can be configured at app/public/js/dojo.profile.js.

For details on configuring the Dojo build system, see dojotoolkit.org/reference-guide/build.

2.3 - Global Functions [back to top]

Starbug defines various functions in the global scope. Since defining global functions has the potential to interfere with other applications that you might use, the vast majority of them are in core/global_functions.php.

The API Documentation contains a complete reference, but here are some that you should know about.

uri

Converts a relative path to an absolute URL.

Parameters

path: the relative path

flags: either 's', 'u' or 'f'.

  • s: return a secure (https) URL.
  • u: return an unsecure (http) URL.
  • f: return a friendly URL (no protocal).
Return

string the absolute URL. If no flag is specified, the protocal of the active page will be used (http or https).

Example

<a href="<php echo uri("users/update/10"); ?>">update</a>

star

Converts a star string to an associative array.

Parameters

star: a star formatted string.

Return

array an associative array containing the key/value pairs from the string.

Example

$options = star("first_name:Ali  last_name:Gangji");

logged_in

Check if a user is logged in.

Parameters

group: optional group name.

Return

boolean true if the current user is logged in, false otherwise. If group is specified then true will only be returned if the user is logged in to the specified group.

Example

if (logged_in("admin")) echo "You are an admin";

userinfo

Obtain information about the currently logged in user.

Parameters

field: the field to obtain.

Return

string the requested field.

Example

echo "Welcome, ".userinfo("first_name");

query

Query the database to obtain records.

Parameters

string from: the models/tables to query. Separate multiple models with commas. Joins are performed automatically based on table definitions in your migrations. A via clause can be appended to additional models to specify how they should be joined.

star args: query arguments. All parameters are optional.

  • select: SQL select clause.
  • join: Type of join if multiple models are specified.
  • where: SQL where clause.
  • groupby: SQL group by clause.
  • having: SQL having clause.
  • limit: SQL limit clause.
  • orderby: SQL order by clause.

boolean mine: Automatically join tables if true. This is the default.

Return

array The records. If a limit of 1 is specified, the single record will be returned as opposed to an array of records.

Example

// The via clause is not neccessary, but is shown here to demonstrate it.
$records = query("orders,users via orders owner", "select:8 &nbpsp;where:orders.id='10'  limit:1");

store

Store or update a record in the database. The data will be validated before storing. If it fails validation, it won't be stored and the errors can be accessed with the errors function or directly in the $sb->errors array.

Parameters

string table: the name of the table to store the record in.

star/array fields: the fields to store in star or array form.

star/array from: optional set of fields to match on to perform an update instead of an insert. If not specified, an insert will be performed unless an id is passed in the fields.

Example

//INSERT RECORD
store("users", "first_name:Ali  last_name:Gangji");
//UPDATE RECORD
store("users", "email:ali@neonrain.com", "first_name:Ali  last_name:Gangji");
//UPDATE USING ID
store("users", "email:ali@neonrain.com  id:5");

queue

Queue a record for storage in the database. Behaves exactly like store except the record will only be validated. Once a call to store or store_queue is made, all queued records will be stored if there are no validation errors.

See the store function for parameters.

store_queue

Stores all items in the queue if there are no errors.

Example

store_queue();

store_once

Store a record only if an identical record does not already exist.

See the store function for parameters.

remove

Remove a record from the database.

Parameters

string table: the name of the table to remove the record(s) from.

string where: SQL where clause.

Example

remove("users", "id='5'");

raw_query

Execute a raw SQL query.

Parameters

string query SQL statement to execute.

Return

If the query is a select statement: returns a PDOStatement object, or FALSE on failure.

Otherwise: return the number of records affected.

Example

$statement = raw_query("SELECT * FROM ".P("users")." WHERE id='5'");

errors

Get validation errors from calling store or queue.

Parameters

string model: optional model to check for errors on.

Return

array returns an array of errors, indexed by model and field. If a model is specfied then only errors on that model will be returned indexed by field. If there are no errors, the array will be empty.

Example

if (!errors()) echo "No Errors!";

redirect

Redirect the user to another URL.

Parameters

string URL: the URL to redirect to.

int delay: optional number of seconds to delay.

Example

//REDIRECT TO HOME PAGE
redirect(uri());

connect

Connect a JavaScript event using Dojo.behavior.

Parameters

star options: options. starts with an un-named parameter, a css selector to connect to.

  • action: the function to connect to.
  • event: the event to connect to, defaults to 'onclick'.
  • url: if specified, an XHR call to this url will be triggered and 'action' will be used as the callback.

star parameters: parameters to be passed to 'action'.

Example

connect("#save_button  action:save_data");

efault

Set a variable if it is empty.

Parameters

mixed &variable: the variable in question.

mixed value: the value to set it to if it is empty.

Example

efault($_GET['page'], 1);

dfault

Set a variable if it is not set.

Parameters

mixed &variable: the variable in question.

mixed value: the value to set it to.

Example

dfault($_GET['page'], 1);

empty_nan

Set a variable if it is empty or not a number.

Parameters

mixed &variable: the variable in question.

mixed value: the value to set it to.

Example

empty_nan($_GET['page'], 1);

2.4 - Views, URIs and Routing [back to top]

Starbug is modeled around the HTTP Protocol. An HTTP request consists of a verb and a noun. The verbs in HTTP are GET and POST. There are also PUT and DELETE but these are not used. The URL is the noun of an HTTP request.

Views

Views are simple PHP files that get loaded when a URL is requested. If the URL is the noun in our HTTP conversation, then the View is what that noun refers to. If you think about, this is just like a real conversation. The word table is a noun, but a table itself is not a noun.

URIs

URIs wrap the URL. You can think of them as URLs with metadata, or you can think of them as routes.

URIs have a template and a path.

path

The path only needs to be a prefix of possible URIs. So a URI with a path of photos can provide access to any subpath of photos/ without it's own more specific entry.

template

Templates are kept in app/views/templates/

The template determines what to do with the requested path.

Using the standard View template with a path such as photos/update/2, Starbug will determine the view that you are trying load and sets $request->file accordingly.

Since Templates and Views are loaded from the global $request object, you can include the $request->file like this:

include($this->file);

Going back to the example path we just used (photos/update/2), the first of these that exists will be set as the $request->file:

  • app/views/photos.php
  • app/views/photos/update.php
  • app/views/photos/update/2.php
  • app/views/photos/update/2/default.php
  • app/views/photos/update/default.php
  • app/views/photos/default.php
Migrations

URIs are added via Migrations. Here is an example of what this looks like:

//THIS SECOND PARAMETER IS NOT NECCESSARY SINCE THESE ARE THE DEFAULT VALUES
$this->uri("photos", "template:templates/View  title:Photos");

In the next section we will take a closer look at migrations.

2.5 - Migrations [back to top]

Migrations are where you define URIs, Permits, and the schema of your database.

Generating Migrations

To generate a migration, you can run the following command from your project folder:

$ sb generate migration MyFirstMigration

This will generate the file app/migrations/MyFirstMigration.php.

URIs

See Section 2.5 - Views, URIs and Routing.

Permits

See Section 4.6 - Permits.

Tables

See Section 4.1 - Migrations.

Listing Migrations

To list migrations you can run the following command:

$ sb migrations -l

Running Migrations

To migrate to the latest migration, run the following:

$ sb migrate

For more information on these commands see Section 7: Script.

2.6 - Models, Permits and Access Control [back to top]

Models

Models are PHP classes that represent types of data in your application and they correspond to a table in the database.

For example, there is a Users model and users table.

Permits

Permits are the rules that govern access control. The permits are constrained by the built in roles as well as external constraints called groups and statuses.

Constraints

You can add groups and statuses in the constraints file - etc/constraints.php

Groups

Groups are pretty self explanatory. Each group is assigned a bit, so they can be added together. Say that root = 1, user = 2, mod = 4, and admin = 8. We can add 2 + 4 + 8 = 14. Each user has a property called memberships which if set to 14 would allow this user to do anything a user, mod or admin can do.

All Models have a property called collective which is the group that owns the record.

Statuses

Statuses are assigned to bit positions just like groups. See etc/contraints.php for default statuses.

Permits

You can add permits from your Migrations. Permits are applied to a model/table as well as the following:

Type

Possible options are table, global and object. Table applies to the table like directory permissions such as creating an entry. Global applies to any records, while object applies to a specified record.

Action

The action is the verb. The methods of your models become HTTP verbs when you expose them with permits.

Role

Role can be everyone, user, group, owner, or collective.

everyone means that the rul will apply to, you guessed it, everyone!

user means that the rule applies to a specific user which will have to select.

group means that the rule applies to a specific group which will have to select.

owner means that the rule applies to the owner of the data. All models have a property called owner that defaults to the user that created it.

collective means that the rule applies to members of the group that owns the data. All models have a property called collective that defaults to the root group.

POST actions

The POST can be used to call custom verbs or actions. The post variable $_POST['action'] is used to call upon model functions in the format: $_POST['action'][$model] = $action. For example, if a form posted $_POST['action']['users'] with a value of 'create', Starbug would attempt to invoke a method called 'create' belonging to the model 'Users'.

2.7 - Authentication [back to top]

2.8 - Administration [back to top]

The Starbug administration interface can be accessed by visiting /sb-admin and logging in using the credentials established during installation.

When you login, you will be taken to the Bridge. This is where you handle all routing and access control with URIs and Permits.

You can also utilize the scripts in the folder scripts/. Run them from the root of your application like this:

$ ./script/db migrate 1:2

Section 3 - The Core [back to top]

3.1 - Constants and Global Functions [back to top]

Etc

Configuration constants are held in Etc at etc/Etc.php

Here is an example of one of these constants in use.

<title><?php echo Etc::WEBSITE_NAME; ?></title>

Look in etc/Etc.php to see all of the constants or to add your own.

Global Functions

There are a few functions defined in the global scope.

uri

The uri function converts a path to an absolute url.

Here is an example of it in use:

<a href="<?php echo uri("login"); ?>">Login</a>

P

The P function prefixes a string with the database and session prefix.

Here is an example of it in use:

<?php if ($_SESSION[P("memberships")] & 2) echo "You are a user"; ?>

3.2 - The Request [back to top]

$request is a global instance of the Request class.

3.3 - sb [back to top]

$sb is a global instance of the sb class.

3.4 - Working With Data [back to top]

Section 3 - Coding in Starbug [back to top]

3.1 - Constants and Global Functions [back to top]

Etc

Configuration constants are held in Etc at etc/Etc.php

Here is an example of one of these constants in use.

<title><?php echo Etc::WEBSITE_NAME; ?></title>

Look in etc/Etc.php to see all of the constants or to add your own.

Global Functions

There are a few functions defined in the global scope.

uri

The uri function converts a path to an absolute url.

Here is an example of it in use:

<a href="<?php echo uri("login"); ?>">Login</a>

P

The P function prefixes a string with the database and session prefix.

Here is an example of it in use:

<?php if ($_SESSION[P("memberships")] & 2) echo "You are a user"; ?>

3.2 - sb [back to top]

$sb is a global instance of the sb class.

3.2 - The Request [back to top]

$request is a global instance of the Request class.