Migration Guide v2 to v3 WIP

a work in progress of a community created migration guide from v2 to v3

General Changes

Base

V2:

In V2 you always do static call to the framework base:

F3::set('foo','bar');

V3:

In V3 you still can do that, but the new recommended way is to fetch the instance instead:

$f3 = \Base::instance();
$f3->set('foo','bar');

This also applies for most of the plugins like Template, Web or Image plugin.

Routing

Basic routing V2:

F3::route('GET /@slug', function () {
	echo F3::get('ROOT');
	echo F3::get('PARAMS.slug');
});

Basic routing V3:

F3::route('GET /@slug', function ($f3,$params) {
	echo $f3->get('ROOT');
	echo $params['slug'];
});

Chained functions V2:

F3::route('GET /', 'auth; page; view');

These aren't going to work in V3 anymore. F3 aims to be more OOP now, so create a lamba function to chain your function calls again, or use the new route events:

Chained functions V3:

$f3->route('GET /', function($f3){
  $f3->chain('auth; page; view');
});
// or:
$f3->route('GET /', 'Page->render');

class Page {
  function beforeroute($f3){ 
    // do auth
  }
  function render($f3) {
    // build page content
  }
  function afterroute($f3) {
    // render and echo the view
  }
}

Database Engine Changes

MySQL

V2:

F3::set('DB',
    new DB(
        'mysql:host=localhost;port=3306;dbname=mysqldb',
        'admin',
        'p455w0rD'
    )
);

V3:

$db=new DB\SQL(
    'mysql:host=localhost;port=3306;dbname=mysqldb',
    'admin',
    'p455w0rD'
); 

NEEDS PEER REVIEW: typically you would create the $db object once in your app's controller, and then it becomes a protected php var. Then in your app's class method called by your route, you access the $db var through the app class extended from the controller class. See the app folder in the CMS demo example code download https://github.com/bcosca/fatfree/blob/archive/f3-3.0.1.cms.demo.zip

ORM Changes

V2 used a concept named Axons. in V3, Axons have been dropped and renamed the Data Mapper Object.

Data Mapper Object

V2:

$user=new Axon('users');
$user->load('userID="tarzan"');
//parameterized query:
$user->load(array('userID=:user',array(':user'=>'tarzan')));

V3:

$user=new DB\SQL\Mapper($db,'users'); 
    // $db is your db engine connection object, 'users' is your table name
$user->load('userID="tarzan"');
//parameterized query (named placeholders):
$user->load(array('userID=:user',array(':user'=>'tarzan')));
//parameterized query (positional placeholders):
$user->load(array('userID=? AND password=?','tarzan','ch1mp'));

Views/templates changes

PHP templates (views)

V2:

//controller.php
F3::set('name','world');
echo F3::render('template.phtml');
//template.phtml
<p>Hello, <?php echo F3::get('name'); ?>!</p>

V3:

//controller.php
$f3->set('name','world');
$view=new View;
echo $view->render('template.phtml');
//template.phtml
<p>Hello, <?php echo $name; ?>!</p>

Lightweight template engine (Preview)

V3 only:

//controller.php
$f3->set('name','world');
$view=new Preview;
echo $view->render('template.phtml');
//template.phtml
{~ if (isset($name)): ~}
<p>Hello, {{$name}}!</p>
{~ endif; ~}

Fatfree template engine

V2:

//controller.php
F3::set('name','world');
F3::set('data',array('foo'=>'bar'));
echo Template::serve('template.htm');
//template.htm
<p>Hello, {{@name}}! Array notation: {{@data.foo}}</p>

IMPORTANT: In V2, templates do not raise errors on undefined variables (they are silently replaced by an empty string).

ARRAYS: In V2, in order to access an array with a variable key, we use the syntax {{$_data[$_i]}}.

DIRECTIVES: In V2, available template directives are <include>, <exclude>, <loop>, <repeat> and <check> (optionally prefixed with F3:). The shorthand for <exclude>foo</exclude> is {{*foo*}}.

V3:

//controller.php
$f3->set('name','world');
$f3->set('data',array('foo'=>'bar'));
$tpl=Template::instance();
echo $tpl->render('template.htm');
//template.htm (F3 syntax)
<p>Hello, {{@name}}! Array notation: {{@data.foo}}</p>
//template.htm (PHP syntax)
<p>Hello, {{$name}}! Array notation: {{$data['foo']}}</p>

IMPORTANT: In V3, templates raise an error if a variable is undefined. If you wish to silent the error, prefix the variable with an extra @: {{@@name}} or {{@$name}}.

ARRAYS: In V3, in order to access an array with a variable key, we use the syntax {{@data[@i]}} or {{$data[$i]}}.

DIRECTIVES: In V3, available template directives are <include>, <exclude>, <loop>, <repeat>, <check>, <set> and <switch>. The shorthand for <exclude>foo</exclude> is {*foo*} (notice the difference with V2). The syntax for directives is generally the same as in V2, except for <loop> (see doc for full usage).