Orbis Contacts

WordPress plugin for Orbis that provides a shared contact layer for Orbis Persons and Orbis Organizations, including email addresses, phone numbers, social accounts and relations between contacts.

This plugin is based on the SolveBeam WordPress plugin boilerplate, see its README for the architecture and coding conventions.

Contact post types

A post type becomes a contact by supporting orbis-contact, Orbis Persons and Orbis Organizations register their post types like this:

\register_post_type(
	'orbis_person',
	[
		'supports' => [
			'title',
			'editor',
			'orbis-contact',
		],
	]
);

• orbis_contact is a post type without posts of its own. A query for orbis_contact queries all contact post types, which gives a contacts archive (/contacts/) and a "Contacts" admin menu with all contacts.
• Every contact post gets a row in the {prefix}orbis_contacts table (id, post_id, created_at, updated_at).
• Contact details are stored in post meta, connections between contacts use Posts 2 Posts.

Contact details

Every contact post type gets a "Contact Details" meta box with multiple email addresses and phone numbers, each with a label (e.g. Work, Mobile, Home, Other).

Meta key	Value
_orbis_contact_email	One row per email address, a plain email address string.
_orbis_contact_phone	One row per phone number, standardized to E.164, e.g. +31612345678.
_orbis_contact_json	The whole contact as one JSON string, see json-schemas/contact.json.

Because every email address is a separate meta row, contacts are easy to find with a meta query:

$query = new \WP_Query(
	[
		'post_type'  => 'orbis_contact',
		'meta_key'   => '_orbis_contact_email',
		'meta_value' => 'info@example.com',
	]
);

The _orbis_email post meta of Orbis Persons and Orbis Organizations can be migrated to the contact email addresses, without label. Invalid email addresses and addresses the contact already has are skipped, so it is safe to run multiple times. The old post meta is kept.

wp orbis-contacts migrate-email-addresses --dry-run
wp orbis-contacts migrate-email-addresses

Phone numbers

Phone numbers are standardized to E.164 with libphonenumber for PHP, so they can be queried exactly, no matter how they were entered (06 12345678, +31 6 1234 5678, 0031612345678, …):

$query = new \WP_Query(
	[
		'post_type'  => 'orbis_contact',
		'meta_key'   => '_orbis_contact_phone',
		'meta_value' => \Pronamic\Orbis\Contacts\PhoneNumbers::to_e164( '06 12345678' ),
	]
);

Numbers without a country calling code are parsed with the "Default Phone Country" on Settings → General (orbis_contacts_default_country option, defaults to the country of the site locale). Numbers that can't be standardized are kept in _orbis_contact_json with e164 set to null, without a _orbis_contact_phone row, and get a warning in the meta box.

The _orbis_phone_number and _orbis_mobile_number post meta of Orbis Persons can be migrated to the contact phone numbers (without label and with label "Mobile"). Numbers the contact already has are skipped, so it is safe to run multiple times. The old post meta is kept.

wp orbis-contacts migrate-phone-numbers --dry-run
wp orbis-contacts migrate-phone-numbers

The _orbis_contact_json post meta looks like this:

{
	"$schema": "https://github.com/pronamic/wp-orbis-contacts/json-schemas/contact.json",
	"post_id": 123,
	"contact_id": 45,
	"type": "orbis_person",
	"name": "John Doe",
	"email_addresses": [
		{
			"email": "info@example.com",
			"label": "Work"
		}
	],
	"phone_numbers": [
		{
			"input": "06 12345678",
			"label": "Mobile",
			"e164": "+31612345678"
		}
	]
}

Use ContactJson::get( $post_id ), ContactJson::get_email_addresses( $post_id ) and ContactJson::get_phone_numbers( $post_id ) to read the contact details.

Contact picker (Select2)

Other plugins can let users pick a contact with a select element with the orbis-contact-id-control class. The value is an ID from the {prefix}orbis_contacts table.

\wp_enqueue_script( 'orbis-contact-select2' );

<select name="contact_id" class="orbis-contact-id-control">
	<option value="45" data-icon="dashicons-businessman" data-type-label="Person" data-email="info@example.com" data-archived="1">John Doe</option>
</select>

Use ContactSelect2Controller::get_option_data( $contact_id ) for the data of a preselected option. The script searches through the orbis-contacts/v1/contacts/select2?term=… REST API endpoint, which returns the Select2 data format:

{
	"results": [
		{
			"id": 45,
			"text": "John Doe",
			"type": "orbis_person",
			"type_label": "Person",
			"icon": "dashicons-businessman",
			"email": "info@example.com"
		}
	]
}

Contacts archived with Orbis Archiver (_orbis_archived_at post meta) get an "Archived" label in the picker.

The select2 script and style are registered by the Orbis core plugin.

Templates

The plugin ships an archive contact template, modelled after the person archive template of Orbis Persons. It is used unless the theme has its own archive-orbis_contact.php.

Template	Shown on	Content
templates/archive-orbis_contact.php	Contacts archive (/contacts/)	Table with photo, name, type, email addresses, categories and author

Requirements

• PHP 8.3+
• WordPress 7.1+
• Composer
• Node.js / npm

Installation

composer install
npm install

Development

npx wp-env start

Mount path	Source
wp-content/plugins/orbis-contacts-dev	./
wp-content/plugins/orbis-contacts	./build/orbis-contacts/

composer run phpcs
composer run phpstan
composer run build
composer run make-pot

Deploy

vendor/bin/dep deploy

License

GPL-2.0-or-later