init-development-studios/headless-wordpress-sync

Sync content from a headless WordPress instance using the WP REST API.

3.1.0 2024-03-16 13:19 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^11.0
• spatie/laravel-package-tools: ^1.13.0

Requires (Dev)

• laravel/pint: ^1.0
• nunomaduro/collision: ^8.1
• orchestra/testbench: ^9.0
• pestphp/pest: ^2.0
• pestphp/pest-plugin-laravel: ^2.0
• phpstan/extension-installer: ^1.1
• phpstan/phpstan-deprecation-rules: ^1.0
• phpstan/phpstan-phpunit: ^1.0
• phpunit/phpunit: ^10.0
• spatie/laravel-ray: ^1.26

MIT

• Aaron Heath
• Benjamin Ayles

• json
• api
• wordpress
• headless
• laravel
• Init Development Stuidios
• Init Dev
• headless-wordpress-sync

README

A Laravel package which simplifies the integration with a headless WordPress instance.

[[TOC]]

Getting Started

This guide will walk though the setting up both the Laravel instance along with headless WordPress instance.

The setup has two steps:

1. Setting up WordPress
2. Setting up Laravel

Headless WordPress

Setting up WordPress involves the installation and activation of two WordPress plugins.

• CollabPay Headless WordPress Plugin (https://gitlab.com/collabpay/headless-wordpress-plugin) - TODO move this under Init Dev banner for re-usability.
• JWT Authentication For WP REST API (https://en-au.wordpress.org/plugins/jwt-authentication-for-wp-rest-api/) - Third party plugin which enables access to API resources requiring authentication (eg user details).
• Make sure to set WP to use postname for the permalink or the api will just 404.

Step X

Let's kick off by installation the JWT Authentication For WP REST API plugin.

Follow the instructions found on the plugins installation page.

For the vast majority the "Using The WordPress Dashboard" will suffice.

Step X

The JTW Authentication plugin also requires a little configuration. We must define a secret key in the wp-config.php file.

Simply add the following.

define('JWT_AUTH_SECRET_KEY', 'your-top-secret-key');

You can use a string from here (https://api.wordpress.org/secret-key/1.1/salt/).

Step X

Activate the JWT Authentication plugin from the Installed Plugins page within the WordPress Admin interface.

Step X

Now let's install the Laravel Headless WordPress Plugin.

As this plugin is not published publicly we're best off installing the new plugin via a ZIP file.

Download the latest version (.zip)

Step X

From the Add New plugin page click the Upload Plugin button found at the top of the page.

Then the Browse button.

Find and select the ZIP file downloaded above.

Click Install Now.

Then click Activate Plugin.

WordPress is now setup!

Laravel

We're now up to installing and configuring the Laravel package.

Step X

The Laravel package can be installed via composer.

However, as this package is not publicly available the following manual changes to the composer.json file are required.

Add the following root json object:

"repositories": [
    {
        "type": "git",
        "url": "[e-mail]:init-dev/headless-wordpress/headless-wordpress-sync.git"
    }
],

Then run:

composer require init-development-studios/headless-wordpress-sync:dev-main

Note, you must have authorisation to access the GIT repository.

Step X

Several tables require migration.

Publish the migrations.

php artisan vendor:publish --tag=headless-wordpress-sync-migrations

Step X

Run the migration.

php artisan migrate

Step X

Now let's publish the config file.

php artisan vendor:publish --tag=headless-wordpress-sync-config

Step X

There will now be a headless-wordpress-sync.php config file within the Laravel applications config directory.

Take a look over the file and configure your application as desired. Note that the following attributes are required:

• url - configurable via HEADLESS_WP_URL in the applications .env file.
• username - configurable via HEADLESS_WP_USERNAME in the applications .env file.
• password - configurable via HEADLESS_WP_PASSWORD in the applications .env file.

Example .env

HEADLESS_WP_URL=https://wordpress.test
HEADLESS_WP_USERNAME=api-user
HEADLESS_WP_PASSWORD="tQdVIc!gdb7eD(o9IZ&^WEXm"

Optional

When developing locally it's often useful to not require SSL / TLS verification.

HEADLESS_WP_VERIFY_CERTIFICATE=false

When hosting content for many sites, providing the website_slug for the site who's content is to be displayed on this Laravel applications instance is required.

This slug matches that defined Posts > Website from withing the Headless WordPress applications Admin interface.

HEADLESS_WP_WEBSITE_SLUG=collabpay

Step X

In order to keep the Laravel application in sync with the WordPress application a Scheduled Task is performed each minute.

The Scheduled Task will run automatically.

Make sure that the application has Scheduled Tasks running and that HEADLESS_WP_SYNC_ENABLED is either absent or set to TRUE in the .env file.

Note that a sync can also be manually performed by running php artisan headless-wp:sync.

Step X

You can now start updating your application to present your WordPress managed content.

Fetching Content

Content can be fetched using standard Eloquent queries!

Posts

All Posts

WpPost::all()

Individual Post

WpPost::whereSlug('individual-post-slug')->first();

Scoped to the current website

WpPost::currentWebsite()->get()

Published posts only

WpPost::published()->get()

Ordering by date / time published

WpPost::orderByDesc('published_at_utc')->get()

In a specified category

WpPost::inCategory(WpCategory::whereSlug('tutorials')->first())->get()

Individual post categories

WpPost::whereSlug('individual-post-slug')->first()->categories;

Individual post tags

WpPost::whereSlug('individual-post-slug')->first()->tags;

Individual post author

WpPost::whereSlug('individual-post-slug')->first()->author;

Related posts

All related and inversely related posts.

To relate a posts add the a Custom Field on a post with the Name related_post_slugs and then set the Value to a comma separated list of post slugs.

WpPost::whereSlug('individual-post-slug')->first()->related();

Related posts query

Same as above but will return a query builder to permit further query building

$query = WpPost::whereSlug('individual-post-slug')->first()->relatedQuery();

// Can then be queried further (eg only return published related articles)
$query->published()->get();

Search posts

Search for an exact term within a posts title and content.

Note this is performed at the DB level.

For better search consider using Laravel Scout.

WpPost::search('individual-post-slug')->first()->related();

Categories

All categories

WpCategory::all()

Individual category

WpCategory::whereSlug('tutorials')->first()

Authors (users)

All authors

WpUser::all();

Individual author

WpUser::find(1);

Individual authors Gravatar avatar url

WpUser::find(1)->image()->url();

TODOs

• Disable WP frontend such that it's truly headless. Used another plugin in the past however having this built in would be ideal.
• Search input rendering on individual category pages
• Improved social media meta tags
• Idea: add search to sidebar on individual posts and possibly other places throughout the site. Easy to do now.

Support

TODO

Roadmap

Short term

• Make WP plugin public. Requires further refining and testing. Likely achievable within CollabPay use case.
• Make Laravel plugin public. Should only occur inline with WP plugin being published publicly.
• Add screenshots to readme

Longer term

• Expand support for more WordPress features / functionality.
• Support for Laravel Scout when searching posts.

Contributing

TODO

Authors and acknowledgment

TODO

License

TODO