Creating an new user-project for the framework ==============================================
Creating a user project which the "Framework" component tools can interact
with should consist of a single configuration file in a user-project root
directory.
It should have variables :
* persistent objects dir(s) : where objects usable with
ezcPersistentSession should be stored (if any),
* controllers dir(s) : where "framework"-compatible controllers should
be stored (if any).
And optionnaly :
* controller generator dir(s) : where user-defined controller generators
should be stored. This can be a workstation-wide shared directory.
* test dir(s) : where user will work his tests.
* restricted controllers list.
CLI "Framework" tools
=====================
framework.php [options] command [command-arguments]
framework.php [options] addcontroller name [controller-generator-arguments]
Options :
-p --path Path to user project, default : current directory.
Commands :
newproject Creates a directory with stuff to begin working the user-app.
listcontrollers Lists the controllers proposed by the "Framework" component.
addcontroller Uses the controller generator identified by argument <name>
to add a controller to user's project directory.
ClientQuery object
==================
The "Framework" should provide a ClientQuery object, implementing singleton.
It should contain all the client query informations and be a holder for any
global variable for example : the current user object.
Controllers should use it.
Controllers
===========
The "Framework" controllers should take the client request in account and :
* run the appropriate actions if client has the permission,
* select a response body template,
* select template variables.
This approach lets freedom on it's usage, for example :
* usage of ezcTemplate,
* usage with the "Framework" provided "response-builder",
* usage of several controllers.
Controllers can rely on several templates which should be declared as class
constants : their docblocks should not ommit the description of the cases which
would require this value as well the variable list that will be supplied.
It's better to prefix the template constant names with TPL_ or something
like that.
Example :
<?php
class controller
{
/**
* When everything is fine.
* Variables :
* - $name : visitor name (string).
*
* @var string Template name.
*/
const TPL_OK = 'success.tpl';
}
?>
Controllers should be developped with the "test-first" "Framework" component
tools (more later).
Controller generators
=====================
Controller generators should inherit from abstract the abstract controller
generator class.
Controller generators should :
* take in account the generator arguments if any,
* do pre-installation checks and abord if it fails,
* do the project's modification if any,
* build a controller's code,
* build the controller's unit-test code,
* return the controller's post-install help.
It makes it easy to make controller generators and makes them more testable.
(The "Framework" TextUI tool should take care of saving the code to files and
display post-install instructions).
The "Framework" component should provide a few basic controllers :
* persistent object CRUD, in two versions.
* modern user-management controllers.
The persistent object CRUD :
It's rather hard and a lot of code to make one CRUD capable of handling all
relation
types with style : the "Framework" component should provide one (maybe in
stage2).
It should also be able to generate per-object CRUD controllers.
The modern user-management controller :
In addition of any controller generator minimal features, it should :
* backup user's database structure definition,
* install the database tables in the user's database definition,
* install the persistent objects.
The response builder
====================
The "Framework" component should provide a simple response builder which usage
would rely on a user-defined main template and ezcTemplate.
It should provide methods to :
* add/remove controllers,
* run all controllers,
* build the response with each controller's template and variables,
* return the response.
The main template can use the each controller's built body response as a
variable.
Test-first environement
=======================
The "Framework" component should provide a true test-first efficient
environment.
The "Framework" component should provide a TextUI and test-cases.
Both will inherit from UnitTest's. I know that UnitTest runner build the
test-suites relying on a release:package pair, this should be overloaded
without problems since it hasn't any private method nor variable.
Usage: $ UnitTest/src/runtests.php [--help] [-p `pwd`] [-D <string>] [-c
<string>] [-x <string>] [-v] [[--] <args>]
eZ Components "Framework" Test Runner
--help Show this help
-p / --path Path to user's project directory or current directory.
(stripped all the good options that should remain)
It should be able to figure test class names in the user-project's test dir(s),
generate the test-suite, run the test-suite.
It's test case should provide methods to set up arbitary database states and
ClientQuery singleton states, mocks and shunts.
Test-case methods for any user-project :
* setClientQuery( string variable name, mixed value ) : this would set an
arbitary value to a variable of the singleton ClientQuery object used by
controller.
* installPersistentObjects() : installs the database structure if required,
installs
persistent objects fixtures. Should be cleaned at the end of the test method.
* installDb() : install the database structure if required.
* installPersistentObjectFixture( string persistent object's class name ) :
installs
fixture in the database with default values.
(Note that i am aware that it does not respect the coding standarts but i
haven't though of better for the moment.)
* makePersistentObjectFixture( string persistent object's class name ) :
returns an
instance of a persistent object with default values.
Test-case methods for the moder user-management controller :
* setVisitor( modern user-management controller user object )
Controller generators to develop
================================
The modern user management controller has objects :
* user,
* group,
* permission.
Relations : user-group and group-permission are many-to-many (5 tables).
The controller should have a few configuration values :
* redirect_on_login_success,
* redirect_on_login_failure,
* redirect_on_registration_success,
* redirect_on_registration_failure,
Configuration variables matching redirect_on_* default values are 'off', which
will
make it to continue with it's template constant and variables. Other possible
values
are URLs.
Controllers template cases :
TPL_LOGIN_SUCCESS and TPL_REGISTRATION_SUCCESS and TPL_DEFAULT with variables :
user and group(s) object(s).
TPL_LOGIN_FAILURE and TPL_REGISTRATION_FAILURE with variables : posted id,
error message.
By default, the permission object is composed by a string key and a boolean
value and should be operationnal.
The ClientQuery object stores the current visitor's user, groups and
permissions objects as controller-custom-variables.
James Pic wrote:
> eZ component: Framework, Requirements
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
>
> Introduction
> ============
>
> eZ Components were developed in the spirit of letting a maximum of freedom
> to the user. A new component restricting the freedom of the developer might be
> interesting if it can make developpement of applications even faster.
> Terms of "feedom restriction" were chosen to oppose the existing components to
> the one that will be described : it should reduce the quantity of strategical
> choices that the programer has to make in order to save time, but still be
> able to solve any kind of problem.
>
> Frameworks aim to help the user to develop an application faster and
> sometimes, with more reliability.
> There are many kinds of frameworks out there on internet. But where are the
> frameworks proposing a real test-first environement ?
> The component "framework" should provide ready-to-use test-cases to allow
> really fast and reliable test-first developement.
>
> It's possible to make the developpement faster by :
> * less thinking of deciding the structure of the application.
> * generating applicative code.
>
> It's possible to make the maintenances and updates easier by :
> * providing a test-first complete environement.
>
>
> Description
> ===========
>
> The framework component aims to reduce developement and maintenance time by
> providing :
> * code generators,
> * a common web-application design, able to solve any problem,
> * a complete test-first high-level environment.
>
> Requirements
> ============
>
> It should provide :
> * a basic project directory generator.
> * test-runner(s) and case(s) to make faster test-first at the framework-user
> level :
> * provide a dbunit-like system,
> * provide methods to set arbitary data to eZC-level objects,
> * provide eZC-level object shunts.
> * new persistent object generator : documented and using overloading methods
> to throw exceptions when a property is set with a value that isn't compatible
> with the database column.
> * a testcase extension generator able to :
> * use the dbunit-like system to make the pesistent object's test methods,
> allowing the framework user to start hacking the generated code as soon as
> generated.
> * make controllers or action testcase skeletons.
> * provide controllers and/or a controllers generator for :
> * user authentication and permissions management,
> * persistent object CRUD.
> * generators should provide test-cases to allow the user to start hacking the
> generated code.
>
> Design goals
> ============
>
> Generators should always generate tests for the generated code.
> It should be easy to add generators in later releases.
> The framework should be able to solve any web-application common problem.
>
> The ez-test-first concept :
> Presentation of the concept/procedure to create a simple action :
> * extend the action TestCase and make the test of the first action.
> * use the runner to run the test, which should fail since the action hasn't
> been programmed.
> * program the action until the test passes.
>
> If the first action is : update the persistent object using the query's post
> variables if the user is authenticated. The tests could look like :
> class UpdateWidgetWithRegularPostDataTest extends ezcFrameworkActionTestCase
> {
> public function setUp()
> {
> // parent::setUp();
>
> /*
> * All the code parent to the action should be executed for
> * the revelency of the tests.
> */
> $this->setClientRequest(
> array(
> 'id' => 1,
> 'colour' => 'blue'
> );
> );
>
> /*
> * Hard-set the action, for all the code executed before the
> * action.
> */
> $this->setAction('updateWidget');
>
> /*
> * This tests require the Widget's table(s) to be set up in a
> * temporary database.
> */
> $this->dbunit->prepareTemporaryDatabaseWithPersistentObject(
> 'Widget'
> );
>
> /*
> * This test requires one Widget fixture in the database.
> */
> $this->dbunit->addPersistentObjectFixture('Widget');
> }
> /*
> * The action should not be executed by unauthenticated users.
> */
> public function testUserNotAuthentified()
> {
> /*
> * Hard set the action requester to a guest-user
> */
> $this->setVisitor($this->guest);
>
> try
> {
> $this->runAction();
> }
> catch ( ezcFrameworkNoPriviledgesException $e )
> {
> return true;
> }
>
> // no exception was catched.
> $this->fail();
> }
>
> /*
> * The action should update the database-fixture
> */
> public function testObjectUpdatedCorrectly()
> {
> /*
> * Hard set the action requester to an authorized user
> */
> $this->setVisitor($this->authorized);
>
> $this->runAction();
>
> // assert that the action successed
> $this->assertTemplateVars(
> array(
> 'message' => 'success',
> ),
> 'Action should be successfull since the request is
> fine and the user is authorized'
> );
>
> $this->assertEquals(
> $this->dbunit->Widgets( 1 )->colour,
> 'blue',
> 'Widget database fixture should be updated according
> to the query'
> );
> }
>
> // etc ....
> }
> The framework-user should then develop his action until his test-case passes.
> This was just an example and should be considered as-it.
> The ez-test-first solution provided by the framework should allow the
> framework-user to work in a reliable and complete environement, allowing to
> reduce HTTP-client side testing as much as possible.
>
> The framework component should provide a simple controller system, making it
> easy to develop actions (as controller methods or other classes) using common
> modern websites features : user management, HTTP query management ...
>
> NOTE: Maybe the generators, the framework and the test-first-environement
> could be
> used individually. Allowing the user to generate a CRUD controller or uthe
> test-cases for faster and easier test-first.
>
> --
> Components mailing list
> [email protected]
> http://lists.ez.no/mailman/listinfo/components
--
James Pic
GPG Key : 13185F50x8 / AEE2 CC15 8FF8 339C 23AC 5A91 491B 1638 1318 5F58
Downloadable on http://jamespic.com/pubkey.asc
pgpVW44SDTKD2.pgp
Description: PGP signature
-- Components mailing list [email protected] http://lists.ez.no/mailman/listinfo/components
