humanmade / authorship
Authorship
Installs: 123 119
Dependents: 0
Suggesters: 0
Security: 0
Stars: 67
Watchers: 17
Forks: 7
Open Issues: 46
Type:wordpress-plugin
Requires
- php: >=7.2
- composer/installers: ^1.0 || ^2.0
- humanmade/asset-loader: ^0.5.0 || ^0.6.1
Requires (Dev)
- dealerdirect/phpcodesniffer-composer-installer: 0.7.0
- ergebnis/composer-normalize: ^2
- humanmade/coding-standards: 1.1.1
- php-stubs/wordpress-stubs: ^5.5
- phpcompatibility/phpcompatibility-wp: 2.1.0
- phpstan/phpstan: 0.12.57
- phpunit/phpunit: ^9.5.20
- roots/wordpress: ~5.9.0
- squizlabs/php_codesniffer: 3.5.8
- szepeviktor/phpstan-wordpress: 0.7.1
- vlucas/phpdotenv: ^3
- wp-cli/db-command: ^2
- wp-phpunit/wp-phpunit: ~5.9.3
- yoast/phpunit-polyfills: ^1.0
This package is auto-updated.
Last update: 2024-10-29 15:26:02 UTC
README
Stable tag: 0.2.17
Requires at least: 5.4
Tested up to: 6.2
Requires PHP: 7.2
License: GPL v3 or later
Contributors: johnbillion, humanmade
A modern approach to author attribution in WordPress.
Description
Authorship is a modern approach to author attribution in WordPress. It supports attributing posts to multiple authors and to guest authors, provides a great UI, and treats API access to author data as a first-class citizen.
Authorship is currently geared toward developers who are implementing custom solutions on WordPress. For example, it doesn't provide an option to automatically display author profiles at the bottom of a post. In the future it will include wider support for existing themes and useful features for implementors and site builders.
- Current Status
- Features
- Installation
- Design Decisions
- Template Functions
- REST API
- WP-CLI
- Email Notifications
- Accessibility
- Security, Privileges, and Privacy
- Contributing
- Team
- License
- Alternatives
Current Status
Alpha. Generally very functional but several features are still in development.
Features
- Multiple authors per post
- Guest authors (that can be created in place on the post editing screen)
- A convenient and user-friendly UI that feels like a part of WordPress
- Works with the block editor
- Works with the classic editor
- Full CRUD support in the REST API and WP-CLI
- Full support in RSS feeds
- Full support in Atom feeds
- Fine-grained user permission controls
Features without a checkmark are still work in progress.
Installation
For normal use
composer require humanmade/authorship
For development use
- Clone this repo into your plugins directory
- Ensure you have Composer v2 and Node v16 installed
- Install the dependencies:
composer install && npm install
- Start the dev server:
npm run start
Design Decisions
Why another multi-author plugin? What about Co-Authors Plus or Bylines or PublishPress Authors?
Firstly, those plugins are great and have served us well over the years, however they all suffer from similar problems:
- API: Lack of support for writing and reading author data via the REST API and WP-CLI
- UI: Limited or custom UI that doesn't feel like a part of WordPress
- Users: An unnecessary distinction between guest authors and actual WordPress users
Let's look at these points in detail and explain how Authorship addresses them:
API design decisions
There's a lot more to a modern WordPress site than just its theme. Data gets written to and read from its APIs, so these need to be treated as first-class citizens when working with the attributed authors of posts.
Authorship provides:
- Ability to read and write attributed authors via an
authorship
field on thewp/v2/posts
REST API endpoints - Ability to create guest authors via the
authorship/v1/users
REST API endpoint - Read-only access to users who can be attributed to a post via the
authorship/v1/users
REST API endpoint - Ability to specify attributed authors when creating or updating posts via WP-CLI with the
--authorship
flag
UI design decisions
We'd love it if you activated Authorship and then forgot that its features are provided by a plugin. The UI provides convenient functionality without looking out of place, both in the block editor and the classic editor.
User design decisions
Existing plugins that provide guest author functionality make a distinction between a guest author and a real WordPress user. A guest author exists only as a taxonomy term, which complicates the UX and creates inconsistencies and duplication in the data.
Authorship creates a real WordPress user account for each guest author, which provides several advantages:
- No custom administration screens for managing guest authors separately from regular users
- Plugins that customise user profiles work for guest authors too
- Consistent data structure - you only ever deal with
WP_User
objects - No need to keep data in sync between a user and their "author" profile
- Promoting a guest author to a functional user is done just by changing their user role
Template Functions
The following template functions are available for use in your theme to fetch the attributed author(s) of a post:
\Authorship\get_author_names( $post )
- Returns a comma-separated list of the names of the attributed author(s)
\Authorship\get_author_names_sentence( $post )
- Returns a sentence stating the names of the attributed author(s), localised to the current language
\Authorship\get_author_names_list( $post )
- Returns an unordered HTML list of the names of the attributed author(s)
\Authorship\get_authors( $post )
- Returns a list of user objects of the attributed authors
\Authorship\get_author_ids( $post )
- Returns a list of user ids of the attributed authors
REST API
The following REST API endpoints and fields are available:
authorship/v1/users
endpoint
This endpoint allows:
- Searching all users who can be attributed to content
- Creating guest authors
authorship
field
This field is added to the endpoint for all supported post types (by default, ones which that have post type support for author
), for example wp/v2/posts
. This field is readable and writable and accepts and provides an array of IDs of users attributed to the post.
In addition, user objects are embedded in the _embedded['wp:authorship']
field in the response if _embed
is set and the authenticated user can list users.
WP-CLI
Authorship implements a custom flag for use with posts, and migration commands. The following WP-CLI flags are available:
--authorship
--authorship
flag
When creating or updating posts the --authorship
flag can be used to specify the IDs of users attributed to the post. The flag accepts a comma-separated list of user IDs. Examples:
wp post create --post_title="My New Post" --authorship=4,11
wp post update 220 --authorship=13
If this flag is not set:
- When creating a new post, if the
--post_author
flag is set then it will be used for attributed authors - When updating an existing post, no change will be made to attributed authors
Migration of WordPress authors on existing posts.
If you activate Authorship on an existing site, all content already created will not have authorship data set for old content. This breaks things such as author archive pages.
This command will set the WordPress author as the authorship user for any posts with no authorship user. (Optionally you can override any existing authorship data, updating it with the WordPress post author).
wp authorship migrate wp-authors --dry-run=true
The command will perform a dry run by default, setting --dry-run=false
will make changes to the database.
This command will not overwrite or update Authorship data unless the --overwrite-authors=true
flag is set.
PublishPress Authors Migration
Authorship provides a command for creating Authorship data using data from PublishPress Authors. This allows a non-destructive migration path from PublishPress Authors.
With both plugins active, this command will copy PPA data into Authorship:
wp authorship migrate ppa --dry-run=true
The command will perform a dry run by default, setting --dry-run=false
will make changes to the database. Guest authors that do not exist as users will be created with blank emails and random passwords.
This command will not overwrite or update Authorship data unless the --overwrite-authors=true
flag is set.
Email Notifications
Authorship does not send any email notifications itself, but it does instruct WordPress core to additionally send its emails to attributed authors when appropriate.
- When a comment on a post is held for moderation, the comment moderation email also gets sent to all attributed authors who have the ability to moderate the comment and have a valid email address
- When a comment on a post is published, the comment notification email also gets sent to all attributed authors who have a valid email address
This plugin only adjusts the list of email addresses to which these emails get sent. If you want to disable these emails entirely, see the "Email me whenever" section of the Settings -> Discussion screen in WordPress.
Accessibility
Authorship aims to conform to Web Content Accessibility Guidelines (WCAG) 2.1 at level AA but it does not yet fully achieve this. If full support for assistive technology is a requirement of your organisation then Authorship may not be a good fit in its current state.
With regard to the author selection control on the post editing screen:
- ✅ The visual styles are inherited from WordPress core and are WCAG 2.1 AA compliant
- ✅ The control is fully accessible using only the keyboard
- 🚫 The keyboard controls are not very intuitive
- 🚫 The control is not fully accessible when using a screen reader
The team are actively investigating either replacing the component used to render the control with a fully accessible one, or fixing the accessibility issues of the current one.
Security, Privileges, and Privacy
Great care has been taken to ensure Authorship makes no changes to the user capabilities required to edit content or view sensitive user data on your site. What it does do is:
- Grant users who are attributed to a post the ability to edit that post if their capabilities allow it
- Grant users the ability to create and assign guest authors to a post
- Allow this behaviour to be changed at a granular level with custom capabilities
Assigning Attribution
The capability required to change the attribution of a post matches that which is required by WordPress core to change the post author. This means a user needs the edit_others_post
capability for the post type. The result is no change in behaviour from WordPress core with regard to being able to attribute a post to another user.
- Administrators and Editors can change the attributed authors of a post
- Authors and Contributors cannot change the attributed authors and see a read-only list when editing a post
Authorship allows the attribution to be changed for any post type that has post type support for author
, which by default is Posts and Pages.
Editing Posts
When a user is attributed to a post, that user becomes able to manage that post according to their capabilities as if they were the post author. This means:
- A post that is attributed to a user with a role of Author can be edited, published, and deleted by that user
- A post that is attributed to a user with a role of Contributor can be edited by that user while in draft, but cannot be not published, and cannot be edited once published
From a practical point of view this feature only affects users with a role of Author or Contributor. Administrators and Editors can edit other users' posts by default and therefore edit, publish, and delete posts regardless of whether they are attributed to it.
Searching Users
The authorship/v1/users
REST API endpoint provides a means of searching users on the site in order to attribute them to a post. Access to this endpoint is granted to all users who have the capability to change the attributed authors of the given post type, which means Editors and Administrators by default. The result is no change in behaviour from WordPress core with regard to being able to search users.
In addition, this endpoint has been designed to expose minimal information about users, for example it does not expose email addresses or capabilities. This allows lower level users such as users with a role of Author to be granted the ability to attribute users to a post without unnecessarily exposing sensitive information about other users.
Creating Guest Authors
The authorship/v1/users
REST API endpoint provides a means of creating guest authors that can subsequently be attributed to a post. Access to this endpoint is granted to all users who have the ability to edit others' posts, which means Editors and Administrators by default.
More work is still to be done around the ability to subsequently edit guest authors, but it's worth noting that this is the one area where Authorship diverges from the default capabilities of WordPress core. It allows an Editor role user to create a new user account, which they usually cannot do. However it is tightly controlled:
- An email address cannot be provided unless the user has the
create_users
capability, which only Administrators do - A user role cannot be provided, it is always set to Guest Author
Capability Customisation
The following custom user capabilities are used by Authorship. These can be granted to or denied from users or roles in order to adjust user access:
attribute_post_type
- Used when attributing users to a given post type
- Maps to the
edit_others_posts
capability of the post type by default
create_guest_authors
- Used when creating a guest author
- Maps to
edit_others_posts
by default
Contributing
Code contributions, feedback, and feature suggestions are very welcome. See CONTRIBUTING.md for more details.
Team
Authorship is developed and maintained by Human Made and Altis. Its initial development was funded by Siemens.
License
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Alternatives
If the Authorship plugin doesn't suit your needs, try these alternatives: