Starting a new project from scratch

This tutorial is a step by step checklist to progressively build a basic working application based on Artaengine as the framework.

Following this tutorial builds a strong understanding and idea about how an Artaengine based application is put together. However you can use the Artaengine Project Administrator to configs and create a project from scratch.

Downloading

The first thing to do is to download the required libraries. While the the Artaengine library itself is enough, certain functionalities require other libraries. Artaengine is able to use or work with several libraries and this libraries are not included in the Artaengine download package.

Beside the libraries explained in this tutorial you can use any other front-end or back-end library in your project, you can even tweak the Artaengine libraries to make support for something which is not supported. For example by adding just a few lines you can make Artaengine support another template engine.

Artaengine library

The Artaengine PHP libs, JavaScript libs, documentations, examples and the Artaengine Project administrator.

Artaengine

PHPTAL template engine (recommended optional download)

If you are going to use a PHP template engine, this engine is highly recommend. You may use another PHP template engine which is pluggable to Artaengine, it is also possible to use pure PHP sources as templates or not to use any templates at all. However some examples and the project Artaengine administrator are built on PHPTAL and require PHPTAL.

PHPTAL

Smarty template engine (optional download)

To use Smarty template engine download it.

Smarty

jQuery (recommended optional download)

Optional but highly recommended. The small Artaengine JavaScript lib can talk to the Artaengine PHP libs which makes life a lot easier, and writing significantly less front-end source codes. This lib depends on jQuery. Here are some features which require jQuery:

Using "arta.js" to take care of AJAX requests, adding and updating data, form validation, managing search forms, creating data packs and etc.

When using form generators (Form and FormSearch classes) to render forms, jQuery and jQuery widgets are added to the forms (if jQuery exists).

jQuery

The Artaengine JavaScript lib (based on jQuery)

Using the jQuery based "arta.js" would help a lot to save time and write less codes. "arta.js" includes functions that make connecting an Artaengine application front-end and back-end extremely fast, efficient and easy. This library is included in the Artaengine download bundle.

Artaengine

jQuery UI (optional download)

Lets you add date widget, auto complete, dialog, combo-box and other jQueryUI widgets.

jQuery UI

jQuery Multi-Select plugin

When available this jQuery plugin is used by Artaengine form generators to create nice multi-select widgets. Both the following libs can be used. The first multi-select jQuery plugin is included in the Artaengine package. This plugin is included in the Artaengine download bundle.

Artaengine

jQuery UI Persian calendar (optional download)

To make jQueryUI date picker work with Persian calendar get this one.

Persian Calendar

YUI Compressor (recommended optional download)

If YUI Compressor is available, Artaengine will automatically compress your JavaScript and StyleSheet files with YUI Compressor on.

To not be annoying, Artaengine will only compress the files when the project is not under development, an application config called "debug" which will be explained later tells Artaengine buildout if an application is under development(debug) or not.

YUI Compressor

Closure compiler (recommended optional download)

You can configure the application to use Closure Compiler to minify JavaScript files instead of YUI Compressor. You can also have both tools so the CSS files would be compressed by YUI Compressor.

Closure Compiler

Creating directories

Now its time to make a logical directory structure for your downloaded libraries and application sources. Below is a recommend structure.

The blue colored directories and the files with a small green arrow come with the Artaengine download package. The other directories and files are created or downloaded manually.

Some directories are shown by an empty folder icon but some with a folder icon that has a small file inside it. The not empty icon means the directory will be filled with files or directories which are explained in this tutorial.

When the Artaengine Project Administrator is used to create a new project the layout it creates would look a lot like the layout shown here.

www

The Artaengine package

Inside the package there is a main directory named "artaengine" that contains this sub directories and files:

  • arta : contains the PHP libraries, The "Arta.php" and "ArtaCli.php" inside this directory are the frame classes.
  • admin : the Artaengine Project Administrator.
  • doxer : a command line tool for creating PHP source documentations.
  • documents : contains the Artaengine API documentation.
  • javascripts : contains the Artaengine JavaScript libraries.
  • .htaccess : rewrites the requests to the "artaengine" directory to the Artaengine Project Administrator (only for Apache).

There are two options extracting the Artaengine libraries.

Option 1: Extracting the downloaded Artaengine file into the www directory. The structure shown in this tutorial uses this option. In this case you have one Artaengine directory which can be referenced in one or more applicationsand can be updated more easily.

Option 2: Extracting the downloaded Artaengine into a project(application).

The "javascript" directory includes the Artaengine JavaScript libs.

The "documents" directory includes the Artaengine API documentations.

"doxer" is a PHP documenter tool which is included in the Artaengine package.

Template engine library

If template engine(s) is(are) being used then create a www/arta/template-engines directory and extract the downloaded template engine libraries inside www/arta/template-engines.

The directory names and locations are not strict, you can put whatever you want. The paths are defined in the application config.

YUI Compressor

Artaengine's buildout can compressing your projects CSS and JavaScript filesif YUI Compressor is placed in the artaengine directory as show in the directories tree. Download the YUI Compressor and extract it inside the Artaengine directory, rename the directory to 'yuicompressor' and 'yuicompressor/build/yuicompressor-x.y.z.jar' to 'yuicompressor/build/yuicompressor.jar'. Leave the other YUI Compressor files and directories as they are. Artaengine expects to find YUI Compressor as: 'Artaengine-dir/yuicompressor/build/yuicompressor.jar'

Closure Compiler

Can be used to minify the JavaScripts the in same way as YUI Compressor can be used. However if both YUI Compressor and Closure Compiler exists by default Artaengine will use YUI Compressor unless you put an explicit config in the application (the configs are explained elsewhere). The compiler.jar must be put in the root of this directory.

Application directory

Create an empty directory inside www. This is where application front-end and back-end files will be placed in.

Temp directory

Each application using Artaengine requires a temp directory. If the temp directory not exists then the Artaengine buildout will create this directory.

Artaengine should have appropriate permissions to write inside the temp directory or to create temp directory inside application directory, otherwise an error would be raised.

Artaengine creates cache, logs and temporary files when building-out the application. This files increase performance. This files are created inside the temp directory. If needed this directory can be available as the temp directory for other libraries.

Artaengine's buildout will create the temp directories which are required by the template engines inside the application temp directory.

Browser directory

This directory contains the front-end files. For example it can look something like this:

  • www/app-name/browser/templates
  • www/app-name/browser/images
  • www/app-name/browser/css
  • www/app-name/browser/js

Probably there would be more sub-directories inside each one for example:

  • www/app-name/browser/js/jquery/ui
  • www/app-name/browser/js/jquery/select-list
  • www/app-name/browser/js/jquery/arta
  • www/app-name/browser/js/i18n
  • www/app-name/browser/js/ck-editor
  • www/app-name/browser/js/app
  • www/app-name/browser/templates/users
  • www/app-name/browser/templates/portal
  • ...

Extract the JavaScript libraries which you downloaded into the directory you created for your JavaScript files.

Feel free to set the directories as you want. Later on a feature called (front-end)browser dictionary will be explained which lets you set keys to each front-end file and address the files using the keys instead of the address.

In you want to use the Artaengine JavaScript libs then copy them into the project's JavaScript directory e.g:

www/arta/javascript/jquery/arta.js to www/app-name/browser/js/jquery/arta/arta.js

For a multi lingual project create a directory for JavaScript translations (i18n). For each language create a file and put the translation dictionary inside it. Based on the language used by a user include one of this dictionaries to the page. Tha arta.js file uses this system, the messages and texts for arta.js come in English within Artaengine download bundle named as "en.js".

Copy www/arta/javascript/i18n/en.js to www/app-name/browser/js/i18n/en.js For a multi-lingual application copy this file per language and translate the keys to appropriate values.

Locales

Artaengine can startup i18n gettext. If you want to use gettext for your PHP codes and templates you need a directory for the locales: www/app-name/_locales

Translation files should be places inside this www/app-name/_locales directory. You should make directories for each locale you have in the application for example: www/app-name/_locales/en_US/LC_MESSAGES, www/app-name/_locales/it_IT/LC_MESSAGES, www/app-name/_locales/hu_HU/LC_MESSAGES, www/app-name/_locales/fa_IR/LC_MESSAGES, ... The po and mo files must be placed inside the .../xx_XX/LC_MESSAGES directories.

Factories

The application needs a directory to keep the factory files.

What are "factories"? Artaengine dispatches URLs to PHP class methods or functions. Think of URL paths or a groups of URL paths to your website as events, each of this events or a group of them can be mapped to a "class.method" or a "function". This "class.method"s or "function"s catch and handle the events. Let's call this event handlers "factories". A URL/Factory map may include other settings such as permissions.

The Artaengine Project Administrator lets you define the URL form and set a class/method name to it plus setting all the possible configs, it will even create the handler (PHP file, class and method). All you would have to do is to write your codes for handling the event.

For now creating a directory is enough. Later on read the URL mapping/dispatch tutorial to learn everything about this topic.

The directory name is optional and of course it should be created inside the application directory.

Models

What are "models"? they are fun (is developing softwares fun at all?). Models are just plane PHP classes which define data entities. A model consists of a data structure (data attributes and their definitions), the actions that can be done on the data and the events that can happen on the data. Each model inherits the fundamental actions and events from the Artaengine Model class, you may add other custom and conventional actions. The Artaengine model mechanism will interact with the database, from creating the database tables, relations, etc. to manipulating and querying the data. All you have to do is define your model classes and work with them.

Using the model feature is optional. But to use models you also need to use a database engine such as PostgreSQL or MySQL. Models require a databases for storing and querying data.

For now creating a directory is enough. Later read Models to learn everything about models.

The directory name is optional and of course it should be inside the application directory. This directory can have sub-directories and the model files can be placed and organized anywhere in the main or sub directories. The only restrictions are that a model class must have the same name as the PHP file it is in, and the model names must be unique to the application.

Creating files

.htaccess

All requests need to go to only one PHP file, lets say that file is www/app-name/start.php this has to be set in the web server. If the web server is Apache then we can create an .htaccess and set the rules.

Note that you would want to exclude the resource(front-end) requests. Something like this will do it:

Options +FollowSymlinks
RewriteEngine on

RewriteRule robots.txt robots.txt [L]

RewriteRule ^images/(.+)$ browser/resources/images/$1 [L]
RewriteRule ^css/(.+)$ browser/resources/css/$1 [L]
RewriteRule ^js/(.+)$ browser/resources/js/$1 [L]

RewriteCond %{REQUEST_FILENAME} !^(.*)\.(ico|jpg|png|js|css|swf|xml|txt)$
RewriteRule ^(.*)$ start.php?q=$1 [L,QSA]

Artaengine can manage the resource files but this means using PHP to access each file and is not performance wise. It is recommended to exclude the resource requests within the web server settings.

See Web server settings to see more rewrite examples.

Configure

An ini file or a PHP array must exists and contain the application configurations. With this configuration we direct Artaengine how to build and load the application.

In this tutorial the configs are show as ini file settings. The settings can be put inside a PHP array instead, the array must have exactly the same structure.
{section1: {config1: val1, config2: val2, }, }

Create www/app-name/configure.ini and write the configure parameters inside it. The location and name of the ini file is optional. If an array is preferred over ini file the array can be put directly inside the start.php. This will be discussed later in this tutorial. For now its enough to know that the application needs some configurations that can be placed inside an ini file or a PHP array. The next section will expose all the possible configs.

Some configs are file and directory paths. You may put strings "APP_DIR", "ARTA_DIR" and "TEMP_DIR" inside a path. The paths will be resolve correctly.

Artaengine configuration

[arta]                      ; REQUIRED
temp_path = APP_DIR/_temp   ; REQUIRED
debug = on                  ; OPTIONAL
build = on                  ; OPTIONAL
slash = on                  ; OPTIONAL
base_url = http://app-url   ; OPTIONAL
;compress = off             ; OPTIONAL
;principal = Skinner        ; OPTIONAL
;timezone = UTC             ; OPTIONAL
;date_format = Y/m/d        ; OPTIONAL
;log = log-object-name      ; OPTIONAL
;buffer = on                ; OPTIONAL
;request_filter = filter    ; OPTIONAL
  • Set to the app temp directory path. see.
  • Can be on/off. Set to "on" when developing. Many Artaengine classes check this setting to control their behavior. For example an error or exception will be pronounced in debug mode. This setting is respected by the "arta.js" too. The DEBUG constant can be checked inside the app to get the debug state.
  • Can be on/off. Enable or disable build-out from URL. When build=on http://app-name/build will run the Artaengine application build-out proccess.
    If the build path is in conflict with the application defined URL's then add slashes http://app-name/build///////////.
    Note: "debug = off" overrides this setting to "off"
  • Can be on/off (default=off). Sets the behavior of URL-mapping engine. If "on" URL mapper will consider URLs with and without trailing slashes to be the same. See URL-mapping tutorial
  • Can be on/off. "off" will override normal behavior. Normally when debug = off front-end CSS and JavaScript files will be compressed if possible.
  • Set to application BASE_URL. This value is only required if you want to use Artaengine Project Manager with your application.
  • The name of a principal class which checks URL, factory and class permissions. You can put permissions on URLs, factories and classes, when accessed a method from the principal class will be called to check user's permissions against the required permissions. The default principal is the Artaengine Skinner class. You can create your own principal class and set it to this config.
  • Set the default timezone. Default="UTC".
  • Set the default date-format. Default="Y/m/d".
  • Log object name defined in a "log" config section. If set data about each request will be put into the log.
  • Use PHP output buffer. ob_start() will be called on startup and, class Response will respect the buffer.
  • Can be set to a function name or static class method name as "Class::method". When getting data from request objects or when binding data to models (using IRequest, IRequestArray and IBinder objects) all data are passed through this filter as a mid-ware, the returned value will be returned or used instead of the original value. Note that the filter function or class must be visible.

Database configuration

[database:dbo]            ; OPTIONAL
engine = postgres         ; REQUIRED
server = localhost        ; OPTIONAL
dbname = dbname           ; REQUIRED
user = myuser             ; REQUIRED
password = mypassword     ; REQUIRED
;advanced = on            ; OPTIONAL
data = DIR_PATH DELIMITER ; OPTIONAL

This section is for defining a database connection. Based on the configs Artaengine will connect to a database and provide you an object to access the database. An application can connect to none, one or more than one databases so zero or more database sections can be defined.

About section name [database:objectName]

"database" is fixed and is shows this is a database connection section.

objectName is the object name which can be used inside the application to access the database connection. When more than one connections are defined each section must have a unique object name.

You can get the object from the database object factory, a connection will only be made and an object will only be created upon the first call:

$dbo = Database::get('dbo');
$dbo->query("SELECT ...");
  • DBMS engine name. mysqli/postgres
  • Server address.
  • Database name.
  • Database user-name.
  • Database password.
  • off = (default) creates an IDbAbstract instance.
    on = creates an IDbAdvanced instance (extends the IDbAbstract with more database methods).
  • To run SQL files at the end of a builout put them inside this directory. This is useful to fill the database tables with initial data. When an SQL file is executed it will be moved to "/executed" to prevent being executed again. If the files contain more than one SQL statement a delimiter must be mentioned to let the builder separate them.

Models configuration

[model:MyModels]      ; OPTIONAL
database = dbo        ; REQUIRED
path = APP_DIR/models ; REQUIRED
dropsql = on          ; OPTIONAL
build = on            ; OPTIONAL
;optimize_debug = on  ; OPTIONAL
;optimize = on        ; OPTIONAL

This section is for defining a Model group. An application can have none, one or more model groups.

About section name [model:ModelGroupName]

model is fixed and is the section name. Meaning a model group is being defined.

ModelGroupName is an optional name and can be whatever you want. Each model group must have a unique group name, a separately directory to hold model files (PHP class files) and a database object to use for storing and querying data.

  • Path to Model directory. Model files can be placed inside this directory or any level of subdirectories inside it.
  • Name of a database object defined by a database section.
  • Can be set to on/off (default=off). If on, after build-out an SQL file will be created and placed in temp-directory/arta/ which contains DROP statements for all relations created by Artaengine.
  • Can be set to on/off (default=on). If off then ignore synchronizing models with database on build-out.
  • Can be set to on/off (default=on). This config is active only in DEBUG mode. To cache or not cache model files. To gain performance model files are automatically analyzed, optimized and cached during development(DEBUG mode). The cached models are used instead of the original ones when not in DEBUG mode.
  • Can be set to on/off (default=on). This config is ignored in DEBUG mode. When not in development(DEBUG mode if off) then on means use the optimized and cached model classes over original ones. off means use the original model classes.

Factories configurations

;[template:tpl]           ; before Artaengine 1.2.1 REQUIRED
[factory:tpl]                                     ; REQUIRED
factory_path = APP_DIR/factories                  ; REQUIRED
factory_config = APP_DIR/factories.xml            ; REQUIRED
engine = phptal                                   ; OPTIONAL
syntax = HTML5                                    ; OPTIONAL
; REQUIRED WHEN engine IS SET
engine_path = ARTA_DIR/../template-engines/phptal ; OPTIONAL/REQUIRED
templates_path = APP_DIR/browser/templates        ; OPTIONAL/REQUIRED
;dictionary = APP_DIR/browser.xml                 ; OPTIONAL

This section is always required even if templates are not used.

This section hold configure parameters for both factories and templates.

Factories are responsible for creating a "Response" to a "Request". Templates may be used in the "Response" process.

It is possible to define one or more factory/template section.

About section name [factory:objectName]

Both factory(Artaengine 1.2.1 or later) or template can be used as section name, while factory is a more appropriate name.

objectName is an optional name and can be whatever you want. When using a template engine, the engine object will have this name otherwise this would be set to null. To reach the template object use the template object factory:

$tpl = Template::get('tpl');
$tpl->assign('key', 'val');
  • Path to factories directory
  • Path to factory configuration XML or PHP file
  • can be set to phptal, smarty or php. PHP is always available as a template platform anyway.
  • If template engine supports output syntax type then this key can be set to XHTML(default), HTML5 or XML.
  • Required when using template engines (except for PHP). Path to the template engine library.
  • Required when using template engines. Path to the template directory.

Application

[application]                     ; OPTIONAL
title = application name
email = info@my-app.com
cookie_expire = 525600
dictionary = APP_DIR/browser.xml
fav = images/fav.ico
;globalKey = globalValue

In this section you can define global key/values. The values can be accessed in the application via Arta::$globals for example:

$globalKey = Arta::$globals['globalKey'];
Arta::$globals['globalKey'] = newValue;

Using Arta::$globals is faster than using $GLOBALS. This section and any key under it are optional. However there are few keys that are meaningful:

  • Path to an XML or PHP file called browser dictionary. A dictionary that can be used to organize front-end files.
  • URL path to website icon. This value will be available inside the template context.
  • If defined this keys may be used by some libraries. For example the Session, Email and Response classes.

Session configuration

[session]                  ;           OPTIONAL
;startup = off             ;           OPTIONAL
;name = name               ;           OPTIONAL
;expire = 60               ; (minutes) OPTIONAL
;regenerate = 2            ; (minutes) OPTIONAL
;secret = rabbit           ;           OPTIONAL
;database = dbo            ;           OPTIONAL
;memcache = on             ;           OPTIONAL
;path = /memdrive          ;           OPTIONAL
;cookie_expire = 60        ; (minutes) OPTIONAL
;cookie_path = \           ;           OPTIONAL
;cookie_domain = myweb.com ;           OPTIONAL
;cookie_secure = on        ;           OPTIONAL

Session configs. Sessions are only started on demand, on the first session demand. Sessions are accessible via a Request object. e.g. $request->Session->set('k', 'v');

  • Set to "on" to always have sessions started at startup. In contrast to on demand.
  • Set this key to change session name to something other than default.
  • To manually check and expire session(if timeout) on application startup.
  • Intervals (in minutes) to regenerate session id.
  • If set to a string, session id will be regenerated on occasions and ArtaException::UNSAFE_SESSION will be thrown if user agent changes.
  • Name of a database object which was previously defined by a database section. Set this key if you wish session data to be stored on a database. Just set this key and build-out will take care of creating the database tables.
  • Set this key to "on" to put sessions on memcache.
  • Session file path.
  • Session cookie config. Session cookie expires timeout.
  • Session cookie config. Session cookie path.
  • Session cookie config. Session cookie domain.
  • Session cookie config. Create session cookie only on HTTPS.

i18n configuration

[i18n]               ; OPTIONAL
;startup = on        ; OPTIONAL
;key = lang          ; OPTIONAL
domain = app-name    ; OPTIONAL
locales = ./_locales ; OPTIONAL
codeset = utf8       ; OPTIONAL
default = en         ; OPTIONAL
;detect = on         ; OPTIONAL
;the available lang/locales in the application
en = en_US           ;
fa = fa_IR           ;
hu = hu_HU           ;
it = it_IT           ;
;date format may be added
en = en_US m/d/Y     ;
fa = fa_IR Y/m/d     ;
hu = hu_HU Y-m-d     ;
it = it_IT d/m/Y     ;

If you want to use i18n gettext add this section.
This section can be defined only if session is started.

  • Set to on to always have gettext started at startup. In contrast to on demand. To use on demand gettext you have to use T() instead of _().
  • Key name to set or expect lang key in GET/POST/COOKIE/SESSION.
  • A name for the translation domain, if this key is not set Arta:$globals['title'] will be used.
  • Path to locales directory, in this example the locales directory is www/app-name/_locales or ./_locales Default value is ./_locales
  • Code-set of the locales. Default value is utf8
  • When no LANG/LOCALE is set by user, this will be the default LANG/LOCALE. The default value for this key is en
  • When no LANG/LOCALE is set by user, instead of config LANG/LOCALE to default detect client's preferred LOCALE from HTTP_ACCEPT_LANGUAGE.
  • Any other key/value under i18n section will be a lang/locale available for the application.
    it = it_IT
    pa = fa_IR
    en = en_EN
    us = en_US
    langX = localeX langX is an optional key and localeX is a valid localecode_COUNTRYCODE. http://app-name.com/any-paths?lang=langX will set application to use translations for localeX. LOCALE and LANG constants will give the selected locale and lang.
    $localeDictionary = Arta::$globals['locales'];
    gives {langX: localeX, } defined in i18n.

Autoloads

[autoload] ; OPTIONAL
;custom = APP_DIR/autoload.php
;1 = APP_DIR/other-path1
;2 = APP_DIR/other-path2

This optional section is for defining paths which you want to be added to autoload. This paths will be extended to the Artaengine autoload path stack. To get or set the paths stack inside your codes touch:

$paths = Arta::$autoload;

The default autoload includes Artaengine library path, data model path(s) and paths added here.

The default autoload first checks if user has permission to the requested class(if class permissions are defined in the application). Then searches in the autoload queue paths for a PHP file named the same as the class-name. To add other rules define your own autoload:

To define a custom autoload function set your custom autoload PHP file path to key: custom. Custom autoload file must contain this function:

function customAutoload($className) {
    /* YOUR RULES */
}

Constants

[constants] ; OPTIONAL
;ROOT_USER = Super

This optional section is for adding constants to the application.

Globals

[globals] ; OPTIONAL
;varname = value

This optional section is for adding variables to $_GLOBALS. It is recommended to define your global values using Arta::$globals instead of $_GLOBALS see Application.

Includes

[includes] ; OPTIONAL
;1 = APP_DIR/other/other.php

This optional section is for including PHP files to the application.

Log

[log:objectName]          ; OPTIONAL
engine   = text           ; REQUIRED
log_file = /path/file.log ; OPTIONAL
json = false              ; OPTIONAL
user_data = true          ; OPTIONAL
compact = false           ; OPTIONAL only for csv
style = arta              ; OPTIONAL only for text

This section is for defining a logger object. An application can have zero or more log objects so zero or more log sections can be defined.

About section name [log:objectName]

"log" is fixed and is shows this is a cache section.

objectName is the object name which can be used inside the application to access the logger object and write logs. When more than one cache objects are defined each section must have a unique object name.

The object can be accessed inside the application by the Log object factory:

$log = Log::get('objName');

// or more simple ways
Log::model('objName', $model);
Log::request('objName');
Log::handle('objName', $model);
// by level: error, warn, trace, debug, info
Log::error('objName', $commentsStringOrArray);
  • Log weriter engine name. text / csv
  • Path to the file to write the logs into. Default = TEMP_DIR/logs/date(Y-m-d).(txt or csv).
  • To write log array comments as JSON or not. Default = false.
  • Add user id, username and IP if possible to the log. Default = true.
  • If the array comments must be written into only one column for csv logs. Default = false.
  • The text log style. The log item style. may be any of:
    'arta' = log in a highly readable style
    'one' = log each item in only one line
    'two' = log each item in two lines
    'param'= log each item's part inside braces

Cache

[cache:obj]               ; OPTIONAL
engine = APC              ; REQUIRED
;host = host              ; OPTIONAL only for memcache
;port = port              ; OPTIONAL only for memcache
;1 = host1 port1 balance1 ; OPTIONAL only for memcache
;2 = host2 port2 balance2 ; OPTIONAL only for memcache

This section is for defining a cache object. An application can have zero or more cache objects so zero or more cache sections can be defined.

About section name [cache:objectName]

"cache" is fixed and is shows this is a cache section.

objectName is the object name which can be used inside the application to access the cache. When more than one cache objects are defined each section must have a unique object name.

The object can be accessed inside the application by the Cache object factory:

$cache = Cache::get('objName');
  • Cache engine name. APC / XCache / MemCached / MemCache
  • MemCache server address. Default = localhost.
  • MemCache server port. Default = 11211.
  • When more than one memcache server is being used use an index and set it to host, port and load balance separated by space.

factories.xml

The URL paths are mapped to factories inside this file.

This maps can be defined as an XML structure or a PHP array in a PHP file.

The path to this file is set inside the factory section of the application configuration.

Below is a simple example of a URL to factory mapping. And a short description on some of the tags/keys.

<?xml version="1.0" encoding="UTF-8"?>
<configure>

<!-- PATHES -->

  <route
      path="/"
      factory="App.index"
      />

  <route
      path="/test1"
      factory="App.test1"
      />

  <route
      path="/test2/:param"
      factory="App.test2"
      robots="false"
      ajax="true"
      />

<!-- HANDLE -->

  <notfound factory="Handle.notfound"/>

  <exception factory="Handle.exception"/>

  <unauthorized factory="Handle.unauthorized"/>

  <illegal factory="Handle.illegal"/>

  <nofactory factory="Handle.nofactory"/>

  <notajax factory="Handle.notajax"/>

</configure>
  • Each route maps a URL path to a factory, the URL can be a static text or a pattern, when a pattern is set, unknown paths of the URL are passed as parameters to the factory.
    In the above example the first route maps the base URL (http://app-name) to method index of class App which is expected to be found inside www/app-name/factories/App.php
  • Handle tags define handles for a set of special events.
  • Resource tags map a URL to a directory path on the server.
    Use web server to do this instead, see .htaccess.

See the URL mapping/dispatch tutorial to learn everything about URL to factory mapping.

browser.xml

A dictionary can be defined for the app that maps keys to resource files (front-end files like CSS, JS and templates). This dictionary can be defined in an XML file or a PHP array inside a PHP file. The resources can be addressed by their keys inside the app's PHP sources, this will let the resource files and paths be changed without the need to change the app files, also the CSS and JS entries may be marked to be compressed, plus this creates a standard way to add resources inside the app, for example a class that renders a widget for a form can add it's JS and CSS dependencies via their keys, etc.

Nested entries can be defined for mapping keys to resource files. For example you can define an entry named "jquery" and define the "jquery" plugins within that entry. e.g. "jquery/multi-select".

The path to this dictionary XML or PHP file is set inside the app configuration under the "application" section.

Here is an XML example:

<?xml version="1.0" encoding="UTF-8"?>
<configure>
 
  <configs>
    <!-- to explicitly say use Compiler Closure instead of YUI Compressor -->
    <config key="minify" value="closure"/>
  </configs>

  <templates>
    <template
        path="APP_DIR/browser/templates/index.xhtml"
        name="index"
        />
  </templates>

  <javascripts>
    <js
        path="BASE_URL/js/jquery/jquery.min.js"
        name="jquery"
        />

    <jquery>
      <js
          path="BASE_URL/js/jquery/arta.min.js"
          name="arta"
          />
      <myjslibs>
        <!-- key to this entry: "jquery/myjslibs/mylib" -->
        <js
            path="BASE_URL/js/app/users.js"
            compress="APP_DIR/browser/resources/js/app/users.js"
            name="mylib"
            />
      </myjsfiles>
    </jquery>
  </javascripts>

  <styles>
    <style
        path="BASE_URL/styles/styles.css"
        compress="APP_DIR/browser/resources/styles/styles.css"
        name="styles"
        />
  </styles>

</configure>

start.php

This is the entry point of your application. All requests are going to be diverted to this "start.php" file. That is what we defined in the .htaccess file.

All we have to write in this file is to start Artaengine, and pass it the app configs, Artaengine will read the configs, prepare the request and map it to the correct factory to handle it.

Include the "Arta.php" which in our example is located inside "www/artaengine/arta/Arta.php" then call the "start" method of "Arta" class. thats all!

The application configuration is passed to Artaengine here.

error_reporting(E_ALL | E_STRICT);
ini_set('display_errors', '1');

include_once '../artaengine/arta/Arta.php';
Arta::start('configure.ini');

if configs are in an array:

error_reporting(E_ALL | E_STRICT);
ini_set('display_errors', '1');

include_once '../artaengine/arta/Arta.php';
Arta::start(array(
    'arta' => array(
        'temp_path' => 'APP_DIR/_temp',
        'debug' => true,
        'build' => true,
    ),
    'database:dbo' => array(
        'engine'   => 'postgresql',
        'server'   => 'localhost',
        'dbname'   => 'arta_examples',
        'user'     => 'arta',
        'password' => 'arta',
    ),
    'factory:tpl' => array(
        'factory_path'   => 'APP_DIR/factories',
        'factory_config' => 'APP_DIR/factories.xml',
    ),
));

Creating database

Create database(s) as defined in the configs:

PostgreSQL

CREATE DATABASE dbname ENCODING 'UTF8';
CREATE USER myuser WITH PASSWORD 'mypassword';
GRANT ALL PRIVILEGES ON DATABASE dbname TO myuser;

MySQL

CREATE DATABASE dbname CHARACTER SET = utf8 COLLATE = utf8_persian_ci;
CREATE USER 'myuser'@'localhost' IDENTIFIED BY 'mypassword';
GRANT ALL PRIVILEGES ON dbname.* TO 'myuser'@'localhost';

Creating data models

Create models (if models are going to be used). Models can be created, removed and updated all the time. Artaengine will take care of synchronizing them with the database.

Learn everything about models.

Creating factory classes

Create a PHP file inside the factories directory and name it "App.php". Add the below class inside it. In the "factories.xml" there is a line that sets the base-URL to "App.index".

class App extends Response
{
    public function index($request)
    {
        I('HELLO WORLD');
    }
}
The URL-mapping tutorial explains everything about factories and mapping URL pathss to factories.

Build out

Before the app will work it has to be built, also certain changes to the app's configs and files will require re running the build before they take effect. The building process can be ran in several ways:

1. From the browser (works only if debug = on and build = on in the app configs):

http://app-name/build
http://app-name/build/////

Sometimes "http://app-name/build" is overshadowed by a registered URL mapping to overcome this you can add one or more trailing slashes to the URL.

2. By Artaengine Project Administrator. You can build apps via the admin user interface.

3. Manually, for example you can put below codes inside a PHP file and run it.

// running build-out manually:
include_once '../artaengine/arta/Arta.php';
Arta::build('configure.ini');

See this tutorial about buildout

Below changes to the app would require re running build:

Each time the URL to factory map is changed, the browser dictionary is changed.

Some changes to the app configs which are essential, for example adding database sections or model sections or changing model or temp paths.

Adding or removing model classes, updating the model properties which define the data attributes which require to be synchronized with the database.

If temp directory or the files created by Artaengine which are inside it are removed.

The first time an application is being created.

If build shows errors and the application will not run then check if temp folders are writable or config parameters are valid.

Download example

Getting started
TOP