General discussion: Ideas/suggestions for next version of F3

[bcosca]

2015 is round the corner. 3.3 has reached its peak. Don't worry, it won't be abandoned. 3.3.1 will be released before year-end. Now we're preparing the specs for the next incarnation of the framework you've come to know and love. In light of this announcement, we would like to engage everyone in a healthy discussion of what 4.0 should be like. Each feature request must have a justification. Code volunteers are also welcome and must be stated in the entry.

To start off, a code review is now an absolute necessity.

* I plan on cleaning up the hive's built-in variables. It's starting to be a mess and some variables add fat where there should be none.

* Event triggers/handlers should be unified. A standard mechanism must be developed. Those before... after... on... prefixes should be eliminated.

* PHP 5.4 will be the new minimum. 5.3 has already reached its end of life. No use beating a dead horse.

If you have ideas/suggestions about how the future F3 should behave, we're all ears. Bear in mind, the basic single-file functionality will still be there and will always conform to our non-fat philosophy. Everything else will be a plugin.

Remember, this should be a healthy discussion. Feature comparison with other frameworks is fine but should never be a basis for a feature request. A rationale should stand by itself.

Help make F3 better. Your active participation is truly welcome.

[xfra35]

Good news!

Concerning the points you've raised:

• Cleaning up the hive: an idea would be to store the framework's core variables in a dedicated namespace, something like F3.autoload or CORE.autoload, instead of AUTOLOAD. It's sometimes confusing to have core variables mixed up with app-specific variables.
  
• Core event system: I agree that it should be unified. Would be great if we could also use it at app level.
  

 

[bcosca]

I have written some preliminary code on the event system and I also discussed this with ikkez on IRC. The way it works right now is to use something like $f3('var') to create a wrapper for hive variable 'var' so you can attach user-definable events like $f3('var')->trigger=function() {}; and invoke them as $f3('var')->trigger(); It works as planned, but how event propagation should be handled is something elusive. How will the framework handle $f3('var.element') or $f3('var->property')?

[xfra35]

Can you clarify what would be the benefits of attaching events to a variable?

Also how would attach events on a specific instance of an object (a mapper for example) and how would you attach multiple handlers to the same event?

It seems that you've pushed the reflection further than the classical pattern:

$f3->on('run',$callback1); //hook on $f3->run from within a plugin

$f3->on('run',$callback2); //another plugin

function run() {

  $this->emit('run',$args);

  //..

}

//hook on specific object instances:

$mapper->on('update',$callback3);

$mapper->on('insert',$callback4);

$template->on('render',$callback5);

[Eric Fernance]

Hi All

I'm a recent newcomer to F3 and using it for a first project now.

One thing I would be interested in seeing... (and willing to support with code if it's something that others think worthwhile) is to extend the functionality of the Auth class to encompass route based permissions. That may not be the correct term...

For example adding users to groups and then specifying groups that have permission to access specific routes.

Also secondly maybe extending the Auth class to login with google account.

Eric.

[bcosca]

@xfra35: Nothing is set in stone yet. I will surely take your insights into consideration. Your valuable contributions to F3 cannot be overemphasized.

[uonick]

Sometimes want to use the function:

$validator = Validator::make(
    array('name' => 'User'),
    array('name' => array('required', 'min:5'))
);

$validator = Validator::make(
    array(
        'name' => 'Dayle',
        'password' => 'lamepassword',
        'email' => 'em...@example.com'
    ),
    array(
        'name' => 'required',
        'password' => 'required|min:8',
        'email' => 'required|email|unique:users'
    )
);

Events:

Event::listen('POST.login', function($event){
    // Handle the event... $mapper->save();

    return false;
});

and triggers on ORM!

пятница, 5 декабря 2014 г., 16:40:31 UTC+6 пользователь bcosca написал:

[xfra35]

@Eric you can login with a google account using the OpenID library.

Concerning the permissions, I'm planning to write a plugin, unless @bcosca intends to add something at the framework level.

[Richard Catto]

I would like to see the addition of a Dependency Injection container class that allows for the instantiation of user defined classes on an as needed basis.

Options for instantiation of injected class:

1. instantiated once when injected. access the same instance whenever / wherever referenced. ie. global scope

2. instantiated each time it is injected. a fresh instance is referenced. i.e local scope

definition of each class to be injected, could be via:

1. anonymous function (fresh object each time)

2.  new classname (same object each time)

Currently, the hive caters for the second type, but when creating the definitions, all the classes are instantiated immediately, not as needed. The anonymous function type is not supported at all.

[Eric Fernance]

@xfra35. thanks for the feedback.

I will check out the docs on the openid library.

Eric.

--
Sent from my Android device with K-9 Mail. Please excuse my brevity.

[bcosca]

@Richard Catto:

1. instantiated once when injected. access the same instance whenever / wherever referenced. ie. global scope

If your class extends Prefab, you automatically have the instance() method, so $f3->set('obj',myClass::instance()); should instantiate the class and give you the same object every time you retrieve via $f3->get('obj');

 

2. instantiated each time it is injected. a fresh instance is referenced. i.e local scope

I don't understand what you mean by "local scope", but $f3->set('obj',new MyClass) should give you a new instance every time.

 

definition of each class to be injected, could be via:

1. anonymous function (fresh object each time)

2.  new classname (same object each time)

Currently, the hive caters for the second type, but when creating the definitions, all the classes are instantiated immediately, not as needed. The anonymous function type is not supported at all.

If you wrap your object instantiation in an anonymous function, then you defer the process:

$f3->set('deferred',function() {

    return myClass::instance();

});

$deferred=$f3->get('deferred');

var_dump($deferred());

What exactly do you need that can't already be done?

[xfra35]

@Richard Catto, after reading your initial post, I had no idea of what you had in mind. I googled "dependency injection container" and stumbled on that, which made things even worse :P

But after @bcosca's answer, the picture got clearer. It looks like "dependency injection container" is some form of lazy loading with shared dependencies.

In that case, I think the following should answer your question:

class MyClass extends Prefab {

  public $name='foo';

  private $db;

  function __construct(\DB\SQL $db,$name=NULL) {

    $this->db=$db;

    if ($name)

      $this->name=$name;

  }

}

$db=new \DB\SQL('mysql:host=127.0.0.1;port=3306;dbname=test;','user','pwd');

$f3->global=function() use($db) {

  return MyClass::instance($db);

};

echo $f3->global()->name; //foo

$f3->local=function($name) use($db) {

  return new MyClass($db,$name);

};

echo $f3->local('baz')->name; //baz

echo $f3->local('bar')->name; //bar

});

In that example:

- the database connection $db is a shared "dependency"

- $f3->global() always returns the same instance/singleton (what you call "global instance")

- $f3->local() always returns a fresh instance (what you call "local instance")

Note that the first use ("global") requires your class to extend \Prefab.

[bcosca]

It's just a fancy name for Service Locator.

[Richard Catto]

On Thursday, December 11, 2014 2:34:05 AM UTC+2, bcosca wrote:

@Richard Catto:

1. instantiated once when injected. access the same instance whenever / wherever referenced. ie. global scope

If your class extends Prefab, you automatically have the instance() method, so $f3->set('obj',myClass::instance()); should instantiate the class and give you the same object every time you retrieve via $f3->get('obj');

This is not an elegant solution, it is simply a working hack. I want an elegant solution.

I already have a working hack

I want a separate DI class where services are setup. I do not want user defined classes to have to extend anything.

 

 

2. instantiated each time it is injected. a fresh instance is referenced. i.e local scope

I don't understand what you mean by "local scope", but $f3->set('obj',new MyClass) should give you a new instance every time.

local to the method you're using it in.

 

 

definition of each class to be injected, could be via:

1. anonymous function (fresh object each time)

2.  new classname (same object each time)

Currently, the hive caters for the second type, but when creating the definitions, all the classes are instantiated immediately, not as needed. The anonymous function type is not supported at all.

If you wrap your object instantiation in an anonymous function, then you defer the process:

$f3->set('deferred',function() {

    return myClass::instance();

});

$deferred=$f3->get('deferred');

var_dump($deferred());

What exactly do you need that can't already be done?

the ability to define services, without necessarily instantiating them and having them instantiated as needed. That is an elegant solution.

 

[Richard Catto]

Better to read this:

http://docs.phalconphp.com/en/latest/reference/di.html

I was considering using phalcon but it's overly complex.

On Thursday, December 11, 2014 6:22:06 PM UTC+2, xfra35 wrote:

@Richard Catto, after reading your initial post, I had no idea of what you had in mind. I googled "dependency injection container" and stumbled on that, which made things even worse :P

But after @bcosca's answer, the picture got clearer. It looks like "dependency injection container" is some form of lazy loading with global dependencies.

In that case, I think the following should answer your question:

class MyClass extends Prefab {

  public $name='foo';

  private $db;

  function __construct(\DB\SQL $db,$name=NULL) {

    $this->db=$db;

    if ($name)

      $this->name=$name;

  }

}

$db=new \DB\SQL('mysql:host=127.0.0.1;port=3306;dbname=test;','user','pwd');

$f3->global=function() use($db) {

  return MyClass::instance($db);

};

echo $f3->global()->name; //foo

$f3->local=function($name) use($db) {

  return new MyClass($db,$name);

};

echo $f3->local('baz')->name; //baz

echo $f3->local('bar')->name; //bar

});

In that example:

- the database connection $db is a global "dependency"

- $f3->global() always returns the same instance/singleton (what you call "global instance")

- $f3->local() always returns a fresh instance (what you call "local instance")

Note that the first use ("global") requires your class to extend \Prefab.

On Thursday, December 11, 2014 1:34:05 AM UTC+1, bcosca wrote:

[Richard Catto]

correct.

[xfra35]

Those Phalcon docs are much clearer. Then I think you can easily implement your own DI container. See here for a quick example.

I don't see the use of adding it in the framework though.

What do you think?

[bcosca]

I agree it's not a must-have for everyone. It's syntactic/programmatic sugar for some, but it's an extra layer of fat IMO. So it's better served as an optional plugin.

[Richard Catto]

Well here are some reasons to include it in the core code:

1. Most frameworks implement Dependency Injection now - this is across the board of different languages.

2. Many developers are familiar with this pattern and rely upon it

3. The reason for this is because it makes testing of classes possible without having to worry about other classes causing problems - just create dummy services for the other classes. You can then be sure that when you test a single class, that no other code will run and introduce errors. You can thus test each class separately one by one.

4. A framework without DI is like a framework without routing. You can plug in a third party router, but it's so much better to use the built-in routing and its why many choose a framework in the first place.

5. DI itself is not fat. The implementation of it determines its fatness. You can still implement a fat free version of DI and developers will thank you for it.

Here's a discussion of DI that you might find useful:

http://stackoverflow.com/questions/130794/what-is-dependency-injection

This discussion offers many good reasons why DI is so useful.

[Richard Catto]

I think that's some excellent code you wrote there. I think you prove the point that adding DI to Fat Free doesn't have to add much code.

However you decide to add DI, as core code or as an optional plug-in, this sample code is a step in the right direction. It's simple and short, both exemplars of the Fat Free Framework that make people choose this framework over others.

Thank you.

On Thursday, December 11, 2014 11:15:25 PM UTC+2, xfra35 wrote:

Those Phalcon docs are much clearer. Then I think you can easily implement your own DI container. See here for a quick example.

I don't see the use of adding it in the framework though.

What do you think?

On Thursday, December 11, 2014 7:39:21 PM UTC+1, Richard Catto wrote:

[ikkez]

very neat. maybe we could just add that portion to the Registry class.

Am Donnerstag, 11. Dezember 2014 22:15:25 UTC+1 schrieb xfra35:

Those Phalcon docs are much clearer. Then I think you can easily implement your own DI container. See here for a quick example.

I don't see the use of adding it in the framework though.

What do you think?

On Thursday, December 11, 2014 7:39:21 PM UTC+1, Richard Catto wrote:

[xfra35]

True. The Registry already does the job of locating shared services, so if it has to be part of the framework, it should belong to the Registry.

But there's still one thing I don't fully understand: what would be a use case of non-shared services? Can someone provide an example?

BTW, where did that topic about software patterns go?

[Richard Catto]

I am going to test your code during the holidays.

A non-shared service is one which is created from scratch each time and does not retain any data from previous usage. This is useful in some instances, for example, when sending mail, you may to drop a previous connection and send mail via a different service. I have a mailer class like that.

Defining a service allows a class to be instantiated in a particular way, using custom arguments and a class of your choosing. It also allows testing of different classes. All you need to do is change the definition of the service and a new class is used throughout your code. The alternative is having to update every instance in your code that you instantiate the class, which is painful even in small projects.

Setting up your dependencies as services makes maintaining code much simpler and less painful. This is the chief reason this software pattern appears in almost every framework these days,.

On Friday, December 12, 2014 1:43:11 PM UTC+2, xfra35 wrote:

True. The Registry already does the job of locating shared services, so if it has to be part of the framework, it should belong to the Registry.

But there's still one thing I don't fully understand: what would be a use case of non-shared services? Can someone provide an example?

BTW, where did that topic about software patterns go?

On Friday, December 12, 2014 10:25:55 AM UTC+1, ikkez wrote:

[xfra35]

Thanks for your clarification.

I was wondering why "$mail=$di->mail()" would be better than "$mail=new Mail()". It looks like the DI container is a way of flattening signature/dependencies differences, which may come in handy when integrating a significant amount of third party libraries. The price to pay is that dependencies become harder to track.

Also I realize that it could be used as a way of defining "shortcuts" for common/frequent actions. E.g:

$di->set('sendMailToCustomer',function($to,$subject,$html){

  $smtp = new SMTP('127.0.0.1',25,'ssl','user','pw');

  $smtp->set('To',$to);

  $smtp->set('Subject',$subject);

  $body=Template::instance()->render('mail-customer.html',NULL,array('message'=>$html));

  $smtp->send($body);

});

$di->set('log',function($msg,$target='app'){

  $log=new Log($target.'.log');

  $log->write($msg);

});

Then in your app:

$di->sendMailToCustomer('john@doe.me','Your new password','...');

$di->log('John Doe required a new password');

On the other hand, the same could be achieved with a wrapper class:

Utils::sendMailToCustomer(..);

Utils::log(..);

[Richard Catto]

You can use wrapper classes and that is the route some take, however, what if you decide to switch to using a different third party library which exposes a different interface?

e.g. upgrading from swiftmailer version 3 to version 4 required a rewrite of wrapper classes.

it's all well and good to just rewrite the wrapper class, and then start testing it, but if you want to revert to the previous wrapper class, it means swapping files in and out of your library directory.

better to write two wrapper classes with different names and use a service file to setup the service to use the new wrapper class.

switching between the two classes is a matter of commenting / uncommenting code in the service file, instead of swapping files in and out of the library and keeping track of which file (both of which are named the same for autoload purposes) contains which code.

On Monday, December 15, 2014 2:00:30 PM UTC+2, xfra35 wrote:

Thanks for your clarification.

I was wondering why "$mail=$di->mail()" would be better than "$mail=new Mail()". It looks like the DI container is a way of flattening signature/dependencies differences, which may come in handy when integrating a significant amount of third party libraries. The price to pay is that dependencies become harder to track.

Also I realize that it could be used as a way of defining "shortcuts" for common/frequent actions. E.g:

$di->set('sendMailToCustomer',function($to,$subject,$html){

  $smtp = new SMTP('127.0.0.1',25,'ssl','user','pw');

  $smtp->set('To',$to);

  $smtp->set('Subject',$subject);

  $body=Template::instance()->render('mail-customer.html',NULL,array('message'=>$html));

  $smtp->send($body);

});

$di->set('log',function($msg,$target='app'){

  $log=new Log($target.'.log');

  $log->write($msg);

});

Then in your app:

$di->sendMailToCustomer('jo...@doe.me','Your new password','...');

[Dilemma]

Form Creation and Validation is probably something that most web projects need.

[bcosca]

Form validation is fine.

However, form/report creation and scaffolding is something that a framework should never be involved with. Templates render them obsolete. Besides, this is a job for the UI/UX designer and the design could be tangential to the developers' ideas.

[Hollol]

form validation and language class..

5 Aralık 2014 Cuma 12:40:31 UTC+2 tarihinde bcosca yazdı:

[Lux Logica]

1) F3's greatest appeal is, IMHO, its gentle and short learning curve, and therefore it is not just a powerful framework, but also a fantastic framework for those new to php, and even to programming itself. I would love to see a total beginner's guide to programming with F3 - i.e., 'Learning PHP with F3' - taking the new user by the hand, step-by-step through installing and configuring the framework, then developing progressively more complex projects while introducing the features of the framework - and of php itself, when F3 does not cover it.

2) A 'Cookbook' for more experienced users, with recipes for common requirements, like building a group-based authorisation system.

[ikkez]

Hey bcosca, old buddy :) When do you release the next version? You said:

3.3.1 will be released before year-end.

But the year is almost over now. Now the last release is "only" 5 month old, but we fixed a lot of things and i think people should not bother with those in 2015 again.
In addition i think that the version number of 3.3.1 is not appropriate anymore. In the versioning system the versions are numbered like [major.minor.patch], and i really think that what we did the last months, isn't only a little 3.3.0 > 3.3.1 patch release - we added many features, some API changes, and even a PHP version requirement increase. That all shouts more like 3.4.0 ! Think about that ;) and have a happy new year =)
best wishes.

[Achille D'Aniello]

Oh, yes! I agree... New year, new version!
Happy new year, f3 workers!

[bcosca]

The F3 team has worked hard and long to bring you 3.4.0 on the first day of the year. Thanks everyone! Enjoy the creamy goodness of this version of F3 :)

[Achille D'Aniello]

This is the first good news of new year!

Many thanks!

[Farhad Sakhaei]

An idea using php magic methods and ArrayAccess:

$f3->set( 'AUTOLOAD' , '/includes/' );

To:

$f3['AUTOLOAD'] = '/includes/';

or

$f3->AUTOLOAD = '/includes/';

[Nash Born]

[redirects]

GET|POST /r@region/@city=/r@region/@city/3days

function reroute($url,$permanent=FALSE) {
$par=$this->get('PARAMS');
unset($par[0]);
foreach ($par as $key=> $val) {
$url= str_replace("@$key", $val, $url);
}
if (PHP_SAPI!='cli') {
if (preg_match('/^(?:@(\w+)(?:(\(.+?)\))*|https?:\/\/)/',
$url,$parts)) {
if (isset($parts[1])) {
if (empty($this->hive['ALIASES'][$parts[1]]))
user_error(sprintf(self::E_Named,$parts[1]));
$url=$this->hive['BASE'].
$this->hive['ALIASES'][$parts[1]];
if (isset($parts[2]))
$this->parse($parts[2]);
$url=$this->build($url);
}
}
else
$url=$this->hive['BASE'].$url;
header('Location: '.$url);
$this->status($permanent?301:302);
die;
}
$this->mock('GET '.$url);
}

GET|POST /r/@city=/r/@city.html;302

GET|POST /r/@city=/r/@city.html;301 

[Farhad Sakhaei]

Hi,

Lets begin using ArrayObject :D

http://php.net/manual/en/class.arrayobject.php

http://www.lornajane.net/posts/2011/arrayaccess-vs-arrayobject

[ikkez]

Sorry, but this idea comes too late, we already added that with the v3.4 release, exactly like you have suggested ;) https://github.com/bcosca/fatfree/blob/master/lib/changelog.txt#L19

[Farhad Sakhaei]

You mean ArrayAccess ?

I mean ArrayObject :)

Better than ArrayAccess

And why don't use in Base ?

feeling good with ArrayAccess:

Sample: :)

/** Initialize Log system */

$f3['LOGS'] = 'logs/';
$f3['logger'] = new Log('error.log');
$f3['logger']->write( 'Hello' );

I think we can fly with ArrayObject :D

Example:

foreach ( $f3['names'] as $key => $value) {
     .... Do somethings
}

On Saturday, January 17, 2015 at 1:14:14 AM UTC+3:30, Farhad Sakhaei wrote:

You mean ArrayAccess ?

I mean ArrayObject :)

Better than ArrayAccess

And why don't use in Base ?

[ikkez]

It is used in base. it represents the hive. ArrayObject is just more overhead. I think ArrayAccess is sufficient. You probably wont need any complex array functions on the hive directly, and iterating with foreach over a key like $f3['names'] is already working now, since you left the array object on accessing the first key ;)

Am Freitag, 16. Januar 2015 23:18:04 UTC+1 schrieb Farhad Sakhaei:

You mean ArrayAccess ?

I mean ArrayObject :)

Better than ArrayAccess

And why don't use in Base ?

feeling good with ArrayAccess:

Sample: :)

/** Initialize Log system */

$f3['LOGS'] = 'logs/';
$f3['logger'] = new Log('error.log');
$f3['logger']->write( 'Hello' );

I think we can fly with ArrayObject :D

Example:

foreach ( $f3['names'] as $key => $value) {
     .... Do somethings
}

On Saturday, January 17, 2015 at 1:14:14 AM UTC+3:30, Farhad Sakhaei wrote:

You mean ArrayAccess ?

I mean ArrayObject :)

Better than ArrayAccess

And why don't use in Base ?

On Saturday, January 17, 2015 at 12:51:54 AM UTC+3:30, ikkez wrote:

[Farhad Sakhaei]

OK Christian , Thank you , I am happy with ArrayAccess right now

I think it is need to implement Registry class with ArrayAccess too , isn't it ?

[bcosca]

Registry doesn't implement ArrayAccess. It's too much a hassle to instantiate a variable/object when all the methods and properties are static anyway.

[ved]

Hey there, I'll throw my $0.02 in.

First of all, let me say that I really love F3. Been using it pretty much exclusively since the v2->v3 transition and It has served me pretty well. At the time I was looking for a simple framework that provided basically just a simple routing system because I was tired of most frameworks with strict syntaxes, xml or yaml cfg files, etc. What I eventually found was that f3 provided me with not only the simple routing I was looking for but also other brilliant features that I currently pretty much depend on. Features aside, the developer freedom, flexibility and lack of strict guidelines is the main key here.

That being said, my first two suggestions for the next version have already been discussed here and on gh issues, and they are better composer integration and better documentation.

Regarding composer, I understand that doing things the composer way is maybe less optimal that a regular f3 install, or that the composer autoloader is slower, or less flexible, or any other reasoning to not emphasize it's use, but the truth is, composer is now pretty much a standard for dependency management on php. That, in my opinion, is a *good thing* as it gives php something like npm, ruby gems, etc. Basically a standard way for developers to maintain their apps dependencies and a standard way to add new external libs to their projects.  Another reason to adopt and encourage the use of f3 through composer is the developer freedom and flexibility I mentioned earlier. Now a days, most apps that warrant the use of a framework like f3 will usually integrate a number of external packages. And most packages now a days are available with composer. Also, most current public and popular apis use and document composer as the main way to integrate their sdk's. Facebook, google, twitter, braintree payments, stripe payments, even the Paypal sdk all use composer.

Now, me personally, I've figured out how to use composer, and I know f3 has had the composer.json file for a while and it works fine. The thing is, nowhere in the documentation or README.md does it mention composer. The less-than-a-minute hello world tutorial turns into a lot more than a minute if you have to figure out how to make it work using composer. The documentation should have the composer installation instructions and that hello world using composer as the first things. The f3 = require(base.php) thing, while pretty cool, is confusing to new people coming to f3. So why not use composer and $f3 = \Base::instance(); or $f3 = \f3\Base::instance() or something like that. Of course, you should always also keep the instructions for a non-composer install.

Now regarding the documentation. I think there is too much copy on github's readme. The readme is the first thing you see on github and should contain just basic install instructions and some simple examples of common tasks or features that can be considered very useful most of the times. At the top of my head I think some examples demonstrating the router with closures and classes, the ReST (map) feature, the caching system and maybe the data mappers should be enough to show as a quick intro and getting started to get an overall feel for the app. Highlighting any new features on the latest version could also be here. Then all other supported features should be mentioned but leave the large blocks of text, syntax instructions and edge case considerations for another section (ideally, a user manual/reference, article/tutorial collection, wiki, blog or any combination of these).

As it is now, the readme is a mix between a manual, some tutorials, and some generic programming notions and developer views thrown in (like the pros and cons of db relations or the don't cache dynamic content, etc). All that information is great and it should all be available. I just think that it could be better organized. I would suggest a simplified readme on github and improved documentation on http://fatfreeframework.com/. Also better documentation of new features between versions would be a major plus. Reading the changelogs I sometimes see lots of new stuff added, but no real context on how can I possibly make use of such features.

As for actual new features for f3, although I haven't thought about it too much, I have the following suggestions:

- Better handling of translation files/strings. That is, find some way to not make them part of the main hive. As it is now, I usually name my translation variables like "lang_something" to prevent any colisions, but would like to see something like maybe a kind of helper function (for example $f3->i18n('mystr') or {{ @i18n('mystr') }} and f3 would lazily load the ini files as needed. (or something like that).

- Support for hhvm. I'm mentioning this because of the recent hype and performance increases hhvm seems to be bringing to php. I've done some tests with it, and at least the things I've tried seemed to be working just fine. But It would be nice to have a sort of "official support" for it. Unfortunately, I believe the hhvm team only supports PHPUnit on their framework testing system so that's probably a bit of a stretch for now.

- Something like ikkez's Cortex would be nice as some kind of basemodel plugin. The ability to, if needed, use an extended version of the basic mappers that implement relations and validations.

- Ability to configure what happens when a session is invalidated by ip change or csrf protection.

That's all for now I guess. Again, thanks for all your work with f3.

[Achille D'Aniello]

@ved

- Better handling of translation files/strings. That is, find some way to not make them part of the main hive. As it is now, I usually name my translation variables like "lang_something" to prevent any colisions, ... +1

- Ability to configure what happens when a session is invalidated by ip change or csrf protection +1

- add ikkez's Cortex +100!

[Anatol Buchholz]

I´d like to cite Achille:

- add ikkez's Cortex +100!

Cortex is great and still "fatfree" – would be great to see it in the core … 

[Steve Cove]

I also agree that cortex is an important plugin.

Whether or not it gets officially integrated, i think it should certainly get a mention in the databases section of the user guide.

"No relational orm" is a complaint i have heard from a few people i have mentioned fatfree to.

Also a minor thing:

If php 5.4 is the new requirement, old style array syntax can be replaced:

$old = array(1,2,3);
$new = [1,2,3];

Should save a few bytes, and is clearer imho.

[ethanpil]

This might be crazy and really off the wall... Have you thought about re-implementing in C as a PHP module?

[Steve Cove]

One thing that would be usefull would be to have f3 in its own namespace, eg \FatFree\

On Friday, 5 December 2014 10:40:31 UTC, bcosca wrote:

2015 is round the corner........

[bcosca]

I disagree with this mad rush about having a framework, ANY framework, in it own namespace. A framework is the keystone of your app; it is not an optional component. Neither is it a library you can use on demand; it embodies the entire structure of your app. Every app component will not run properly without it. As such, it is only logical that it be in the root namespace where it belongs: on the same level as your app; no, the basis of everything.

Be careful what you wish for. Lots of use statements can be annoying.

[Richard Catto]

agreed. namespaces are for libraries, add-ons, plugins, not the app itself.

On Wednesday, February 18, 2015 at 1:34:03 PM UTC+2, bcosca wrote:

I disagree about this mad rush about having a framework, ANY framework, in it own namespace. A framework is the keystone of your app; it is not an optional component. Neither is it a library you can use on demand; it embodies the entire structure of your app. Every app component will not run properly without it. As such, it is only logical that it be in the root namespace where it belongs.

Be careful what you wish for. Lots of use statements can be annoying.

On Wednesday, February 18, 2015 at 7:25:35 PM UTC+8, Steve Cove wrote:

[Rayne]

F3 isn't your app. You are free to use it as framework or only some of its components. It's a good thing that most frameworks and libraries have their own namespace instead of polluting the global namespace. There is no reason to fear namespaces and use statements.

[bcosca]

Unlike other frameworks, F3 aims to be usable - not usual.

F3 doesn't have to be like other frameworks.

F3 doesn't pollute the global namespace. Are you really sure you understand what this means?

F3 doesn't fear namespaces. It was the first framework to support namespaces; it was the first framework to require PHP5.3.

[Rayne]

What is unusable about a vendor namespace? It's fine to not use one but please help me to understand the drawbacks. Also PSR-4, which F3 doesn't have to follow, recommends to use one.

Thank you.

[Steve Cove]

Ok, i dont have any strong feelings about it either way, i just thought it would be useful, based on my experience, not on what any other framework is doing (in fact, fatfree is pretty much the only php framework i use)

My specific reasoning is that, being a microframework, it is highly likely people will build out their own 'fatter' framework around it, and that fat framework is likely to have classes that would logically clash with f3.

Anyway, i just thought of something else that would be a useful addition to fatfree - the ability so disable route sorting via Hive key or similar mechanism.

I understand why the routes are sorted, but sometimes it would be usefull to just have f3 use the 1st matching route it finds, so you can have routes like:

/about=specificFunctionForAboutPage
/contact=specificFunctionForContactPage

;user added pages, pulled from database
/@page=pageController->show

On Wednesday, 18 February 2015 11:34:03 UTC, bcosca wrote:

I disagree with this mad rush about having a framework, ANY framework, in it own namespace. A framework is the keystone of your app; it is not an optional component. Neither is it a library you can use on demand; it embodies the entire structure of your app. Every app component will not run properly without it. As such, it is only logical that it be in the root namespace where it belongs: on the same level as your app; no, the basis of everything.

Be careful what you wish for. Lots of use statements can be annoying.

On Wednesday, February 18, 2015 at 7:25:35 PM UTC+8, Steve Cove wrote:

[ethanpil]

I wanted to mention that there are quite a few issues labeled as enhancements on github, many of which are worthy of consideration... Least of all, my own request for $mapper->touch()   

;)

https://github.com/bcosca/fatfree/issues/620

[rafaelmsantos.com]

Hi @bcosca, hope everything is alright with you, do you have any news on the new F3 version for us?

Cheers

[bcosca]

I wouldn't hurry if I were you. Any major version change in a dev tool is always a pain in the neck for devs with existing code bases to maintain. It's guaranteed to break something, specially with the (radical) ideas, feature requests, and other hardcore changes floating around, that it will keep all of us busy. Well, it's a good job maintenance strategy for the employed ;) but no fun for those with "almost done" projects.

The mythical man-month says it all: "Good cooking takes time." Blah, blah. That said, the 3.4.0 code is still in active development with experimental features that will make its way to the next version eventually.

There are no timelines for 4.0. @ikkez and @xfra35 deserve to be mentioned as my new co-maintainers. We will make sure that F3 is sweet, ripe, stripped of all traces of fat, and ready to eat.

F3 will be turning 6 years old this year. It's still alive and will stay that way for as long as there's a community rallying "give me an F, give me a 3" behind it.

I thank you all for the TLC you gave to this project. You deserve equal credit.

[rafaelmsantos.com]

Thanks for your answer, such good news in my opinion. Hope to hear from you again, any time soon. 

I think I could speak for everyone in this community, when I say that everyone here will gladly help you get another set of 6 years in the project. 

Cheers

[Richard Catto]

fat free is awesome. I looked at framework after framework but found all of them to have a steep learning curve.

I found it easy to migrate an existing project to using fat free. I implemented routes, global variables, templates and config files. it was smooth sailing.

My next thing is to migrate from mysqli to PDO. I can take it one class at a time.

[Doonge Hagen]

A refined "hooking" system for the route handler (Base->run()), beforeroute and afterroute.

Typically, the front-controller calls a controller after filtering the route list, inbetween controller->beforeroute and controller->afterroute, especially if you define routes in a config file (no fancy anonymous function).

I got stuck because I wondered how to implement a permission system, and learned about the decorator pattern (I'm not a professional) on http://stackoverflow.com/questions/3430181/how-can-i-implement-an-access-control-list-in-my-web-mvc-application

I was annoyed because I realized I had to route everything to the decorator container (if I wanted to make the check outside the controller class, outside of beforeroute), and somehow delegate the routing task to it (destroying the purpose of fatfree inner routing system).

I had a look at Laravel, and I saw they use a "middleware" system, which to my untrained eyes looks alot like the hook system in fatfree, just more refined in the sense you are not stuck within the controller class.

In fatfree, if you use another string than 'beforeroute, afterroute' in Base->call($func, $args, $hooks), it does nothing anyway.

So I was thinking of having a MIDDLEWARE (or ROUTEHOOKS) F3 global that would be defaulted to ['before' => ['beforeroute'], 'after' => ['afterroute']]

but could be changed to something like this

[
    'before' => [
        'beforeroute', //resolve to CONTROLLER->beforeroute (or a generic beforeroute() function if CONTROLLER->beforeroute doesn't exist)
        'generic_function', //resolve to generic_function (assuming CONTROLLER->generic_function doesn't exists)
        'Middleware->intercept' //resolve to Middleware->intercept (not CONTROLLER)
    ],
    'after' => [
        'afterroute' //resolve to CONTROLLER->afterroute (or...)
    ]
]

which means some change here (base.php line 1504 to 1518), within Base->call():

                // Execute pre-route hook if any

if ($obj && $hooks && in_array($hook='beforeroute',$hooks) &&

method_exists($func[0],$hook) &&

call_user_func_array(array($func[0],$hook),$args)===FALSE)

return FALSE;

// Execute callback

$out=call_user_func_array($func,$args?:array());

if ($out===FALSE)

return FALSE;

// Execute post-route hook if any

if ($obj && $hooks && in_array($hook='afterroute',$hooks) &&

method_exists($func[0],$hook) &&

call_user_func_array(array($func[0],$hook),$args)===FALSE)

return FALSE;

return $out;

and some changes in (base.php ), within Base->run() (change the nature of the third parameter, or ignore it totally, or add a parameter in the run() function, whatever suits your boat best).

// Call route handler

$result=$this->call($handler,array($this,$args),

'beforeroute,afterroute');

Considering the behavior of run() regarding the $hook parameter, I think it will be easily retro compatible.

[ikkez]

Hey Doonge, some more control about the hooks would be nice, indeed. I tried to put your attempt into a little plugin. It's a draft and currently only works on named routes, but maybe you get the idea: https://gist.github.com/ikkez/c3bc58d5189b2e7b804b/e6797eba84b80bb7d98e992852de159815aa5df5
I guess the point is to find a nice way to configure the hooks of one or multiple routes / groups. I have no better idea yet, but maybe we can think of a neat way for v4 event handling.

[Andrew Brookes]

Help make F3 better. Your active participation is truly welcome.

  What i haven't seen identified  is WHO is f3 being pitched at?
   The higher up the ability level aimed at  will correspond with less of the population using it

  On the Docs you know when you buy a new printer or other gissmo and the book is a hundred pages plus long but there   is included  a three page leaflet for the impatient (which i always use) then a brief complete overview somewhere at the start of the docs might be helpful.

 I initially got my understanding of the fatfree framework here:  https://www.digitalocean.com/community/tutorials/how-to-use-the-fat-free-php-framework
 
 

[ikkez]

  What i haven't seen identified  is WHO is f3 being pitched at?
   The higher up the ability level aimed at  will correspond with less of the population using it

Well, since the framework's core footprint (Base) is small and its usage is very simple (routing, caching, config&variables) and easy to learn,.. F3 is or should be handy for everyone, regardless if one is a novice or expert in PHP programming. Nevertheless it has a lot of advanced features, plugins and a good documentation of them (mostly), which makes it interesting for bigger and more complex applications.
 

  On the Docs you know when you buy a new printer or other gissmo and the book is a hundred pages plus long but there   is included  a three page leaflet for the impatient (which i always use) then a brief complete overview somewhere at the start of the docs might be helpful. 

I can see your point. Well if we would write up some essentials like you have in the blog article you posted, it's maybe easier for a quick start, but I'm afraid of people who do not read the rest of the usual user guide when the first questions appear. It's okay to have blogs that give you a quick start, but i'm not sure if it makes sense to left out details and just throw code samples to the people. We have the user-guide on the one hand, which gives a step-by-step introduction to all topics, including some edge cases, samples, warnings and recommendations, and on the otther hand we have the API docs, that describe every method and feature with detailed samples. Maybe another "essentials" section would be more confusing than helpful. But don't get me wrong, if there is a way to improve the docs in any way, let's do it. Maybe we can collect some ideas or problems first and see what we can do.
If anyone encountered problems or felt lost when studying the docs, please tell us and give feedback. Of course we want to provide an easy, understandable and helpful guide in a nutshell. But we can't do it all alone. F3 lives from its community and you all are part of it. Don't fear the way to the Pull-Request button, create blogs, write articles, tell your friends, mingle in IRC and shape F3's ecosystem to become strong. For a better future with more fun at work and less headaches while coding.. bla bla.. you know what I mean ;)

[Doonge]

About the common F3 $ttl variable (time to live), which is tied to the CACHE functionality.

How do you do to destroy a cached variable (or SQL query, or...) once you know you've just "UPDATE" the data?

Typically the flow I envision is to find back the CACHE hashes of all the "READ" I want to refresh, and clear them. Whether or not I want to recreate them I do not know yet, but a simple (and maybe not realistic) way of symbolizing it would be to use a negative $ttl in all case for the READ access, and adapting the caching behavior accordingly.

If $ttl is negative:
cache->clear($hash)
$ttl = asb($ttl) for the following operations.

Would it be useful?

[James Ringrose]

F3 is brilliant in terms of it's balance between utility and complexity. I also appreciate the well organized documentation (wish I could take it on a plane with me), but it could really do with some more examples. The code snippets provided are often difficult to map onto whatever problem I am facing or trying to learn. 

I think a "cook book" would be a terrific help. More best practices than things to slavishly copy.  Some of the "fatter" platforms out there do have more extensive examples as well as "build FaceBook in 5 minutes" type tutorials.

However, I smile everytime I write a prototype, or finish a mobile app in less time I would believe, but I also blush at my stupid mistakes and a couple of times, literally started over because I wound up with helper classes that had helper classes and this forum or rereading the docs caused me to have an aha!! moment.

Some examples about third party integration would also be appreciated - I have gotten AWS, DataTables and other packages to work, but some of them took a lot of effort that I would have really appreciated some help with understanding. 

Just don't chuck out the baby with the bathwater here, what we have is amazing and really appreciated.

[Rayne]

No internet on the plane? Get a copy of the website and/or documentation:

• Website: https://github.com/F3Community/F3com
• Documentation: https://github.com/F3Community/F3com-data
  

[Daniel]

I know one feature that I miss from coldfusion is the ability to use CFOUTPUT with GROUP

example...

this allows someone to pull a view with a join

class-students are 1 to many

in cf someone might do something like this

<cfoutput query="classes_students_pets" group="class_id">
    <!--- groups the query and returns one item per class_id (as long as the result is ordered by class_id) --->
    Class Name: #class_name#
    Students:
    <cfoutput group="student_id">
        <!--- loops through all rows that have the same class_id, --->
        #student_name# has pets: 

              <cfoutput>
            <!--- lists all rows that match student_id and class_id--->
            #pet_name#
        </cfoutput>
    </cfoutput>
</cfoutput>

I've seen some implementations of this in php, but most are use specific, meaning they are not reusable.

It would be handy if this kind of logic could be easily used

I know that <repeat> pretty much does this, but it seems to me that the array has to be prepped like this for it to work

$f3->set('div',
    array(
        'coffee'=>array('arabica','barako','liberica','kopiluwak'),
        'tea'=>array('darjeeling','pekoe','samovar')
    )
);

would it be possible to have the mappers create this kind of result automatically based on specified groups?

I'm not sure how the code would look.... but I'm thinking it would require defining the GROUP_BY levels, and the columns at each grouping.

I feel that this would be handy, but maybe just to me because I find myself missing the only redeemable feature of ColdFusion

On Friday, December 5, 2014 at 3:40:31 AM UTC-7, bcosca wrote:

2015 is round the corner. 3.3 has reached its peak. Don't worry, it won't be abandoned. 3.3.1 will be released before year-end. Now we're preparing the specs for the next incarnation of the framework you've come to know and love. In light of this announcement, we would like to engage everyone in a healthy discussion of what 4.0 should be like. Each feature request must have a justification. Code volunteers are also welcome and must be stated in the entry.

To start off, a code review is now an absolute necessity.

* I plan on cleaning up the hive's built-in variables. It's starting to be a mess and some variables add fat where there should be none.

* Event triggers/handlers should be unified. A standard mechanism must be developed. Those before... after... on... prefixes should be eliminated.

* PHP 5.4 will be the new minimum. 5.3 has already reached its end of life. No use beating a dead horse.

If you have ideas/suggestions about how the future F3 should behave, we're all ears. Bear in mind, the basic single-file functionality will still be there and will always conform to our non-fat philosophy. Everything else will be a plugin.

Remember, this should be a healthy discussion. Feature comparison with other frameworks is fine but should never be a basis for a feature request. A rationale should stand by itself.

[Daniel]

I would like to see ability to add parameters to aliases in templates that doesn't seem like a hack.

I noticed the issues was brought up already

https://groups.google.com/forum/#!searchin/f3-framework/ALIAS$20$20template/f3-framework/cctEWVHNBVo/3RD0XvaJG_kJ

I've noticed this in the change log, but it seems not usable if called through {{@ALIASES}}

*	Alias: allow array of parameters

[ikkez]

This can already be made like this:
{{ 'list', 'a=5' | alias }}

or a bit more dynamic:
{{ @name, 'a=5,b='.@id | alias }}

[Dilemma]

How about SASS support in the template engine for css

 

[Richard Catto]

put that in a plugin, otherwise it just adds FAT

[ethanpil]

Dilemma, off topic, but to answer your request, here is what I do for SASS:

Download the SCSS library for PHP: http://leafo.net/scssphp/

I keep it in:  lib/scssphp/

In /.htaccess:

#Sass Parser: anything /css/FILENAME.css -> FILENAME.scss
RewriteRule ^css/(.*).css?$ style.php/$1.scss [NC,L]

In root folder, I have style.php:

<?php
require "lib/scssphp/scss.inc.php";
$scss = new scssc();
$scss->setFormatter("scss_formatter");
$server = new scss_server("ui", null, $scss);
$server->serve();       
?>

In my HTML, I use:

<link rel="stylesheet" href="/css/style.css">

In /ui I have my file of actual SCSS code: /ui/style.scss

And everything just works. SCSSPHP just checks if the file needs to be recompiled and does it transparently, otherwise sends the cached version.

[ethanpil]

I was thinking today that perhaps we can add a hook / action system, similar to this:

http://docs.slimframework.com/hooks/how-to-use/

[bcosca]

Some code for an on() and off() hook, as well as trigger() capability is in the works. It is definitely coming. What is not definite is the release date, although there is a chance it may appear before 4.0 comes along.

[Ethan Piliavin]

That's very exciting news. I hope there will be multiple hooks addable per trigger with priority? As well ability to remove actions?

On Aug 9, 2015 5:52 PM, "bcosca via Fat-Free Framework" <f3-framework+APn2wQfMLSpXhGq3PUv...@googlegroups.com> wrote:
>
> Some code for an on() and off() hook capability is in the works. It is definitely coming. What is not definite is the release date, although there is a chance it may appear before 4.0 comes along.

>
>
> On Monday, August 10, 2015 at 7:07:30 AM UTC+8, ethanpil wrote:
>>
>> I was thinking today that perhaps we can add a hook / action system, similar to this:
>>
>> http://docs.slimframework.com/hooks/how-to-use/
>>

> --
> You received this message because you are subscribed to a topic in the Google Groups "Fat-Free Framework" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/topic/f3-framework/IuwlCpNvyMs/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to f3-framework...@googlegroups.com.
> To post to this group, send email to f3-fra...@googlegroups.com.
> Visit this group at http://groups.google.com/group/f3-framework.
> For more options, visit https://groups.google.com/d/optout.

[Rayne]

Another feature request: get the values of INI files as array or allow an optional HIVE prefix. This could be useful for additional configuration or meta information which shouldn't mess with F3's state or HIVE variables. For instance loading article meta information when working with plain files instead of relational or document oriented databases.

Example: Every article has a meta.ini file. To render the article list, every (not trustworthy) meta.ini file has to be interpreted.

[Richard Catto]

articles are stored in a database along with all meta info, no need for files.

[Dilemma]

Looks like a good implementation - I'll give this ago.

[Nuwanda]

I use F3 because it's simple yet powerful in its core features.

I prefer solid and comprehensive documentation. It's a common and frustrating failing of many frameworks that the documentation while adequate, lacks depth. And it's depth--examples and use cases--that enables adopters to get excited about the framework and its possible applications.

There's nothing wrong with F3's docs but they are the minimum required. They are well laid out and clear. But I would prefer to see effort put into more OFFICIAL examples and use cases than there is currently.

Forums are fine but are not a substitute for solid docs. Docs are authoritative and present the official, intended usage of any software.

So I say, make F3 as comprehensibly user friendly and as well-explained as possible before creating new features.

[James Ringrose]

I posted something similar, if a bit less eloquent, a while ago to a somewhat negative reaction. I agree that docs are very clear and understandable, but they lack use cases and examples. A couple of times I have built my own "helper" class only to discover a better way lurking in the core someplace.

From the postings in this group it's apparent that for someone starting out it is really easy to get on the on-ramp, but then it gets hard. This is particularity true with the database classes that seem really simply and powerful, but you pretty soon hit the "how the heck do I..." wall.

I know docs are tedious and hard, but I think Nuwanda is right - this is the key to making F3 more widely accepted. 

I recently completed a project that was a really good proof of how quickly you can build apps with F3 as the foundation. I then had to deal with view that it would be hard to maintain because the framework's docs were not detailed enough for subsequent programmer's. As it happened once they saw the architecture, code and real simplicity, I think we have another convert. :-)

[Richard Catto]

In respect of the captcha plugin, the documentation does not even meet the minimum requirements.

I had to use google to find help with it, which I did, but if I had not found help elsewhere, then I would have been clueless as to how to implement the captcha plugin.

There are still aspects of it that I am clueless about.

Nowhere in the docs does it state that in order to get the captcha image to display, I need to create a route for the image.

I still don't know how to use the dump() method of \Image

[Steve Cove]

Whilst i agree that official tutorials are a great way to introduce a frameworks features, it is not really that feasible with a microframework like F3.

The very ethos of the framework is that it is a minimalist collection of components that can be used as you require.

Any non trivial application will be based on userland code and conventions - for example every app i have built uses a form of MVC at its base, but i doubt any two users (or core contributors) could agree on how to do MVC with fatfree.

Similarly, authentication and authorization are another core component of most large apps, but how you handle that is up to you - there is no official way.

Even the excellent Cortex ORM is an optional plugin maintained outside the official repository - its just an option among many (doctorine, redbean, raw sql, etc).

I would selfishly love to see some MVC application structure baked into the core, but i doubt the maintainers will go for this, for good reason - the more opinionated a framework becomes, it either becomes more specialized (eg looses its general purpose nature) or more heavily (over)engineered.

With an un-opinionated framework, the best you can do is document the components well. It is down to the user to create their own style guidelines and structure.

With regards to the actual documentation, the fatfreeframework site is powered by git, so you can make pull requests: https://github.com/F3Community/F3com

[bcosca]

I agree with what Steve has expressed with such fluency and fire. Any attempt to dictate any structure (MVC, HMVC, RMR, etc) will be counter-productive and goes against the very nature of a minimalist framework. As the dev lead (and longest full-time user) of this project, I noticed that even my own code has evolved thru the years, so I don't think focus on an official definitive structure is the way to move forward.

Having said that, I echo Steve's recommendation about the documentation. I'm sure everyone is aware that thorough documentation of the framework is not a small undertaking. With only a handful of regular core contributors, our hands are full with introduction of new features, enhancements, bug fixes, tech support, blah, blah, every dev here knows the drill. We appeal to everyone to submit pull requests to the documentation repo at https://github.com/F3Community/F3com instead. It's one way of giving back something to this project.

[Joseff Betancourt]

This would be useful. I usually write my own app layer based trigger... is this still far off or should I wait it out?

[Joseff Betancourt]

>>I would personally love to see some application structure baked into the core, 

Please no. f3 is great because of the hive and it's plugin type layering for all other functionality. Cementing it into this block of central code undoes the modular nature of f3 in my opinion.

>>With regards to the actual documentation, the fatfreeframework site is powered by git, so you can make pull requests: https://github.com/F3Community/F3com

Very good point that I had not considered before.

On Monday, August 17, 2015 at 7:59:29 AM UTC-4, Steve Cove wrote:

Whilst i agree that official tutorials are a great way to introduce a frameworks features, it is not really that feasible with a microframework like F3.

The very ethos of the framework is that it is a minimalist collection of components that can be used as you require.

Any non trivial application will be based on userland code and conventions - for example every app i have built uses a form of MVC at its base, but i doubt any one user (or core contributor) could agree on how to do MVC with fatfree.

Similarly, authentication and authorization are another core component of most large apps, but how you handle that is up to you - there is no official way.

Even the excellent Cortex ORM is an optional plugin maintained outside the official repository - its just an option among many (doctorine, redbean, raw sql, etc).

I would personally love to see some application structure baked into the core, but i doubt the maintainers will go for this - the more opinionated a framework becomes, it either becomes more specialized (eg looses its general purpose nature) or more heavily engineered.

[bcosca]

The release cycle is usually 6 months. I noticed too that a vast majority of F3 users opt to deploy the dev branch itself, despite its name is actually just as stable as the master. So once it appears in the dev branch it's safe to assume it will be in the next release.

[Nuwanda]

"With an un-opinionated framework, the best you can do is document the components well."

This is precisely what I was saying above. I just want to know that the new or improved features defined in a changelog have been added to the docs so the changelog doesn't become an exercise in guessing, or worse, irrelevancy.

Further, it seems reasonable that the more well-documented the components of F3 are, the fewer support requests there will be. That is, a day spent updating the docs has to result in much more than a day being saved in support/forum time.

I'm also not against the idea of using pull requests but it's a bit of a catch-22: how does one really know what's missing if they don't know it's missing? Frankly, I read the docs to see what's possible.

[Steve Cove]

I have edited my post to better highlight my intention - i agree with you.

Though on reflection i dont see why some optional namespaced plugins couldnt be written to encapsulate the main stuctures used (MVC, RMR? whats that -> googles-> oh interesting!).

Time to put my money where my mouth is..

[Steve Cove]

Yes, fair enough. Really the only option for non contributors is the trawl the pull requests, which might not be very productive, and even result in misinterpretations.

However i good habit would be to make a documentation pull request if you ask a question on here and get an answer that isnt mention on the docs.

I'll try and spend a bit of time going through some recent questions and see if there are any answers that could go into the docs.

[David Foy]

One big, big help would be if the code examples were fully functioning working snippets. I often make a very basic working snippet of whatever it is that I'm trying to do, so I can be sure it works before building it out step by step. Is there some organized place where I could upload my good ones for others to look at or use?

[Richard Catto]

pastebin

[Nuwanda]

Thanks, Steve.

By way of example, regarding the changelog, here's what I mean. The lastest changelog, 3.5.0 is here:

https://raw.githubusercontent.com/bcosca/fatfree/master/lib/CHANGELOG

And it lists:

NEW: [configs] section to allow config includes

Great. But the config docs don't mention it at all:

http://fatfreeframework.com/framework-variables#ConfigurationFiles

It seems to me that there's no point in new features if the docs don't get updated with an explanation of that new feature. Even more
problematic are existing functions that have been updated or enhanced since the changes are often subtle or esoteric.

The starting place for doc updates should be the changelog since that's the official record of changes. Sure, you can use forum
questions as a way to enhance or clarify the docs, but that's like doing things backwards since most people read the docs to find out
what's possible. If I don't find a way to do something in the docs I don't necessarily assume it's undocumented. Why would I?
Should I? The question should be: why would undocumented features exist at all?

If it's too time-consuming to update the docs when a new version/changelog is published, perhaps publish the changelog as a forum

sticky post so we can hammer the topic until all questions have been answered. But that kind of goes back to my previous post where I said:

"Further, it seems reasonable that the more well-documented the components of F3 are, the fewer support requests there will be. That is, a
day spent updating the docs has to result in much more than a day being saved in support/forum time."

Frankly, the answer to the question: what would you like us to document? is, just whatever's in the changelog, thanks.

[ethanpil]

I agree with Nuwanda here... I often find myself trying to reverse engineer the code for new features to try and figure them out and the idea behind their use. If anything, perhaps making documentation+examples a required part of the release cycle might help.

[Nuwanda]

I came to F3 because of clean routing + added benefits including easy config and a really clean app/directory structure. It's allowed me to write code without worrying too much about whether  I was conforming to some huge pattern. I feel that I can write solid PHP without needing to learn a new language specific to the framework. It's why I rejected Laravel despite having an enormous amount of respect for what the Laravel team has achieved. Lumen, the Laravel micro offshoot, suffers from the same problems as its big brother: inherent buy-in.

I have a healthy fear of the extremes. I want a good entry point and a good exit: request and response. The F3 dev team seem to be focused on this and I applaud them. What happens in the middle should be up to me.

I like the idea of some more attention to routing convenience and perhaps that involves event triggers, etc. But I also like the idea of auth being a solid component of the framework since I also have healthy fear of implementing that in an insecure way especially as it relates to REST APIs. Now that may be considered a plugin responsibility but I'd like to see some support for that which I think fits in well with general routing concerns. I'd like to be able to think of F3 as being a framework that allows me to route securely as well as to route easily.

And, as always, I'd love to see a tutorial site--an offshoot of the core F3 effort, perhaps--that allows new users to be easily educated in the fundamentals. I say this because at some point a great framework---which F3 is--needs to be marketed by actual example.

And if I haven't been explicit enough in my praise in the past: thanks, thanks many times over, to the devs who are maintaining F3. You've provided me with great value which on my own I would never have been able to achieve.

I'm currently porting an app to F3 which I originally developed in Codeigniter, mainly for reasons of simplicity and maintainability.

http://woeid.rosselliot.co.nz/

 I should say that the reasons I originally used CI was the same reasons I started with F3: lightweight simplicity. But CI does a better job of documentation than F3 does despite F3 being the better platform. But I repeat myself.



On Friday, December 5, 2014 at 11:40:31 PM UTC+13, bcosca wrote:

2015 is round the corner. 3.3 has reached its peak. Don't worry, it won't be abandoned. 3.3.1 will be released before year-end. Now we're preparing the specs for the next incarnation of the framework you've come to know and love. In light of this announcement, we would like to engage everyone in a healthy discussion of what 4.0 should be like. Each feature request must have a justification. Code volunteers are also welcome and must be stated in the entry.

To start off, a code review is now an absolute necessity.

* I plan on cleaning up the hive's built-in variables. It's starting to be a mess and some variables add fat where there should be none.

* Event triggers/handlers should be unified. A standard mechanism must be developed. Those before... after... on... prefixes should be eliminated.

* PHP 5.4 will be the new minimum. 5.3 has already reached its end of life. No use beating a dead horse.

If you have ideas/suggestions about how the future F3 should behave, we're all ears. Bear in mind, the basic single-file functionality will still be there and will always conform to our non-fat philosophy. Everything else will be a plugin.

Remember, this should be a healthy discussion. Feature comparison with other frameworks is fine but should never be a basis for a feature request. A rationale should stand by itself.

Help make F3 better. Your active participation is truly welcome.

[David Rhoderick]

Some of you might notice that I have posted quite a few questions in the past week.  I want to start by thanking the developers of F3 and those who have helped me.  I am a programmer who has used many frameworks and tools such as CodeIgniter, jQuery, AngularJS, WordPress, Laravel, and Ruby on Rails.  I decided to give Fat-Free Framework a go with a number of projects because I heard many good things about it and F3 offers tons of functionality in a very small footprint.  Unfortunately, I have yet to experience the success of many of the members on this forum.  I still want to make it work but I am starting to think about abandoning F3.

I think you should fix the documentation to help diagnose some of the problems people could experience.  For example, I couldn't use the templating engine because I didn't know that I needed to create a 'tmp' folder and make editable by the php parser (chmod 777).  Additionally, I have tons of problems implementing simple commands such as $f3->set.  I am willing to accept the fact that maybe I am not as resourceful as other programmers but I have few issues with most of the frameworks listed above using their basic functions.  It's obvious that the framework works based on others' success, but it hasn't been easy for me to figure it out.  Perhaps adding some tutorials, more example code (it's pretty minimal and not always that applicable to real-life scenarios), and at least more information on how things work under the hood could help.  I also really think there should be a search built into the documentation pages.

I know this not really a behavioral issue with the framework but it appears that if all functions worked as they are documented, then I would need nothing else.  I am sort of handcuffed by having to ask the community for answers all of the time.  Thanks for taking the time to read my suggestion.

P.S.  If it were up to me, I would migrate the forum from Google Groups.  I find it really isn't good for programming issues (I have search for my name in order to see my posts, a simple feature on most other forum systems).  I know adding a forum to the website is extra work and you would lose or have to migrate what is up on Google Groups already, but since I'm giving my 2 cents, here's another.

[Richard Catto]

Right now, you are struggling with some really basic things, which you will because you are new to F3.

I adopted F3 and got routing, closures, getting and setting, views etc. to work without too much trouble. Not everything worked instantly, I made some mistakes, struggled to understand how some things worked, but managed to figure it out by persistence and googling for code examples.

You are right about one thing - the way to learn how to implement something is via code samples.

If F3 is lacking proper docs for something, you can help by blogging what to do. That will help the next poor sod to come along.

Once you get it, you will begin to appreciate its simplicity and ease of use.

[James Ringrose]

Hi David,

Don't give up! I went through the same sensations. I was very impressed and delighted with the concept. The developers are smart and understand the realities of today's programming pressures and on a cursory viewing the docs are comprehensive. 

As I noted in an earlier post, it's when you get stuck that you realize that there are very few examples and you can drift (or do what I did and reinvent the wheel) or hit the learning cliff.

What helped me most was a trip to GitHub and some of the apps and application shells that are out there. One of them literally solved most of my structural questions and I have not really looked back since.

I promise you, that the week you make an entire app, unit test it and bathe in the adoration of your users (OK a pipe dream then!) you will think it is worth it. :-)

James