Surebert wiki - New pages [en]

Framework::sb Event Dispatcher - Advanced

2012-05-01T21:50:28Z

Paul: /* Additional Event Methods */

=Overview=
The [[Framework:Sb_Event_Dispatcher]] page covers basic event usage. Here are some more advanced options.

Framework:Sb Event Dispatcher

2012-05-01T21:13:37Z

Paul: /* Custom Events */

=Overview=
The event dispatcher is used to allow the programmer to add events which other code can listen for. It helps decouple the event dispatch code from the event listening code in a similar way to how javascript handles events. It also makes it easy for you to allow other programmers to make modules that react to your main application without directly touching your code.

=Creating the Dispatcher=
First create an event dispatcher. It is common practice to create one global event dispatcher for your app, however, you can make as many instances as you want.

<source lang="php">
App::$events = new sb_Event_Dispatcher();
</source>

=Adding Listeners=
Next go ahead and add some listeners. You can pass a function, a closure, a static class method reference, or a class instance method reference to a listener. See the following examples.

==function==
<source lang="php">
function crashed_car(sb_Event $e){
echo "Oh no the car crashed... the survivor count was ".$e->get_arg('survivor_count');
}
$id = App::$events->add_listener('car.crash', 'crashed_car');
</source>
==closure==
This one should look a lot like javascript
<source lang="php">
$id = App::$events->add_listener('car.crash', function(sb_Event $e){
echo "Oh no the car crashed... the survivor count was ".$e->get_arg('survivor_count');
});
</source>

==static method==
The nice thing about using static methods is that the listening class is not autoloaded until the event fires.
<source lang="php">
Class Car{
public static function crash(sb_Event $e){
echo "Oh no the car crashed... the survivor count was ".$e->get_arg('survivor_count');
}
}
$id = App::$events->add_listener('car.crash', Array('crashed_car', 'crash'));
</source>

==instance method==
<source lang="php">
Class Car{
public function crash(sb_Event $e){
echo "Oh no the car crashed... the survivor count was ".$e->get_arg('survivor_count');
}
}

$car = new Car();
$id = App::$events->add_listener('car.crash', Array($car, 'crash));
</source>

=Stopping Propagation=
Sometimes you may want to prevent the event from propagating up to other subscribed listeners. Make sure to only use this if you know what you are doing as other programmers whose listeners would fire after yours will not receive anything.
<source lang="php">
$id = App::$events->add_listener('car.crash', function(sb_Event $e){
echo "Oh no the car crashed";
$e->stop_propagation();
});
</source>

=Setting/Getting Event Arguments=
In the examples above, the listeners were getting argument past from the when dispatcher fired the event. Each listener can grab arguments and event edit or add to them.

In this example, the one listener reports the survivor count but then changes it for the next listener.
<source lang="php">
$id = App::$events->add_listener('car.crash', function(sb_Event $e){
echo "Oh no the car crashed... The survivor count was ".$e->get_arg('survivor_count');
$e->set_arg('survivor_count', 10);
});
</source>

While this type of usage may be very useful, it could also cause issues if you rely on the data matching the data originally past to the dispatcher. If you wish to prevent this type of behavior you can pass an instance of sb_Event_Unchangeable instead of sb_Event to your event dispatcher.

=Getting the Event Name=
You can get the current event name of the event being fired by calling the events get_name() method. This is especially useful if you are reusing a single function listeners for multiple events and want to know which one fired.

<source lang="php">
function generic_listener(sb_Event $e){
if($e->get_name() == 'car.crash'){
//do something
}
}
$id = App::$events->add_listener('car.crash', 'generic_listener');
</source>

=Getting the Event Subject=
Programmers can choose to pass a specific subject with the event by setting the second argument to the event __constructor. See the dispatching the event details below for more info. If the subject is set you can get it with $e->get_subject() in the listener.

<source lang="php">
$id = App::$events->add_listener('car.crash', function(sb_Event $e){
if($e->get_subject() instanceOf Car){
//do something
}
});
</source>

=Dispatching the Event=
When you dispatch the event, each listener is fired in the order that they were added and each listener receives the event passed as the second argument. You can pass data to the event constructor. It is then available in the listeners using the events ->get_arg() or ->get_args() method.

This returns the event object back in the state it is at after passing through each listener which can do things like change the args, etc.
<source lang="php">
$e = App::$events->dispatch('car.crash', new sb_Event(Array(
'survivor_count' => '3'
)));
</source>

Dispatching the event with a specific subject by passing the subject as the second argument to the event constructor. This is options. Once set, it can be referenced in the listener using $e->get_subject();
<source lang="php">

$car = new Car("AXT-2293");
$e = App::$events->dispatch('car.crash', new sb_Event(Array(
'survivor_count' => '3'
), $car));
</source>

You can also dispatch the event and allow partial matches so listeners for event_name "car" would receive "car.paint" and "car.crash" events and can decide what to do based on $e->get_name(); To do so set the third argument to dispatch "$allow_partial_match" to true.
<source lang="php">
App::$events->dispatch('car.crash', new sb_Event(), true);
App::$events->dispatch('car.paint', new sb_Event(), true);
</source>

This listener would fire for car.crash or car.paint
<source lang="php">
App::$events->add_listener('car', function(sb_Event $e){
if($e->get_name() == 'car.crash'){
//do something
}
});
</source>

=Removing a Listener=
Everytime you add a listener, its unique id for that event is returned. You can remove it by calling remove_listener and passing in the id.
<source lang="php">
$id = App::$events->add_listener('car.crash', function(sb_Event $e){
//do something
});

App::$events->remove_listener($id);
</source>

=Referencing the Dispatcher From The Listener=
You can always reference the dispatcher from the listener using the $e->get_dispatcher() method;
<source lang="php">
$id = App::$events->add_listener('car.crash', function(sb_Event $e){
var_dump($this->get_dispatcher()->logger);
});
</source>

=Custom Events=
You can easily extend the sb_Event to add custom events which can have their own easy access methods.
<source lang="php">
class CarCrashEvent extends sb_Event{
public function get_survivor_count(){
return 'The survivor count was '.$this->get_arg('survivor_count');
}
}
</source>

Then in the listener you can use the methods and properties of that extended Event class as needed.
<source lang="php">
$id = App::$events->add_listener('car.crash', function(CarCrashEvent $e){
echo $e->get_survivor_count();
});
</source>

=Logging/Debugging=
You can have your event dispatcher log all events that fire making it much easier to bug decoupled code. To do so simply set the logger for the event dispatcher. After that new logs will be created matching the events that fire. The logs are based on the event name and each capture includes whatever you normally include in the log headers e.g. username, ip, etc followed by information about where the listener that was fired is located and the data associated with the event being fired.

You can expect logging to reduce the efficiency of event handling. Therefore, it is best used for debugging in a dev environment.
<source lang="php">
App::$events->set_logger(App::$logger);
</source>

Example logs
<source lang="text">

2012/05/01 17:19:15 visco 14650 10.51.10.19 ~visco ~14650
{"listener":{"func":"hello($e)","file":"\/private\/views\/test\/page.view","line":13},"event":{"args":{"survivor_count":"3","func":{}},"stopped_propagation":0}}

2012/05/01 17:19:15 visco 14650 10.51.10.19 ~visco ~14650
{"listener":{"func":"Test::crash($e)","file":"\/private\/models\/Test.php","line":4},"event":{"args":{"survivor_count":"3","func":{}},"stopped_propagation":0}}

2012/05/01 17:19:15 visco 14650 10.51.10.19 ~visco ~14650
{"listener":{"func":"new Test2()->crash($e)","file":"\/private\/views\/test\/page.view","line":3},"event":{"args":{"survivor_count":"3","func":{}},"stopped_propagation":0}}

2012/05/01 17:19:15 visco 14650 10.51.10.19 ~visco ~14650
{"listener":{"func":"{closure}($e)","file":"\/private\/views\/test\/page.view","line":19},"event":{"args":{"survivor_count":"3","func":{}},"stopped_propagation":1}}
</source>

=Advanced Usage=
There are more advanced things you can do with events but the above code should get you started. See [[Framework::sb_Event_Dispatcher - Advanced]] for more info

Framework:sb Controller Command Line

2011-06-30T16:28:30Z

Paul: /* Methods */

=Overview=
Used to create command line script for your surebert application. While all views/controllers can be accessed via the command line, controllers that extended sb_Controller_Command_Line are Great for running cron jobs. It calculates the time and memory used to run the script and logs to both screen and log file.

It also prevents execution from anywhere but the command line. E.g. will not serve over http. You can change that by overriding the contructor.

=Methods=
==log($message, $type='MESSAGE')==
Logs the message to screen and log file. Type is displayed at beginning of log message. If type is set to 'ERROR' then the message counts as an error in the total errors count.

==set_memory_limit($message, $memory_in_MB=200)==
Sets the memory limit for the script

==set_max_execution_time($time_in_seconds=3600)==
Sets the max execution time in seconds

=Usage=
Create a new controller which extends sb_Controller_Command_Line. Create a method with @servable true
<source lang="php">
class CronController extends sb_Controller_Command_Line {

/**
* Does something
* @servable true
*/
public function do_something() {
$this->log('Did something');
$this->log('Found Error', 'ERROR');
return true;
}
}
</source>

Visit from the command line
<source lang="php">
php gateway.php --request=/cron/do_something
</source>

Should report back something like. Obviously, memory and time required depend on script, php configuration, and hardware.
<source lang="text">
MESSAGE: 2011/06/30 12:28:02 - Begin Process CronController
MESSAGE: Did something
ERROR: Found Error
MESSAGE: PEAK MEMORY USAGE: 1 MB
MESSAGE: TOTAL ERRORS: 1
MESSAGE: TOTAL TIME REQUIRED: 6.09ms
MESSAGE: 2011/06/30 12:28:02 - End Log
</source>

It would also log this same data to the file /private/logs/CronController/2011_06_30.log - replacing date with current date

Repository

2011-06-11T01:22:43Z

Paul: Created page with "=Surebert Framework= Repository: http://surebert.com/svn/framework Logs: <source lang="bash"> svn log -v http://surebert.com/svn/framework/ </source> =Surebert Toolkit= Reposit..."

=Surebert Framework=
Repository: http://surebert.com/svn/framework

Logs:
<source lang="bash">
svn log -v http://surebert.com/svn/framework/
</source>

=Surebert Toolkit=
Repository: http://surebert.com/svn/toolkit

Logs:
<source lang="bash">
svn log -v http://surebert.com/svn/toolkit/
</source>

=Surebert Application=
Repository: http://surebert.com/svn/application

Logs:
<source lang="bash">
svn log -v http://surebert.com/svn/application/
</source>

MIT license

2011-06-11T01:17:33Z

Paul: Created page with "Copyright (c) 2011 Paul Visco Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), ..."

Copyright (c) 2011 Paul Visco

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Framework:.htaccess

2011-03-31T05:25:17Z

Paul: Created page with "The .htaccess file looks for files in the public folder and if there is no match it redirects the request to the gateway in order to facilitate the request. If using another ser..."

The .htaccess file looks for files in the public folder and if there is no match it redirects the request to the gateway in order to facilitate the request.

If using another server besides apache you would have to emulate this behavior. Most servers can do this. See [[Serving_with_nginx]] for using with nginx.

Framework:sb Controller REST

2011-03-31T03:34:27Z

Paul: /* Explaination */

=sb_Controller_REST=
sb_Controller_REST is a custom controller you can extend which handles the full spectrum of HTTP request methods and fires the corresponding controller method that matches the HTTP request method.

=Example=
<source lang="php">
<?php

class BlogController extends sb_Controller_REST{

public function __construct(){

}

/**
* Accepts GET requests
* @return string
* @servable true
*/
public function get(){
return 'get: '.json_encode($this->request);
}

/**
* Accepts PUT requests
* @return string
* @servable true
*/
public function put(){
return 'put: '.json_encode($this->request->data);
}

/**
* Accepts POST requests
* @return string
* @servable true
*/
public function post(){
return 'post: '.json_encode($this->request->post);
}

/**
* Accepts DELETE requests
* @return string
* @servable true
*/
public function delete(){
return 'delete: '.json_encode($this->request->data);
}
}
?>
</source>

=Explaination=
Using the example BlogControler above, a visit to yoursite.com/blog/ would fire the controller's get method because it is a get request. You could then query the $this->request for more info about the request.

You could also request via ajax using the toolkit
<source lang="javascript">
new sb.ajax({
url : '/blog/4',
onResponse : function(r){
//do something
}
}).fetch();

//or the shortcut
sb.get('/blog/4', function(){//do something});
</source>

Using the surebert toolkit you could make a PUT or DELETE request via sb.ajax. There is currently no shortcut call for PUT or DELETE requests, you must use a full sb.ajax request
<source lang="javascript">
new sb.ajax({
url : '/blog',
method : 'PUT',
data : {title : 'Programming', entry : 'A fun activity'},
onResponse : function(r){
//do something
}
}).fetch();

new sb.ajax({
url : '/blog/4',
method : 'DELETE',
onResponse : function(r){
//do something
}
}).fetch();
</source>

Framework:sb Controller JSON RPC2

2011-03-31T03:31:14Z

Paul: Created page with "=Creating a JSON RPC2 Server Using sb_Controller_JSON_RPC2= Creatng a JSON RPC2 server with the surebert framework is easy. Simple extend the sb_Controller_JSON_RPC2_Server clas..."

=Creating a JSON RPC2 Server Using sb_Controller_JSON_RPC2=
Creatng a JSON RPC2 server with the surebert framework is easy. Simple extend the sb_Controller_JSON_RPC2_Server class with your own. This will allow you to select methods of you app which can then be called from another application.

<source lang="php">
class CalculatorController extends sb_Controller_JSON_RPC2_Server{

/**
* Adds two numbers together
* @param integer $x
* @param integer $y
* @return integer
* @servable true
*/
public function add($x, $y){
return $x+$y;
}

}
</source>

You could then call it with a client as such
<source lang="php">
$client = new sb_JSON_RPC2_Client('http://yoursite.com/calculator');
$result = $client->add(1,2);
//$result would equal 3
</source>

==HTTP Status Headers==
By default a sb_JSON_RPC2_Server serves the appropriate HTTP status header with the response, see the table above. If you would like to suppress the headers from being sent set the controllers's surpress_http_status to true; You may have to do this for certain clients that won't read the message body if a status other than 200 is returned, e.g. 400, 404, 500

<source lang="php">
public $suppress_http_status = true;
</source>

==GZ Compression==
A sb_JSON_RPC2_Server instance can serve the json data gzipped. This is an excellent way to save bandwith for larger data transfers. You can set the gz compression level by passing a level 0-9 to the $server->use_gz_encoding(3); method

<source lang="php">
public $use_gz_encoding(6);
</source>

==Use Encryption==

sb_JSON_RPC2_Client and Server can encrypt communication using mcrypt. In order for it to work, both client and server must use the same key.
javascript code
<source lang="php">
//use encryption for transfer, pass the same key the server is using
public $use_encryption($key);
</source>

Framework:Controllers

2011-03-31T03:29:14Z

Paul: moved Framework:Controllers to Application:Controllers

=Framework:Controllers Overview=
The controllers basically intercept all requests coming in from the Gateway and respond back with the appropriate data.

The controller being used to respond to the request is also the $this of any .view file that is rendered. The behind the scenes controller is called Gateway. It passes off control to the default Controller which is called IndexController and is found in the /private/controllers directory.

By default IndexController extends [[Framework:sb_Controller_HTML5|sb_Controller_HTML5]] which in turn extends sb_Contoller

=sb_Controller Properties=
==$request==
The $this->request property of a sb_Controller is an instance of sb_Request modeling the request that was given to the controller. You can access this from any method of a controller other than __construct() at which time you can only refer to Gateway::$request.

=sb_Controller Methods=
==__construct==
Called when the controller is instantiated. The $this->request is not available at this point. See on_before_render() below if you need that.

==on_before_render()==
Similar to __construct(), on_before_render() is called before any methods are called to render a response. Unlike the constructor you do have access to the $this->request property at this point. You can use on_before_render() to do things like check for GET query variables, cookies, admin status, etc. If you ever return false from on_before_render, all executation is stopped at that point. This is a great method to use for common security checks that would need to be called for each servable method.

==render_view('/admin/login');==
This loads .view template e.g. /views/admin/login.view and returns the resulting contents. The $this of the .view template is the Controller that called $this->render_view('/admin/login); For rendering a totally different request or overriding arguments of the Gateway::$request see [[Framework:Gateway#Gateway::render_request.28.29]]

==not_found()==
This is fired when no there is no matching method or .view to handle the request. The default is a 404 error page. You can always redefine this. You have access to the full request in this method if you want to do anything custom based on the request.c

==__destruct==
Called when the Controller is destructed. You could use this to disconnect from resources, log time/memory, etc

==render()==
Renders the data based on the type of controller. You do not usually call the method, however, you can redefine it to create different types of controllers. The default action is to look for a method name that matches the request and if it is marked as @servable to return the result to the output buffer. This method does not need to be called manually as it is called by the Gateway. You could always redefine the render method for custom controllers. See [[Framework:sb_Controller_REST]], [[Framework:sb_Controller_JSON_RPC2]] as examples of controllers who's render method changes the behavior of the controller.

=Example=
The default render method of sb_Controller works this way.
It looks for a method that matches the request and is marked as @servable e.g. /car/drive would call the CarControllers drive method. See example below.
<source lang="php">
<?php
class CarController extends sb_Controller{

/**
* Test method to demonstrate servable methods
* @return string
* @servable true
*/
public function drive(){
return 'is driving';
}

/**
* fires when no servable method is found
*/
public function not_found(){
//do something, then throw 404
parent::not_found();
}
}
?>
</source>

=Input and Method Properties=
Each public method has additional properties which can be defined in the phpdocs of the methods themselves. These properties include:

*'''@servable''' (true | false) Determines if the method is accessible via URL. True by default
*'''@input_as_array''' (true | false) Determines if arguments are passed in order or as a named hash like GET and POST
*'''@http_method''' (get | post) Determines which type of data is passed to the method POST or GET

==input_as_array==
For the following two examples we are assuming the url is /car/paint?color=ACACAC&detail=1

A method that has input_as_array true would receive input like like

<source lang="php">
/**
* @servable true
* @http_method get
* @input_as_array true
*/
public function some_method($input){
//$input['color'] = 'ACACAC';
//$input['detail'] = '1';
}

</source>

While a method that has @input_as_array set to false would receive input values in the order they came with the keys. In this case the order of the arguments is very important and should only be used when you can be sure of the order.

<source lang="php">
/**
* @servable true
* @http_method get
* @input_as_array false
*/
public function some_method($color, $detail){
//$color = 'ACACAC';
//$detail = '1';
}

</source>