Documentation

MicropubAdapter

Micropub Adapter Abstract Superclass

Subclass this class and implement the various *Callback() methods to handle different types of micropub request.

Then, handling a micropub request is as simple as

$mp = new YourMicropubAdapter();
return $mp->handleRequest($request);

The same goes for a media endpoint:

return $mp->handleMediaEndpointRequest($request);

Subclasses must implement the abstract callback method verifyAccessToken() in order to have a functional micropub endpoint. All other callback methods are optional, and their functionality is enabled if a subclass implements them. Feel free to define your own constructor, and make any implementation-specific objects available to callbacks by storing them as properties.

Each callback is passed data corresponding to the type of micropub request dispatched to it, but can also access the original request via $this->request. Data about the currently authenticated user is available in $this->user.

Each callback return data in a format defined by the callback, which will be converted into the appropriate HTTP Response. Returning an instance of ResponseInterface from a callback will cause that response to immediately be returned unchanged. Most callbacks will also automatically convert an array return value into a JSON response, and will convert the following string error codes into properly formatted micropub error responses:

  • 'invalid_request'
  • 'insufficient_scope'
  • 'unauthorized'
  • 'forbidden'

In practise, you’ll mostly be returning the first two, as the others are handled automatically.

MicropubAdapter does not handle any authorization or permissions, as which users and scopes have what permissions depends on your implementation. It’s up to you to confirm that the current access token has sufficient scope and permissions to carry out any given action within your callback, and return 'insufficient_scope' or your own custom instance of ResponseInterface.

Most callbacks halt execution, but some are optional. Returning a falsy value from these optional callbacks continues execution uninterrupted. This is usually to allow you to pre- empt standard micropub handling and implement custom extensions.

MicropubAdapter works with PSR-7 HTTP Interfaces. Specifically, expects an object implementing ServerRequestInterface, and will return an object implemeting ResponseInterface. If you want to return responses from your callbacks, you’re free to use any suitable implementation. For internally-generated responses, Nyholm\Psr7\Response is used.

If you’re not using a framework which works with PSR-7 objects, you’ll have to convert whatever request data you have into something implementing PSR-7 ServerRequestInterface, and convert the returned ResponseInterfaces to something you can work with.

Tags
link
https://micropub.spec.indieweb.org/
link
https://indieweb.org/micropub

Table of Contents

$logger  : LoggerInterface|null
$request  : RequestInterface
$user  : array<string|int, mixed>
$errorMessages  : array<string|int, string>
configurationQueryCallback()  : array<string|int, mixed>|string|ResponseInterface
Configuration Query Callback
createCallback()  : string|array<string|int, mixed>|ResponseInterface
Create Callback
deleteCallback()  : string|true|array<string|int, mixed>|ResponseInterface
Delete Callback
extensionCallback()  : false|array<string|int, mixed>|string|ResponseInterface
Micropub Extension Callback
handleMediaEndpointRequest()  : ResponseInterface
Handle Media Endpoint Request
handleRequest()  : ResponseInterface
Handle Micropub Request
mediaEndpointCallback()  : string|array<string|int, mixed>|ResponseInterface
Media Endpoint Callback
mediaEndpointExtensionCallback()  : false|array<string|int, mixed>|string|ResponseInterface
Micropub Media Endpoint Extension Callback
sourceQueryCallback()  : array<string|int, mixed>|false|string|ResponseInterface
Source Query Callback
undeleteCallback()  : string|true|array<string|int, mixed>|ResponseInterface
Undelete Callback
updateCallback()  : true|string|array<string|int, mixed>|ResponseInterface
Update Callback
verifyAccessTokenCallback()  : array<string|int, mixed>|string|false|ResponseInterface
Verify Access Token Callback
getLogger()  : LoggerInterface
Get Logger
toResponse()  : ResponseInterface
To Response

Properties

$errorMessages

private array<string|int, string> $errorMessages = [ // Built-in micropub error types 'insufficient_scope' => 'Your access token does not grant the scope required for this action.', 'forbidden' => 'The authenticated user does not have permission to perform this request.', 'unauthorized' => 'The request did not provide an access token.', 'invalid_request' => 'The request was invalid.', // Custom errors 'access_token_invalid' => 'The provided access token could not be verified.', 'missing_url_parameter' => 'The request did not provide the required url parameter.', 'post_with_given_url_not_found' => 'A post with the given URL could not be found.', 'not_implemented' => 'This functionality is not implemented.', ]

Methods

configurationQueryCallback()

Configuration Query Callback

public configurationQueryCallback(array<string|int, mixed> $params) : array<string|int, mixed>|string|ResponseInterface

Handle a GET q=config query. Should return either a custom ResponseInterface, or an array structure conforming to the micropub specification, e.g.:

[
  'media-endpoint' => 'http://example.com/your-media-endpoint',
  'syndicate-to' => [[
    'uid' => 'https://myfavoritesocialnetwork.example/aaronpk', // Required
    'name' => 'aaronpk on myfavoritesocialnetwork', // Required
    'service' => [ // Optional
      'name' => 'My Favorite Social Network',
      'url' => 'https://myfavoritesocialnetwork.example/',
      'photo' => 'https://myfavoritesocialnetwork.example/img/icon.png',
    ],
    'user' => [ // Optional
      'name' => 'aaronpk',
      'photo' => 'https://myfavoritesocialnetwork.example/aaronpk',
      'url' => 'https://myfavoritesocialnetwork.example/aaronpk/photo.jpg'
    ]
  ]]
]

The results from this function are also used to respond to syndicate-to queries. If a raw ResponseInterface is returned, that will be used as-is. If an array structure is returned, syndicate-to queries will extract the syndicate-to information and return just that.

Parameters
$params : array<string|int, mixed>

The unaltered query string parameters from the request.

Tags
link
https://micropub.spec.indieweb.org/#configuration
Return values
array<string|int, mixed>|string|ResponseInterface —

Return either an array with config data, a micropub error string, or a ResponseInterface to short-circuit

createCallback()

Create Callback

public createCallback(array<string|int, mixed> $data, array<string|int, mixed> $uploadedFiles) : string|array<string|int, mixed>|ResponseInterface

Handles a create request. JSON parameters are left unchanged, urlencoded form parameters are normalized into canonical microformats-2 JSON form.

  • If the current access token scope doesn’t permit updates, return either 'insufficient_scope', an array with 'error' and 'error_description' keys, or your own ResponseInterface.
  • Create the post.
  • On an error, return either a micropub error code to be upgraded into a full error response, or your own ResponseInterface.
  • On success, return either the URL of the created post to be upgraded into a HTTP 201 success response, or your own ResponseInterface.
Parameters
$data : array<string|int, mixed>

The data to create a post with in canonical MF2 structure

$uploadedFiles : array<string|int, mixed>

an associative array mapping property names to UploadedFileInterface objects, or arrays thereof

Tags
link
https://micropub.spec.indieweb.org/#create
Return values
string|array<string|int, mixed>|ResponseInterface —

A URL on success, a micropub error code, an array to be returned as JSON response, or a ready-made ResponseInterface

deleteCallback()

Delete Callback

public deleteCallback(string $url) : string|true|array<string|int, mixed>|ResponseInterface

Handle a POST action=delete request.

  • Look for a post identified by the $url parameter.
  • If it doesn’t exist: return false or 'invalid_request' as a shortcut for an HTTP 400 invalid_request response.
  • If the current access token scope doesn’t permit deletion, return 'insufficient_scope', an array with 'error' and 'error_description' keys, or your own ResponseInterface.
  • If the post exists and can be deleted or is already deleted, delete it and return true.
Parameters
$url : string

The URL of the post to be deleted.

Tags
link
https://micropub.spec.indieweb.org/#delete
Return values
string|true|array<string|int, mixed>|ResponseInterface —

extensionCallback()

Micropub Extension Callback

public extensionCallback(ServerRequestInterface $request) : false|array<string|int, mixed>|string|ResponseInterface

This callback is called after an access token is verified, but before any micropub- specific handling takes place. This is the place to implement support for micropub extensions.

If a falsy value is returned, the request continues to be handled as a regular micropub request. If it returns a truthy value (either a MP error code, an array to be returned as JSON, or a ready-made ResponseInterface), request handling is halted and the returned value is converted into a response and returned.

Parameters
$request : ServerRequestInterface
Tags
link
https://indieweb.org/Micropub-extensions
Return values
false|array<string|int, mixed>|string|ResponseInterface —

handleMediaEndpointRequest()

Handle Media Endpoint Request

public handleMediaEndpointRequest(ServerRequestInterface $request) : ResponseInterface

Handle a request to a micropub media-endpoint.

As with handleRequest(), $this->request and $this->user are made available for use within callbacks.

Parameters
$request : ServerRequestInterface
Return values
ResponseInterface —

handleRequest()

Handle Micropub Request

public handleRequest(ServerRequestInterface $request) : ResponseInterface

Handle an incoming request to a micropub endpoint, performing error checking and handing execution off to the appropriate callback.

$this->request is set to the value of the $request argument, for use within callbacks. If the access token could be verified, $this->user is set to the value returned from verifyAccessTokenCallback() for use within callbacks.

Parameters
$request : ServerRequestInterface
Return values
ResponseInterface —

mediaEndpointCallback()

Media Endpoint Callback

public mediaEndpointCallback(UploadedFileInterface $file) : string|array<string|int, mixed>|ResponseInterface

To handle file upload requests:

  • If the current access token scope doesn’t permit uploads, return either 'insufficient_scope', an array with 'error' and 'error_description' keys, or your own ResponseInterface.
  • Handle the uploaded file.
  • On an error, return either a micropub error code to be upgraded into a full error response, or your own ResponseInterface.
  • On success, return either the URL of the created URL to be upgraded into a HTTP 201 success response, or your own ResponseInterface.
Parameters
$file : UploadedFileInterface

The file to upload

Tags
link
https://micropub.spec.indieweb.org/#media-endpoint
Return values
string|array<string|int, mixed>|ResponseInterface —

Return the URL of the uploaded file on success, a micropub error code to be upgraded into an error response, an array for a JSON response, or a ready-made ResponseInterface

mediaEndpointExtensionCallback()

Micropub Media Endpoint Extension Callback

public mediaEndpointExtensionCallback(ServerRequestInterface $request) : false|array<string|int, mixed>|string|ResponseInterface

This callback is called after an access token is verified, but before any media- endpoint-specific handling takes place. This is the place to implement support for micropub media endpoint extensions.

If a falsy value is returned, the request continues to be handled as a regular micropub request. If it returns a truthy value (either a MP error code, an array to be returned as JSON, or a ready-made ResponseInterface), request handling is halted and the returned value is converted into a response and returned.

Parameters
$request : ServerRequestInterface
Tags
link
https://indieweb.org/Micropub-extensions
Return values
false|array<string|int, mixed>|string|ResponseInterface —

sourceQueryCallback()

Source Query Callback

public sourceQueryCallback(string $url[, array<string|int, mixed>|null $properties = null ]) : array<string|int, mixed>|false|string|ResponseInterface

Handle a GET q=source query.

The callback should return a microformats2 canonical JSON representation of the post identified by $url, either as an array or as a ready-made ResponseInterface.

If the post identified by $url cannot be found, returning false will return a correctly-formatted error response. Alternatively, you can return a string micropub error code (e.g. 'invalid_request') or your own instance of ResponseInterface.

Parameters
$url : string

The URL of the post for which to return properties.

$properties : array<string|int, mixed>|null = null

= null The list of properties to return (all if null)

Tags
link
https://micropub.spec.indieweb.org/#source-content
Return values
array<string|int, mixed>|false|string|ResponseInterface —

Return either an array with canonical mf2 data, false if the post could not be found, a micropub error string, or a ResponseInterface to short-circuit.

undeleteCallback()

Undelete Callback

public undeleteCallback(string $url) : string|true|array<string|int, mixed>|ResponseInterface

Handle a POST action=undelete request.

  • Look for a post identified by the $url parameter.
  • If it doesn’t exist: return false or 'invalid_request' as a shortcut for an HTTP 400 invalid_request response.
  • If the current access token scope doesn’t permit undeletion, return 'insufficient_scope', an array with 'error' and 'error_description' keys, or your own ResponseInterface.
  • If the post exists and can be undeleted, do so. Return true for success, or a URL if the undeletion caused the post’s URL to change.
Parameters
$url : string

The URL of the post to be undeleted.

Tags
link
https://micropub.spec.indieweb.org/#delete
Return values
string|true|array<string|int, mixed>|ResponseInterface —

true on basic success, otherwise either an error string, or a URL if the undeletion caused the post’s location to change.

updateCallback()

Update Callback

public updateCallback(string $url, array<string|int, mixed> $actions) : true|string|array<string|int, mixed>|ResponseInterface

Handles a POST action=update request.

  • Look for a post identified by the $url parameter.
  • If it doesn’t exist: return false or 'invalid_request' as a shortcut for an HTTP 400 invalid_request response.
  • If the current access token scope doesn’t permit updates, return 'insufficient_scope', an array with 'error' and 'error_description' keys, or your own ResponseInterface.
  • If the post exists and can be updated, do so. Return true for basic success, or a URL if the undeletion caused the post’s URL to change.
Parameters
$url : string

The URL of the post to be updated.

$actions : array<string|int, mixed>

The parsed body of the request, containing 'replace', 'add' and/or 'delete' keys describing the operations to perfom on the post.

Tags
link
https://micropub.spec.indieweb.org/#update
Return values
true|string|array<string|int, mixed>|ResponseInterface —

Return true for a basic success, a micropub error string, an array to be converted to a JSON response, or a ready-made ResponseInterface

verifyAccessTokenCallback()

Verify Access Token Callback

public abstract verifyAccessTokenCallback(string $token) : array<string|int, mixed>|string|false|ResponseInterface

Given an access token, attempt to verify it.

  • If it’s valid, return an array to be stored in $this->user, which typically looks something like this:

    [
  'me' => 'https://example.com',
  'client_id' => 'https://clientapp.example',
  'scope' => ['array', 'of', 'granted', 'scopes'],
  'date_issued' => \Datetime
]

  • If the toke in invalid, return one of the following:

    • false, which will be converted into an appropriate error message.

    • 'forbidden', which will be converted into an appropriate error message.

    • An array to be converted into an error response, with the form:

      [
  'error': 'forbidden'
  'error_description': 'Your custom error description'
]

    • Your own instance of ResponseInterface

MicropubAdapter treats the data as being opaque, and simply makes it available to your callback methods for further processing, so you’re free to structure it however you want.

Parameters
$token : string

The Authentication: Bearer access token.

Tags
link
https://micropub.spec.indieweb.org/#authentication-0
Return values
array<string|int, mixed>|string|false|ResponseInterface —

getLogger()

Get Logger

protected getLogger() : LoggerInterface

Returns an instance of Psr\LoggerInterface, used for logging. Override to provide with your logger of choice.

Return values
LoggerInterface —

toResponse()

To Response

private toResponse(null|string|array<string|int, mixed>|ResponseInterface $resultOrResponse[, int $status = 200 ]) : ResponseInterface

Intelligently convert various shortcuts into a suitable instance of ResponseInterface. Existing ResponseInterfaces are passed through without alteration.

Parameters
$resultOrResponse : null|string|array<string|int, mixed>|ResponseInterface
$status : int = 200
Return values
ResponseInterface —

Search results