Basics

This tutorial is about Artaengine basics.

Terminology

Signs used in Artaengine documentations:

  • Shows a list of data items, in PHP it means a sequential array.
    ['rabbit', 'cat', 'dog',] =
     array('rabbit', 'cat', 'dog',)
  • Shows a general list declarations such as that can have zero or more items for like:
    array('rabbit', 'cat', 'dog',)
    .
  • Shows a dictionary, in PHP it means an associative array.
    {'a': 'rabbit', 'b': 'cat', 3: 'dog',} =
    array('a' => 'rabbit', 'b' => 'cat', 3 => 'dog',)
  • Shows a general list declarations such zero or more items.
  • Shows a function or method that accepts infinit (one or more) arguments of the same type.
  • Means the function or method accepts infinit (one or more) arguments of the same type.

Style

Indent style

Artaengine PHP libraries are K & R styled.

Definitions

Arrays are defined as:

    $array => array(
        'key'           => val1,
        'medium-key'    => val2,
        'short-key'     => val3,
        'long-long-key' => val4,
    );
Most of the time variables are defined near each other are aligned:
    $var         = val1;
    $varShort    = val2;
    $varMedium   = val3;
    $varLongLong = val4;

Lines

When possible the lines are kept less that 100 characters.

Indents

Four spaces are used for indents.

Comments

Classes, interfaces and public methods which are going to be used by others have a standard PHP/Java style doc comment block. Private and protected methods, classes and public methods such as models and factories which are obvious or are mostly called by the framework itself may only have a small simple comment block.

Where the source code is not obvious there is a short comment above it, there is not preference in using // or /* */ but usually comments about a block of code is commented with /* */ but a single sub line is commented with //.

No commented source codes! Delete the thing if it is not needed, fix it or make it work! It is very confusing specially when another programmer is working with the codes and sees the commented lines, he will be thinking what is this? what should I do with it? there must be a reason he put it here and not removed?

Camel style

Class names are in camel style where each word starts with a capital letter.

Method, function and variable names are in camel style where each word starts with a capital letter except the first character which is always in lower case.

One exception for camel style is the data properties of models. To be cross database compatible all data properties are in lower case and words are separated by underlines.

File names

Classes are usually put in one file which had the same name as the class case sensitive. Other file names are in lower case where words are divided by -.

HTML attribute values, array keys, template variables

Are in lower case where words are divided by -. Template variables and some array keys are are divided by _.

Classes, interfaces and methods

Each class, method, function and object brings over head! Before introducing a new one I always think is it really needed? will the method or function be used a lot? is it becoming too complicated and a new method or function is needed?

Globals and constants

To store global values use Arta::$globals instead of $_GLOBALS.

Arta::$globals['key'] = value;
value = Arta::$globals['key']

To know if application is in debug mode or not:

echo DEBUG? 'debug mode': 'live';

Engine directory:

echo ARTA_DIR; // /var/www/arta/

Application directory:

echo APP_DIR; // /var/www/app-name/

Application temp directory:

echo TEMP_DIR; // /var/www/app-name/temp/

Arta temp directory:

echo ARTA_TEMP_DIR; // /var/www/app-name/temp/arta/

Artaengine version:

echo Arta::VERSION;

Get application configs:

print_r(Arta::$configs);

Get current factory object:

$obj = Arta::$factory;

Debugging

To inspect variables:

I($variable);
inspect($variable);
I($var1, $var2, ...);
inspect($var1, $var2, ...);

I accepts Model, Request, Response and Exception instances and will dump their context data. Also those objects themselves may have a method called inspect() which will do the same.

Assuming below line is executed in a factory method then model data properties, factory context variables, request arrays and exception values will be dumped on screen:

I($model, $this, $request, $exception);

I" and "inspect" show variable dump and end the application, the output can be HTML or text.

The difference between "I" and "inspect" is that "I" does not show object properties where "inspect" shows. Both show model data properties.

To change output format use Arta::$HtmlDebug (default is HTML):

Arta::$HtmlDebug = False; I($variable); // TEXT
Arta::$HtmlDebug = True;  I($variable); // HTML

Data Types

Where data type matters:

Request

Using Request object to get value from $_GET/$_POST/$_SESSION/$_COOKIE.

/* data type dosnt matter */
$val = $request->post('age');
$val = $request->post('age', 'default');
/* check if output is or can be forced to be INT or return default */
$val = $request->post('age', 'default', INT);
/* check if output is or can be forced to be EMAIL or return default */
$val = $request->post('email', Null, EMAIL);

Models

When creating models, the type of model data properties need to be declared explicitly because data types are important for many actions to be done on models for example creating form widgets, synchronizing with database, data validation and so on.

Data types in Artaengine

This constants show data types in Artaengine:

  • String data type. A model property of this data type has a max-length of 256 characters.
  • String data type. A model property of this data type has no max-length limit.
  • String data type. A model property of this data type has no max-length limit. When rendering form, a WYSIWYG widget will be created to input data.
  • Single character data type.
  • A valid e-mail format string.
  • A valid URL format string.
  • A valid IP format.
  • Same as T::STRING but in a form the widget will be of password type.
  • Same as TEXT just when using MySQL DBMS the column type will be a BLOB.
  • Integer data type. For model data min and max allowed values depend on DBMS.
  • Same as T::INT
  • Same as T::INT but creates an auto-increment database column.
  • Long-integer data type. For model data min and max allowed values depend on DBMS.
  • Same as T::LONG but creates an auto-increment column in the database.
  • Small-integer data type. For model data min and max allowed values depend on DBMS.
  • Double number data type. Min and max allowed values depends on DBMS.
  • Float number data type. Min and max allowed values depends on DBMS.
  • Nummeric data type.
  • Boolean data type.
  • Same as T::BOOL
  • Array data type.
  • Same as T::DICT
  • Time-stamp data type.
  • Same as T::TIMESTAMP but when using PostgreSQL time zone will be mentioned.
  • Date data type.
  • Time data type.
  • Same as T::TIME but when using PostgreSQL time zone will be mentioned.
  • Date-time data type.
  • Same as T::DATETIME

Buildout

Build-out is a process where Artaengine:

* Reads configuration files and dictionaries changes and caches them to enhanced data structures.

* Synchronizes database with model classes.

Modifications which require buildout

Modification of this application components require buildout:

  • Changing file or directory paths, database name and switching sessions data storage would require a build-out.
  • Modifying this file requires a build-out.
  • Modifying this file requires a build-out.
  • Modifying data properties requires a build-out.
    Changing labels of a data properties requires build-out before updating po files.
    Changing model __delete__ or __engine__ properties requires build-out
    It is recommended to run build-out when DEBUG status is changed to update model caches
    When database has data some modification can violate the data integration and build-out will fail showing error messages. In this situations database has to be modified manually, for example when a change in a model will create relation between database tables but the PK/FK have data which do not match and it is not possible to create the relation.
  • Before updating po files build-out may be required. Buildout fetches tokens which need to be reachable by "poedit" from PHPTal and Smarty templates. If you have a multi locale application and you changed the template files and you want to run "poedit" first build-out to update the translation tokens.

Products

Build-out creates files inside the application temp directory, without some of this files the application can not run. Below is a description about some of this files which can be useful for the programmer:

  • A file which contains labels from models which must be visible to poedit if application is multi-lingual and using gettext.
  • A file which contains translation tokens fetched from template files which must be visible to poedit if application is multi-lingual and using gettext.
  • SQLs required to drop all tables and views from the database which are related to the models.
  • This file can be very useful when creating adapters and wrappers on models. There is a dictionary of all models showing the object dependencies of each model to other models.
  • Each time build-out updates the database a log file is created inside this directory. The log file is an SQL file containing the SQL commands ran by build-out on database.

Disable build-out

You don't want the BASE_URL/build to be available to public so that each user and visitor can run build-out on your application. So when the application is out of development you would want to disable the /buildout. Edit application configuration and set build = off.

configure.ini

Parameters

Normally build-out tries to be smart and only build things which have been modified. It is possible to restrict build-out domain by this parameters:

  • In this mode first all cache files except Models dictionary are deleted. If you get errors try this parameter.
  • In this mode first all model cache files except Models dictionary are deleted.
  • In this mode first all model caches are deleted.
  • Build-out will totally ignores the models.

Example

Basics
TOP