PHPackages                             codeeverything/planck-framework - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. codeeverything/planck-framework

ActiveLibrary[Framework](/categories/framework)

codeeverything/planck-framework
===============================

0.1(10y ago)320PHP

Since Jun 2Pushed 9y ago1 watchersCompare

[ Source](https://github.com/codeeverything/planck-mvc)[ Packagist](https://packagist.org/packages/codeeverything/planck-framework)[ RSS](/packages/codeeverything-planck-framework/feed)WikiDiscussions master Synced 4w ago

READMEChangelog (1)Dependencies (1)Versions (4)Used By (0)

Planck
======

[](#planck)

### A small framework for RESTful PHP apps

[](#a-small-framework-for-restful-php-apps)

An experiment in writing a \[small\] RESTful framework for PHP. Makes use of the [Burlap](https://www.github.com/codeeverything/burlap) container for dependencies.

Named for the [Planck time](https://en.wikipedia.org/wiki/Planck_time) and [length](https://en.wikipedia.org/wiki/Planck_length) - the smallest measurements of time and length, respectively, that have any meaning.

NB: This is an ongoing project in its infancy, so expect much to be missing and much not to work ;)

Open Source
-----------

[](#open-source)

This is an open source effort, and although its only a pet project of mine contributions are welcome! So fork and PR away :)

Feel free to add issues to leave suggestions and comments.

Take a look at [LICENSE.md](LICENSE.md) for more info (MIT).

Writing a simple app
--------------------

[](#writing-a-simple-app)

Planck is designed to be minimal and to help you quickly get working with RESTful responses.

The routing of RESTful requests is still the responsibility of your router and routes, but with the default Junction router that's easy to achieve.

### App structure

[](#app-structure)

All your application code will live in the `/src/App` folder, with the exception of any routes, services or listeners you define.

Planck expects only two things in order to get you up and running:

- A route which returns an array containing entries for the controller to instantiate, the action to call on that controller and any variables to pass from the route.
- A controller matching the name given in the route, with the suffix "Controller" and an action on that controller matching the action given in the route.

For example:

```
// config/routes.php
$router->add('GET /hello', function () {
    return [
        'controller' => 'Hello',
        'action' => 'hello',
        'vars' => func_get_args(),
    ];
});
```

```
// src/App/Controller/HelloController.php
namespace Planck\App\Controller;

class HelloController {

    public function hello() {
        return 'hello, world';
    }

}
```

Controllers in Planck are the entry and exit points for your business logic. Since we're concerned with RESTful applications we expect a controller to return some data, which can be done in two ways:

- By calling `$this->set('property_name', 'property_value');` inline within a controller, to set return values in a peacemeal fashion
- By returning a value, or set of values from the controller `return ['property' => 'value', 'result' => 1234];`
    - Note: This return can be any serializable data type (using the JsonSerializable interface in PHP this could even be a POPO)

### Responses

[](#responses)

Planck's default behaviour is to return responses as JSON, but this can be changed by using one of the other built in `ResponseFormatters`, or rolling your own.

##### Keeping it RESTful

[](#keeping-it-restful)

Planck includes a `RESTController` which you can extend to get access to some useful convenience methods - for example:

- `$this->ok()` - set the response code as 200
- `$this->created()` - set the response code as 201
- `$this->created(false)` - set the response code as 202 (accepted, will be created later)
- `$this->blank()` - set the response code as 204 (no message body)
- `$this->unchanged()` - set the response code as 304 (removes message body)

The RESTController also includes a handy `afterAction` callback which will sniff your request method and try to set approriate codes and body content for you. For example:

- GET - 200 OK
- POST - 201 CREATED
- PUT - 201 CREATED
- DELETE - 204 NO CONTENT

If these don't suit your needs you can currently override the behavior by having an empty (or custom) `afterAction` function in your controller. In future I aim to make the process more flexible.

### Throw RESTful errors

[](#throw-restful-errors)

If there's an error condition in your app (the record with $id doesn't exist for example), throw an exception to capture this and return an appropriate HTTP coded message, all wrapped up in a nice neat package.

Planck includes exceptions for the most common RESTful error responses, covering:

- Error (400)
- Not found (404)
- Not authorized (401)
- Forbidden (403)
- Conflict (409)
- Server error (500)

Errors are returned in a neat package, handled by defining a service with the name `errorResponseBuilder`, which returns a function accepting a single argument - the exception that has been thrown.

The default package is an array with items for "error" and "code", showing the exception message and HTTP status code respectively. You can change this to be whatever you want simply be redefining the service.

### Services and Dependency Injection

[](#services-and-dependency-injection)

Planck is agnostic about the container you use, though it does expect it to implement the Container Interoperability Interface.

By default Planck uses the lightweight Burlap container.

A controller's dependencies are drawn from the container, and can be injected by simply referencing container services as the arguments for the controller's `init()` function, e.g.:

```
// controller code

// inject the service labelled as "db" into this function
public function init($db) {
    $this->db = $db;
}

// more controller code
```

### Listeners

[](#listeners)

Planck implements a simple event system, which you can extend with your own app specific events.

Event listeners are defined in the `config/listeners.php` file, and by convention Planck expects these to live in the `src/App/Listener` folder, but this is up to you.

##### An example listener

[](#an-example-listener)

```
//src/App/Listener/ExampleListener.php