Some considerations on refactoring the eZ Publish API

Friday 23 April 2010 1:55:32 pm

List of current eZ Publish APIs:

1. template language API
 . template operators
 . template functions
 . template fetch  functions
 . objects

- template variables are not the same between  node templates and module templates (persistent_variable,  view_parameters)
- no documentation of variables available in every  template
- some simple template operators miss (str_replace)
- some template operators are named differently from their php counterpart
- the variable scoping system is borderline blackmagic / it makes it  difficult to pass variables up the include() chain
+ well documented

2. module views
 . positional params
 . named params
 . single/multiple actions
 . POST vars

- extremely poorly documented
- the view template is hardcoded into the view
- redirects are  hardcoded into the view (views are not atomic)

3. php code
- misses a lot of "private" definitions on object members
- should be  documented in phpdoc style for current toolchains/ides
- misses some  architecture doc documenting the layering
- still a few global  variables and functions here and there (not 100% oop)

IDEAS:

+  before/besides adding YOMA (yet one more api), improve existing ones

+  principle of discoverability: document better existing ones
 . add  (optional) declaration of parameter types for views in module.php; it  allows automatic type coercion (safety!), introspection (wsdl!)
 . add definition of all used POST/GET vars for views
 . add links to  docs on ez.no site in the code; in the error messages; in the interface
 . an introspection view can be used in the backoffice to list all  installed modules, views, fetch functions, including code from  extensions
 . it should be doable to do the same with template  functions/operators
 . add a 'description' member in definition of  template operators, fetch functions (could be doable via an explicit  member in the definition struct or via phpdoc parsing)

+ principle of  least resistance: make APIs at the different levels identical or at  least as similar as possible
 . the same operation executed by a view  should be available via ws and via php
 . template operators and  fetch functions should be available via php (ok for objects even though  this is often overlooked, ok for fetch functions with some limitations,  not for operators?)
 . make the module object available to the view  templates

Principal Consultant International Business
Member of the Community Project Board

Sunday 25 April 2010 11:23:58 pm

Some introspection capabilities have been added to extension ggsysinfo in release 0.2: http://projects.ez.no/ggsysinfo

Screenshots:

http://projects.ez.no/ggsysinfo/gallery/admin_interface_screenshots/list_of_available_fetch_functions

http://projects.ez.no/ggsysinfo/gallery/admin_interface_screenshots/list_of_available_views

Principal Consultant International Business
Member of the Community Project Board

Thursday 27 May 2010 2:34:18 am

One more thing that would help introspection is better tagging of php classes methods (I think this is called "annotation" ).

In short: an example of a currently much needed information is "who does permission checking ?"

Afaik:

• index.php checks access perms for current user to module/view if the corresponding perm has no limitation
• the view php code needs to do access checking on its own if the corresponding perm has some limitation
• other bits of code do access checking on their own (eg. the template fetch functions do some, but not all are created equal, eg. checking perms on related object is not always done in a way that is expected)

See issue http://issues.ez.no/IssueView.php?Id=16862 for the feat.request.

Principal Consultant International Business
Member of the Community Project Board