simple-mvc Documentation

Release 0.1.0

Walter Dal Mut

Nov 18, 2017

 Contents

1 Getting Started 3
1.1 Urls with dashes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Bootstrap resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Autoloader 5
2.1 Classmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 PSR-0 Autoloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 Controllers 7
3.1 Init hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2 Next action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.3 Redirects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.4 Interact with layout and views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.5 Change the layout on the fly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.6 Using headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.7 Change View Renderer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 Views 11
4.1 Layout support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2 View Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.3 Escapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.4 Partials view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.5 Multiple view scripts paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5 Events 15
5.1 Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2 Create new events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

6 Pull Driven Requests 17

6.1 simple-mvc implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

7 Examples of usage 19
7.1 Execute with bootstrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
7.2 Controller Forward . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

8 Indices and tables 21

i
ii
 simple-mvc Documentation, Release 0.1.0

Contents:

Contents 1
simple-mvc Documentation, Release 0.1.0

2 Contents
 CHAPTER 1

Getting Started

The goal is realize a web application in few steps.

See scripts into example for a real example. The base is create a public folder where your web server dispatch the
index.php.
Create out from this folder the controllers path or whatever you want (eg. ctrs).:

- controllers
- IndexController.php
- public
- .htaccess
- index.php

In practice you are ready. See the .htaccess:

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} -s [OR]
RewriteCond %{REQUEST_FILENAME} -l [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^.*$ - [NC,L]
RewriteRule ^.*$ index.php [NC,L]

The index.php is the main app entry point

1 <?php
2 set_include_path(realpath('/path/to/src'));
3

4 require_once 'Loader.php';
5 Loader::register();
6

7 $app = new Application();

8 $app->setControllerPath(__DIR__ . '/../controllers');
9 $app->run();

The controller IndexController.php file should be like this

3
 simple-mvc Documentation, Release 0.1.0

1 <?php
2 class IndexController extends Controller
3 {
4 public function indexAction()
5 {
6 echo "hello";
7 }
8 }

See “[view](views.md)” doc for enable views supports.

1.1 Urls with dashes

If you use a dash into an URL the framework creates the camel case representation with different strategies if it is an
action or a controller.:

/the-controller-name/the-action-name

Will be

1 // the-controller-name => TheControllerName

2 class TheControllerName extends Controller
3 {
4 public function theActionNameAction()
5 {
6 //the-action-name => theActionName
7 }
8 }

1.2 Bootstrap resources

You can bootstrap resources:

1 <?php
2 $app = new Application();
3 $app->bootstrap('my-resource', function() {
4 return new MyObject();
5 });

The bootstrap do not executes all hooks (lazy-loading of resources) but execute it ones only if your application needs
it.

1 <?php
2 // Into a controller
3 $resource = $this->getResource("my-resource");
4 $another = $this->getResource("my-resource");
5

6 // IT IS TRUE!
7 var_dump($resource === $another);

4 Chapter 1. Getting Started

 CHAPTER 2

Autoloader

simple-mvc provides two strategies for loading classes for itself and only one strategy for autoload your classes.

2.1 Classmap

The classmap loads only simple-mvc classes. If you have a self-designed autoloader you have to use this strategy for
reduce conflicts during the autoloading process.

1 <?php
2 require_once '/path/to/simple/Loader.php';
3

4 // Load all simple-mvc classes

5 Loader::classmap();

2.2 PSR-0 Autoloader

If you want to use the PSR-0 autoloader you have to register the autoloader.

1 <?php
2 require_once '/path/to/simple/Loader.php';
3

4 set_include_path(
5 implode(
6 PATH_SEPARATOR,
7 array(
8 '/path/to/project',
9 get_include_path()
10 )
11 )
12 );
13

5
 simple-mvc Documentation, Release 0.1.0

14 // Load all simple-mvc classes

15 Loader::register();

The autoloader loads automatically namespaced classes and prefixed.

Prefix example:

1 <php
2

3 // Prefix -> ClassName.php

4 class Prefix_ClassName
5 {
6

7 }

Namespace example:

1 <?php
2 namespace Ns;
3

4 // Ns -> ClassName.php
5 class ClassName
6 {
7

8 }

6 Chapter 2. Autoloader
 CHAPTER 3

Controllers

The controller section

3.1 Init hook

Before any action dispatch the framework executes the init() method.

1 <?php
2 class IndexController extends Controller
3 {
4 public function init()
5 {
6 // The init hook
7 }
8 }

Using the object inheritance could be a good choice for this hook.

1 <?php
2 abstract class BaseController extends Controller
3 {
4 public function init()
5 {
6 // Reusable code
7 }
8 }

3.2 Next action

The next action goes forward to the next action appending the next view.

7
 simple-mvc Documentation, Release 0.1.0

1 <?php
2 class IndexController extends Controller
3 {
4 public function indexAction()
5 {
6 $this->view->hello = "hello";
7

9 $this->then("/index/next");
10 }
11

12 public function nextAction()

13 {
14 $this->view->cose = "ciao";
15 }
16 }

The result is the first view (index.phtml) concatenated to the second view (next.phtml).

3.3 Redirects

You can handle redirects using the redirect() method

1 <?php
2 class IndexController extends Controller
3 {
4 public function indexAction()
5 {
6 // Send as moved temporarily
7 $this->redirect("/contr/act", 302);
8 }
9 }

3.4 Interact with layout and views

You can disable the layout system at any time using the disableLayout() method.

1 <?php
2 class IndexController extends Controller
3 {
4 public function indexAction()
5 {
6 // Remove layout
7 $this->disableLayout();
8 }
9 }

You can disable the view attached to a controller using the setNoRender() method

1 <?php
2 class IndexController extends Controller
3 {
4 public function indexAction()

8 Chapter 3. Controllers
 simple-mvc Documentation, Release 0.1.0

5 {
6 // No this view
7 $this->setNoRender();
8 }
9 }

3.5 Change the layout on the fly

If you want to change your layout during an action or a plugin interaction you can use the resources manager

1 <?php
2 class IndexController extends Controller
3 {
4 public function fullWithAction()
5 {
6 $this->getResource("layout")->setScriptName("full-width.phtml");
7 }
8 }

Obviously you must use the layout manager.

3.6 Using headers

You can send different headers using addHeader() method

1 <?php
2 class IndexController extends Controller
3 {
4 public function indexAction()
5 {
6 $this->addHeader("Content-Type", "text/plain");
7 }
8 }

3.7 Change View Renderer

You can change the view renderer at runtime during an action execution.

1 <?php
2 class IndexController extends Controller
3 {
4 public function indexAction()
5 {
6 $this->setRenderer("/use/me");
7 }
8 }

The framework will use the use/me.phtml

The end.

3.5. Change the layout on the fly 9

simple-mvc Documentation, Release 0.1.0

10 Chapter 3. Controllers
 CHAPTER 4

Views

The framework starts without view system. For add view support you have to add view at bootstrap.

1 <?php
2

3 $app = new Application();

4 $app->bootstrap('view', function(){
5 $view = new View();
6 $view->addViewPath(__DIR__ . '/../views');
7

8 return $view;
9 });
10

11 $app->run();

The framework append automatically to a controller the right view using controller and action name. Tipically you
have to create a folder tree like this:

site
+ public
+ controllers
- views
- index
- index.phtml

In this way the system load correctly the controller path and the view script.

4.1 Layout support

The layout is handled as a simple view that wrap the controller view.
You need to bootstrap it. The normal layout name is “layout.phtml”

11
 simple-mvc Documentation, Release 0.1.0

1 <?php
2

3 $app->bootstrap('layout', function(){
4 $layout = new Layout();
5 $layout->addViewPath(__DIR__ . '/../layouts');
6

7 return $layout;
8 });

You can change the layout script name using the setter.

1 <?php
2 $layout->setScriptName("base.phtml");

4.2 View Helpers

If you want to create view helpers during your view bootstrap add an helper closure.

1 <?php
2 $app->bootstrap('view', function(){
3 $view = new View();
4 $view->addViewPath(__DIR__ . '/../views');
5

6 $view->addHelper("now", function(){
7 return date("d-m-Y");
8 });
9

10 return $view;
11 });

You can use it into you view as:

1 <?php echo $this->now()?>

You can create helpers with many variables

1 <?php
2 $view->addHelper("sayHello", function($name){
3 return "Hello {$name}";
4 });

View system is based using the prototype pattern all of your helpers attached at bootstrap time existing into all of your
real views.

4.2.1 Share view helpers

View helpers are automatically shared with layout. In this way you can creates global helpers during the bootstrap and
interact with those helpers at action time.
Pay attention that those helpers are copied. Use static scope for share variables.

1 <?php
2 $app->bootstrap("layout", function(){
3 $layout = new Layout();

12 Chapter 4. Views
 simple-mvc Documentation, Release 0.1.0

4 $layout->addViewPath(__DIR__ . '/../layouts');
5

7 return $layout;
8 });
9

10 $app->bootstrap("view", function(){
11 $view = new View();
12 $view->addViewPath(__DIR__ . '/../views');
13

14 $view->addHelper("title", function($part = false){

15 static $parts = array();
16 static $delimiter = ' :: ';
17

18 return ($part === false) ? "<title>".implode($delimiter, $parts)."</title>" :

˓→$parts[] = $part;
19 });
20

21 return $view;
22 });

From a view you can call the title() helper and it appends parts of you page title.

4.3 Escapes

Escape is a default view helper. You can escape variables using the escape() view helper.
1 <?php
2 $this->escape("Ciao -->"); // Ciao --&gt;

4.4 Partials view

Partials view are useful for render section of your view separately. In simple-mvc partials are view helpers.
1 <!-- ctr/act.phtml -->
2 <div>
3 <div>
4 <?php echo $this->partial("/path/to/view.phtml", array('title' => $this->
˓→title));?>

5 </div>
6 </div>

The partial view /path/to/view.phtml are located at view path.

1 <!-- /path/to/view.phtml -->
2 <p><?php echo $this->title; ?></p>

4.5 Multiple view scripts paths

simple-mvc support multiple views scripts paths. In other words you can specify a single mount point /path/to/views
after that you can add anther views script path, this mean that the simple-mvc search for a view previously into the

4.3. Escapes 13
 simple-mvc Documentation, Release 0.1.0

second views path and if it is missing looks for that into the first paths. View paths are threated as a stack, the latest
pushed is the first used.
During your bootstrap add more view paths

1 $app->bootstrap('view', function(){
2 $view = new View();
3 $view->addViewPath(__DIR__ . '/../views');
4 $view->addViewPath(__DIR__ . '/../views-rewrite');
5

6 return $view;
7 });

If you have a view named name.phtml into views folder and now you create the view named name.phtml into views-
rewrite this one is used instead the original file in views folder.

4.5.1 Partials and multiple view scripts paths

*Partial views follow the rewrite path strategy*. If you add the partial view into a rewrite view folder, this view
script is choosen instead the original partial script.

1 <?php echo $this->partial("my-helper.phtml", array('ciao' => 'hello'))?>

If my-helper.phtml is found in a rewrite point this view is used instead the original view script.
The end.

14 Chapter 4. Views
 CHAPTER 5

Events

Events
• loop.startup
• loop.shutdown
• pre.dispatch
• post.dispatch

5.1 Hooks

The loop.startup and loop.shutdown is called once at the start and at the end of the simple-mvc workflow.
The pre.dispatch and post.dispatch is called for every controlled pushed onto the stack (use the then() method).

5.1.1 Hooks params

The loop.startup and the loop.shutdown have the Application object as first parameter.
The pre.dispatch hook has the Route object as first parameter and the Application object as second.
The post.dispatch hook has the Controller object as first paramter.
• The router object is useful for modify the application flow.

1 <?php
2 $app->getEventManager()->subscribe("pre.dispatch", function($router, $app) {
3 // Use a real and better auth system
4 if ($_SESSION["auth"] !== true) {
5 $router->setControllerName("admin");
6 $router->setActionName("login");
7

8 $app->getBootstrap("layout")->setScriptName("admin.phtml");

15
 simple-mvc Documentation, Release 0.1.0

9 }
10 });

5.2 Create new events

1 <?php
2 // Call the hook named "my.hook" and pass the app as first arg.
3 $app->getEventManager()->publish("my.hook", array($app));

You can use the self-created hook using

1 <?php
2 $app->getEventManager()->subscribe("my.hook", function($app) {/*The body*/});

16 Chapter 5. Events
 CHAPTER 6

Pull Driven Requests

Typically MVC frameworks are “push” based. In otherwords use mechanisms to “push” data to a view and not vice-
versa. A “pull” framework instead request (“pull”) data from a view.
Pull strategy is useful for example during a for statement (not only for that [obviously]...). Look for an example:

1 <?php foreach ($this->users as $user) : ?>

2 <?php
3 // Pull data from a controller.
4 $userDetail = $this->pull("/detail/user/id/{$user->id}");
5 ?>
6 <div class="element">
7 <div class="name"><?php echo $userDetail->name;?> <?php echo $userDetail->surname;
˓→ ?></div>

8 <!-- other -->

9 </div>
10 <?php endforeach; ?>

6.1 simple-mvc implementation

simple-mvc has *push* and *pull* mechanisms. The push is quite simple and a typical operation. See an example

1 <?php
2 class EgController extends Controller
3 {
4 public function actAction()
5 {
6 // PUSH to view a variable named <code>var</code>
7 $this->view->var = "hello";
8 }
9 }

The view show the pushed variable

17
 simple-mvc Documentation, Release 0.1.0

1 <?php echo $this->var; ?>

The pull strategy is quite similar but use the return statement of a controller to retrive all the information. Consider
in advance that simple-mvc doesn’t require a valid controller for retrive a view, that view is mapped directly. See an
example

1 <!-- this view is test/miss.phtml (/test/miss GET) -->

2 <div>
3 <h1>Missing controller and action</h1>
4

5 <?php $data = $this->pull("/ctr/act"); ?>

6

7 <!-- example -->

8 <?php echo $data->title; ?>
9 </div>

The view require a pull operation from a controller named ctr and action act. See it:

1 <?php
2 class CtrController extends Controller
3 {
4 public function actAction()
5 {
6 $data = new stdClass();
7

8 $data->title = "The title";

9

10 // The return type doesn't care...

11 return $data;
12 }
13 }

You can use a “pull” controller as a normal controller with the attached view, but remember that when you request
for a “pull” operation the view is never considered and the framework remove it without consider the output, only the
return statement will be used.

18 Chapter 6. Pull Driven Requests

 CHAPTER 7

Examples of usage

A simple base app execution

1 <?php
2 $app = new Application();
3

4 $app->run();

7.1 Execute with bootstrap

1 <?php
2 $app = new Application();
3

4 $app->bootstrap("say-hello", function(){
5 return array('example' => 'ciao');
6 });
7

8 $app->run();

Into a controller

1 <?php
2 class IndexController extends Controller
3 {
4 public function indexAction()
5 {
6 $element = $this->getResource('example');
7

8 echo $element["example"];
9 }
10 }

19
 simple-mvc Documentation, Release 0.1.0

7.2 Controller Forward

You can pass to another controller using then()

1 <?php
2 class IndexController extends Controller
3 {
4 public function indexAction()
5 {
6 // Add forward action
7 $this->then("/index/forward");
8 }
9

10 public function forwardAction()

11 {
12 // append to index or use it directly
13 }
14 }

See example folder for a complete working example.

20 Chapter 7. Examples of usage

 CHAPTER 8

Indices and tables

• genindex
• modindex
• search

21