Micropub

Description

A Micropub server plugin. From micropub.net:

Micropub is an open API standard that is used to create posts on one’s own domain using third-party clients. Web apps and native apps (e.g. iPhone, Android) can use Micropub to post short notes, photos, events or other posts to your own site, similar to a Twitter client posting to Twitter.com.

Once you’ve installed and activated the plugin, try using Quill to create a new post on your site. It walks you through the steps and helps you troubleshoot if you run into any problems. After that, try other clients like OwnYourGram, OwnYourCheckin, MobilePub, and Teacup.

Supports the full W3C Micropub CR spec as of 2016-10-18, except for the optional media endpoint. Media may be uploaded directly to the wordpress-micropub endpoint as multipart/form-data, or sideloaded from URLs.

WordPress details

Filters and hooks

Adds one filter: before_micropub( $input )

Called before handling a Micropub request. Returns $input, possibly modified.

…and one hook: after_micropub( $input, $wp_args = null)

Called after handling a Micropub request. Not called if the request fails (ie doesn’t return HTTP 2xx).

Arguments:

  • $input: associative array, the Micropub request in JSON format. If the request was form-encoded or a multipart file upload, it’s converted to JSON format.
  • $wp_args: optional associative array. For creates and updates, this is the arguments passed to wp_insert_post or wp_update_post. For deletes and undeletes, args[‘ID’] contains the post id to be (un)deleted. Null for queries.

Other

Stores microformats2 properties in post metadata with keys prefixed by mf2_. Details here. All values are arrays; use unserialize() to deserialize them.

Does not support multithreading. PHP doesn’t really either, so it generally won’t matter, but just for the record.

Authentication and authorization

Supports the full OAuth2/IndieAuth authentication and authorization flow. Defaults to IndieAuth. Custom auth and token endpoints can be used by overriding the MICROPUB_AUTHENTICATION_ENDPOINT and MICROPUB_TOKEN_ENDPOINT endpoints. If the token’s me value matches a WordPress user’s URL, that user will be used. Otherwise, the token must match the site’s URL, and no user will be used.

Alternatively, you can set MICROPUB_LOCAL_AUTH to 1 to use WordPress’s internal user login instead of tokens.

Finally, for ease of development, if the WordPress site is running on localhost, it logs a warning if the access token is missing or invalid and still allows the request.

Configuration Options

These configuration options can be enabled by adding them to your wp-config.php

  • define('MICROPUB_LOCAL_AUTH', '1') – Bypasses Micropub authentication in favor of WordPress authentication
  • define('MICROPUB_AUTHENTICATION_ENDPOINT', 'https://indieauth.com/auth') – Define a custom authentication endpoint
  • define('MICROPUB_TOKEN_ENDPOINT', 'https://tokens.indieauth.com/token') – Define a custom token endpoint
  • define('MICROPUB_DRAFT_MODE', '1') – Set all Micropub posts to draft mode

Development

The canonical repo is http://github.com/snarfed/wordpress-micropub . Feedback and pull requests are welcome!

To add a new release to the WordPress plugin directory, run push.sh.

To set up your local environment to run the unit tests:

  1. Install PHPUnit, e.g. brew install homebrew/php/wp-cli phpunit with Homebrew on Mac OS X.
  2. Install and start MySQL. (You may already have it.)
  3. Run ./bin/install-wp-tests.sh wordpress_micropub_test root '' localhost to download WordPress and its unit test library, into /tmp and ./temp by default, and create a MySQL db to test against. Background here. Feel free to use a MySQL user other than root. You can set the WP_CORE_DIR and WP_TESTS_DIR environment variables to change where WordPress and its test library are installed. For example, I put them both in the repo dir.
  4. Open wordpress-tests-lib/wp-tests-config.php and add a slash to the end of the ABSPATH value. No clue why it leaves off the slash; it doesn’t work without it.
  5. Run phpunit in the repo root dir. If you set WP_CORE_DIR and WP_TESTS_DIR above, you’ll need to set them for this too. You should see output like this:

    Installing…

    1 / 1 (100%)
    Time: 703 ms, Memory: 33.75Mb
    OK (1 test, 3 assertions)

To set up PHPCodesniffer to test adherence to WordPress Coding Standards:

  1. Install PHPCS.
  2. Install and connect WordPress-Coding-Standards.
  3. Run in command line or install a plugin for your favorite editor.
  4. To list coding standard issues in a file, run phpcs --standard=phpcs.ruleset.xml micropub.php.
  5. If you want to try to automatically fix issues, run phpcbf with the same arguments as phpcs.

Installation

Install from the WordPress plugin directory or put micropub.php in your plugin directory. No setup needed.

FAQ

If your Micropub client includes an Authorization HTTP request header but you still get an HTTP 401 response with body missing access token, your server may be stripping the Authorization header. If you’re on Apache, try adding this line to your .htaccess file:

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

If that doesn’t work, try this line:

RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

If that doesn’t work either, you may need to ask your hosting provider to whitelist the Authorization header for your account. If they refuse, you can pass it through Apache with an alternate name, but you’ll need to edit this plugin’s code to read from that alternate name.

Installation Instructions

Install from the WordPress plugin directory or put micropub.php in your plugin directory. No setup needed.

Contributors & Developers

“Micropub” is open source software. The following people have contributed to this plugin.

Contributors

Translate “Micropub” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.

Changelog

1.2 (2017-06-25)

1.1 (2017-03-30)

  • Support h-adr, h-geo, and plain text values for p-location.
  • Bug fix for create/update with content[html].

1.0.1

  • Remove accidental dependence on PHP 5.3 (#46).

1.0

Substantial update. Supports full W3C Micropub spec, except for optional
media endpoint.

  • Change mf2_* post meta format from multiple separate values to single array value that can be deserialized with unserialize.
  • Change the before_micropub filter’s signature from ( $wp_args ) to ( $input ) (microformats2 associative array).
  • Change the after_micropub hook’s signature changed from ( $post_id ) to ( $input, $wp_args ) (microformats2 associative array, WordPress post args).
  • Post content will not be automatically marked up if theme supports microformats2 or Post Kinds plugin is enabled.
  • Add PHP Codesniffer File.

0.4

  • Store all properties in post meta except those in a blacklist.
  • Support setting authentication and token endpoint in wp-config by setting MICROPUB_AUTHENTICATION_ENDPOINT and MICROPUB_TOKEN_ENDPOINT.
  • Support setting all micropub posts to draft in wp-config for testing by setting MICROPUB_DRAFT_MODE in wp-config.
  • Support using local auth to authenticate as opposed to Indieauth as by setting MICROPUB_LOCAL_AUTH in wp-config.
  • Set content to summary if no content provided.
  • Support querying for syndicate-to and future query options.

0.3

  • Use the specific WordPress user whose URL matches the access token, if possible.
  • Set post_date_gmt as well as post_date.

0.2

  • Support more Micropub properties: photo, like-of, repost-of, in-reply-to, rsvp, location, category, h=event.
  • Check but don’t require access tokens on localhost.
  • Better error handling.

0.1

Initial release.