Class -> File mapping – Need your feedback

Thursday, August 12th, 2010|Brainstorming, Version 4|by Romans

We have been discussing this internally but I’d like to hear your feedback on this matter.

It is Class to File mapping and use of upper / lower cases.

Page Naming and Mapping

page_* classes are being searched in page/*. Pages are typically in low-case, although toolkit does not impose it as a limitation. Sample:

http://…/foo/bar/baz.html

api->page = ‘foo_bar_baz’;

class: page_foo_bar_baz; Sometimes extends Page_EntityEditor.php

loads: page/foo/bar/baz.php

template: page/foo/bar/baz.html (page_foo_bar_baz.html in some implementations)

PLANS: In ATK4 we expect to leave same principles for pages.

Class Naming and Mapping

$this->add(‘Foo_Bar_Baz’);

Class files are being searched in lib/, amodules3/lib and possibly some other locations. They typically come with UcFirst.

class Foo_Bar_Baz .. defined in file lib/Foo/Bar/Baz.php

Plugins / addons

In AModules3 the concept of addons is very vaguely defined. It is just another location where to look for classes.

In ATK4, we expect to have prefixes for all classes and interfaces defined inside addon. For example:

billing_SomeClass

Class naming in Agile Toolkit 4

We want to introduce the mandatory prefixing of all classes. Here are some class examples:

  • api_Structured
  • api_generic
  • core_Controller
  • controller_DB
  • model_User
  • billing_model_PaymentMethod
  • billing_controller_Realex
  • core_Form
  • form_Login
  • form_User_Settings
  • core_AbstractObject
  • core_Exception
  • billing_Exception

In regards to pages:

Pages will always be loaded from page/ directory. You can add multiple directories to look into for pages with addResource()

page/ can inherit other classes, but those must be sitting inside lib/.

Bottomline: classes will always start with word in lowercase which identifies area of that class. Agile Toolkit 4 will provide api, form. Some plug-ins will bring in their own areas such as “billing”, those would have sub-areas “billing_model”, “billing_form” etc.

Second part of class will be in UcFirst and will be pretty much what we have at the moment in amodules3.

Works for me. What about you?

12 Comments

Camper
Posted August 12, 201012:24 pm

Sounds good, though I’d prefer to have exceptions in a separate dir. This would be logical.

romans
Posted August 13, 20106:01 am

Camper, I agree, but each area have it’s own dir too. So if i install plugin with “billing” it have it’s set of exceptions.

billing_Exception
billing_Exception_CardIncorrect
billing_Exception_GatewayProblem
billing_Exception_Validation

etc.. Were you thinking about something like this?

Camper
Posted August 13, 20109:04 am

Yes, exactly.
However path mapping is a developer’s business. I’d prefer to name them from the tree root:
exception_billing_IncorrectNumber
model_billing_Card
controller_billing_Transaction

You have few class types in your application (page, model, view, controller, exception,… – which are also common for all applications) and lots of entity types (billing, invoice, payment, quote, report, timesheet, article, contractor, and so on). I prefer to have most common on the top…

romans
Posted August 13, 201012:06 pm

Good point. I’m gotta think about this.

jancha
Posted August 15, 201010:27 am

+1

romans
Posted August 15, 20108:31 pm

BTW – can we use namespaces for this?

zak
Posted August 18, 20108:26 am

I also agree with camper. Indeed exceptions is good to be in a separate dir. About pages … I think its both logical and easy to find and create. I saw some projects with “page” dir moved one level up, but personally I think they are classes as all other and should be left in lib dir.

romans
Posted August 18, 20102:40 pm

zak -i don’t mind exceptions in other dir.

The question is – if we have a “package” something you unzip into /addons/ and it would come with it’s own exceptions. Like plugin in wordpress.

let’s say i added plugin called “crm”, how will exceptions look like?

Exception_crm or crm_Exception

Camper
Posted August 18, 20107:27 pm

When I supposed addons concept, I assumed it to be the kind of additional lib/ directory. I.e. as if you added more classes into lib/.
Package is rather application than an addon. It should contain complete functionality, so it usually comes with full structure including lib, page, template, etc.
We build applications upon entities (models, controllers and exceptions), so let entities go first.

romans
Posted August 18, 20108:20 pm

yes, we want to add many packages, which would be self-sufficient ie will come with pages, php, models controllers , exceptions.

But I’m not sure if those will simply live in a separate namespace or would contain prefix / infix in the class names.

maglev
Posted January 22, 20119:51 am

hi romans, i using ur toolkit, it was great, i can easily generate almost any kind of web element.

but there is something i can’t figure it out (no manual), its about downloading/generating PDF or CSV/XLS files.
how can i send header() properly to set for PDF/XLS. what api should i use.

regards, PHP newbie

romans
Posted January 22, 201111:09 am

Wow really? That’s exciting. Tell us more.

Regarding generation of PDF, that one is quite tough. You would need a software to generate PDF first. Check hose two out:
http://code.google.com/p/wkhtmltopdf/
http://www.princexml.com/

For XSL you would also need some external library, however CSV should be rather easy to download. Header you need would be

header(‘Content-disposition: attachment; filename=’.$filename);
also be sure to specify Content-type.