Modernize OOP-PSR-0 new developer APIs

[GoogleCodeExporter]

The plan would be to namespace and move the APIs to vendors. New design would 
include using shared blueprints and abstract base classes, setters and getters.

This would include the new 4.6 APIs such as:

* Pref
* User
* Template [Form, Page, Style]
* More as thing go on.

Planned methods would include the once already bundled in the current API base:

public function create();
public function update();
public function exists();
public function rename($name);
public function remove();

Getter methods would include:

public function item();
public function items();
public function __toString();

Setter and getter value methods depend on the API, used fields are obviously 
different. For instance Form would include:

public function __construct($name);
public function name($name);
public function type($type);
public function code($code);

Also some supporting functions (validation) would be included:

public function is_valid_name();
public function is_valid_type();
public function types();
public function essential();

The end-developer the usage would be straightforward. Small example with forms:

$form = Textpattern_Template_Form();
$form->name('formName');
$form->type('misc');
$form->code('Abc.');
$form->create();

Would set name to 'formName', type to 'misc' and code/markup to 'Abc.' after 
which it runs 'create' command to the created instance.

Original issue reported on code.google.com by jukka.m.svahn on 20 Dec 2012 at 1:42

[GoogleCodeExporter]

We'd probably better add a few methods to create a "Textpattern_Entity" from an 
array or from the database, like load($primary_key) or 
find($complex_array_of_conditions_or_immediate_sql_clause). 

I.e. in the end we would build our own ORM. 

We could try to use existing wheels instead. Propel or Doctrine are probably a 
bit more than we need. RedBeanPHP comes to mind: http://redbeanphp.com/manual/ 

Most of the relevant ORMs require PHP 5.3 nowadays.

PHP 5.3+ runs on about 34% of WordPress.org sites: 
http://wordpress.org/about/stats/ by the end of 2012. We can expect to meet 
similar hosting environments for Textpattern. 

Can we afford to require PHP 5.3+ for Textpattern 4.6 and discuss the adoption 
of a third-party ORM?

Original comment by r.wetzlmayr on 20 Dec 2012 at 5:46

[GoogleCodeExporter]

I do not like one argument rules them all approaches. From the three you 
mentioned I can only consider Doctrine. It meets PSR-0 and quality standards I 
have. Plus it uses composer which we can use to build the project then too.

One of the problems with any of those is complexity tho, and for instance I do 
not know any of those. If no one of us is fluent in any, we are likely to do 
mistakes.

I personally do not mind if we require PHP 5.3. If we do pick one I would also 
encourage that we adopt composer too, and could consider use of git (and 
branching/tagging).

Original comment by jukka.m.svahn on 20 Dec 2012 at 6:40

[GoogleCodeExporter]

For the record, current Dreamhost shared hosting still runs on PHP version: 
5.2.17.

Original comment by ph.witte...@gmail.com on 20 Dec 2012 at 6:47

[GoogleCodeExporter]

If we do use ORM, it shouldn't be that end-developers are supposed to access 
misc ORM and we wipe our hands clean.

There should be an actual interface designed for each content type we provide 
that does all the needed validation, and what have, for the end-developer. 
Otherwise it's the same thing as doing what we do now, but with different 
covers.

Preferable the provided mapping layer would be extendable and used standard PHP 
practices instead of doing it's own stuff and having factories and generic 
set_abc get_abc methods everywhere.

The stuff I had/have written for that API stuff current consists of classes 
hierarchy of:

interface iTemplate
    abstract class Base
        class Page extends Base implements iTemplate
            class Values
        class Form extends Base implements iTemplate
            class Values
        class Style extends Base implements iTemplate
            class Values

Original comment by jukka.m.svahn on 20 Dec 2012 at 7:13

[GoogleCodeExporter]

Jukka, maybe I misunderstand this issue's scope so I'll try to reiterate a bit:

The methods you mentioned in the initial comment ("create(), update(), 
exists(), rename(), remove()") made me think you were intending to build a CRUD 
engine for any entities we store in the database. 

So I hinted that we'd some kind of "find()" to have a method for object 
retrieval (i.e. the "R" in CRUD).

The "getters, setters, validators" part looks like you also want to build a 
data model for Textpattern entities.

Which begs the question: Do we roll our own DB abstraction layer over PDO with 
an object hierarchy for our data models on top of it, or use an established ORM 
component as a base for these data models?

> If we do use ORM, it shouldn't be that end-developers are supposed to access 
misc ORM and we wipe our hands clean.

Agreed. A proper data model should sit on top of the DB abstraction, no matter 
whether we build our own or embed a third-party ORM.

> The stuff I had/have written for that API stuff current consists of classes 
hierarchy of:

> interface iTemplate
>    abstract class Base
>        class Page extends Base implements iTemplate

Apparently you have already built your own data model/DB-abstraction for a part 
of Textpattern's model.

Is this hierarchy useable for any entity (articles, users, links, plugins, 
user-defined entities)? What does "class Base" provide?

Original comment by r.wetzlmayr on 20 Dec 2012 at 11:38

[GoogleCodeExporter]

> Apparently you have already built your own data model/DB-abstraction for a 
part of Textpattern's model.

Yes, it providers abstraction, doing validation (when setting a value) and DB 
interaction in-house. It bit mixes both.

The "Base" class currently is reserved one for each specific content-type. For 
instance templates (css, page, forms) share one in common. It providers shared 
functionality as validation methods, constructor and initializes Values (data 
storage). This base class is then extended.

iTemplate is the blueprint defining all methods an API needs to provide to the 
end-developer. It does what interfaces do.

Values is a pseudo-type data storage. It collects all the values passed down 
from the setter methods (name, type etc). Values is then used to return those 
values which then are constructed into queries. This all is done directly in 
rename() and create() (etc) methods (there is nothing for that in Textpattern).

The Form, Style and Page classes are the actual resulting classes, exposing all 
the methods. They all host most of the actual code and run the database queries.

> Is this hierarchy useable for any entity (articles, users, links, plugins, 
user-defined entities)?

As a structure and blueprint partly is, the 100-300 lines of code there is for 
each class isn't. It's not a generic ORM or abstraction layer. It would consume 
those.

Original comment by jukka.m.svahn on 20 Dec 2012 at 12:21