Download the PHP package jooservices/laravel-wordpress without Composer

Laravel WordPress

Laravel service package for WordPress local/remote CRUD, sync, and media record/file management.

This package is a service layer only: no routes, controllers, jobs, queues, events, listeners, audit log, sync history, background processing, or UI. It stores local WordPress state in package-owned tables, talks to remote WordPress through jooservices/wordpress-sdk, and keeps sync state explicit.

Install

See installation and configuration for setup notes.

Usage

Architecture Overview

The public flow is:

Grouped services expose resource families while the shared resource layer owns common local, remote, and sync behavior. ResourceDefinition classes adapt WordPress REST resources to local tables, Eloquent models, remote SDK services, and payload mapping. Details are in architecture.

Service Map

Resource Capability Matrix

Sync Lifecycle

pull() reads remote REST payloads, maps them through a ResourceDefinition, stores local records, and updates explicit sync hashes and timestamps. push() creates or updates remote records from local models. sync() currently aliases pull behavior on shared resources.

Sync state uses local and remote hashes, sync_status, synced_at, last_pulled_at, last_pushed_at, conflict_payload, and conflicted_at. See sync.

Conflict Handling

The package does not auto-merge conflicts. Dirty local records are not silently overwritten by a remote pull, and remote changes are not silently overwritten by a local push unless force/local resolution is intentionally used. Use:

• resolveConflictUsingLocal($model) to force the local model to WordPress.
• resolveConflictUsingRemote($model) to replace the local model with the remote payload.
• resolveConflictManually($model, $payload) after building an explicit merged payload.

Media Lifecycle

media()->records()->pull() stores attachment records and source URLs. media()->files()->download($media) copies remote bytes into Laravel Storage. media()->files()->upload($data) sends file bytes to the WordPress Media Library and persists the returned attachment record locally. media()->files()->deleteLocal($media) deletes only the local copied file. Physical files are never deleted as a side effect of record sync.

See media files.

Adding a New Resource

Add a ResourceDefinition, register it in ResourceRegistry, expose it from the appropriate grouped service if needed, and cover payload mapping plus sync behavior with focused tests. Keep resource definitions as adapters and keep database or remote coordination in services. See adding a resource.

Testing

Real Docker Integration Workflow

The Docker workflow installs a fresh Laravel app, installs this package into it with a Composer path repository, installs WordPress with WP-CLI, seeds real WordPress records and media files, runs Laravel package migrations, and executes a PHPUnit smoke test against the real services.

Prerequisites: Docker and Docker Compose.

The workflow validates package discovery, config loading, package migrations, WP-CLI availability, WordPress installation, real WordPress post/media generation, WordPress-to-Laravel pull sync, media record pull, explicit media file download, update handling, idempotent repeated pull behavior, Laravel-originated post create/update push through DTOs, Laravel-originated page create push through DTOs, taxonomy assignment, featured media assignment, unpublish, trash behavior with local reflection, and dirty-local conflict detection against a real remote change. It writes:

The JSON report includes environment versions, executed paths/commands, package capabilities, schema audit notes, WordPress record counts, Laravel record counts, media record/file evidence, pull/push/idempotency results, assertions, skipped assertions, failures, and limitations. Media is reported in three separate buckets: WordPress attachments, Laravel media records, and local copied files. Useful defaults can be overridden with environment variables such as DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD, WORDPRESS_PATH, WORDPRESS_URL, LARAVEL_APP_PATH, and PACKAGE_PATH.

See Docker WordPress testing.

Known Limitations

• Media upload uses the SDK's Media Library upload endpoint; field acceptance still depends on WordPress runtime permissions and REST support.
• Posts/pages have feature-level coverage; many generic resource definitions are available through shared services but are not all feature-complete.
• Author assignment depends on runtime WordPress REST permissions and configuration.
• Custom meta requires WordPress meta keys registered with show_in_rest=true.
• Endpoint shape and capabilities can vary by WordPress version, plugins, themes, auth type, and user permissions.