PHPackages                             tagged/kleinbottle - 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. tagged/kleinbottle

ActiveLibrary

tagged/kleinbottle
==================

Easily create restful apis and services. Based on Klein.php

11.7k1[1 issues](https://github.com/rdgoetz/kleinbottle/issues)PHP

Since Feb 7Pushed 12y ago2 watchersCompare

[ Source](https://github.com/rdgoetz/kleinbottle)[ Packagist](https://packagist.org/packages/tagged/kleinbottle)[ RSS](/packages/tagged-kleinbottle/feed)WikiDiscussions master Synced 2mo ago

READMEChangelogDependenciesVersions (2)Used By (0)

Restful routing/controllers
===========================

[](#restful-routingcontrollers)

This is just a wrapper around [Klein](https://github.com/chriso/klein.php) that allows for easy construction of restful urls and controllers.

A url maps to a controller based on a routes mapping, and the controller handles the http request/response. Controllers can respond to types of routes, one for resources and another for collections (of the same resource).5

Routes
------

[](#routes)

A route looks something like **/owners/\[a:name\]/dogs** or **/users/\[:userid\]/photos/\[i:photoid\]**

The value in square brackets is matched and passed to the controller as query parameters. A request to **/owners/george/dogs?color=brown** becomes

```
name = george
color = brown

```

The value behind the colon is the parameter name, and the value in front is a validation type.

See https://github.com/chriso/klein.php#routing for more about route syntax.

---

The router takes a parameter that is an array of routes mapped to a controller, like

```
"routes" => array(
            # requests to /api/v1/hello handled by tag_tool_api_v1_hello
            "/login" => "login",
            #  a namespace URL. Children of this are appended.
            "/users/[i:userid]" => array(
                "/loginhistory" => "loginhistory",
                "/messages" => "messages",
                "/photos" => "photos",
                "/photos/[i:photoid]" => "photos"
            )
        )
```

where the key is the route path and the value a namespace. If instead of a string, the value is an array, then the routes in that array are nested under the parent path. The router also takes a parameter defining a route namespace and another one defining the controller namespace.

If your domain is **[www.mypets.com](http://www.mypets.com)**, the route namespace **/api/v1**, and the controller namespace **/app/controllers** then routes generated by this are:

```
/api/v1/login                               => /app/controllers/login.php
/api/v1/users/[i:userid]/loginhistory       => /app/controllers/loginhistory.php
/api/v1/users/[i:userid]/messages           => /app/controllers/messages.php
/api/v1/users/[i:userid]/photos             => /app/controllers/photos.php
/api/v1/users/[i:userid]/photos/[i:photoid] => /app/controllers/photos.php

```

The http methods supported by each route are determined by looking at the controller. Routes are either handled as a collection or a resource. A resource acts on a single record (database row), and a collection acts on many records (database table). In the example above, requests to /api/v1/users/\[i:userid\]/photos would be handled by the controller as a collection, and /api/v1/users/\[i:userid\]/photos/\[i:photoid\] as a resource. This is determined by the convention of resource routes ending in an id/paramter (*\[i:photoid\]*) and collections ending in the name of the collection (*photos*).

Controllers
-----------

[](#controllers)

Controllers handle the http request. A handler method expects to be passed a $request and $response object. The default mapping is below, this can be overridden in the main router object. Controllers don't need to extend anything, they just need to implement any of these methods. Methods not implemented become HTTP 405 errors when requested.

Every controller method is passed a response and request object. Check  for documentation.

HTTP methodController methodExpected actionGET (resource)fetch()get the requested item (no side effects)PUT (resource)update()update the requested item (idempotent)DELETE (resource)delete()delete the requested item (idempotent)GET (collection)index()list all items matching the query (no side effects)POST (collection)index()create a new itemPUT (collection)bulkUpdate()update a set of items (idempotent)DELETE (collection)deleteAll()delete all items (idempotent)Controllers also support custom actions. If a controller has the public method `public function translate($request, $response)`, then a POST to **/api/v1/languages/translate?from=english&to=esperanto** will call the method translate on the languages controller. If the requested method does not exist on the controller, then the response 404's.

If dev mode is enabled, GET requests to custom actions are allowed as well.

Usage
-----

[](#usage)

Put this in an index.php file:

```