Plugin Fundamentals

{
	"name": "lumenpress/lumen-catalog",
	"type": "wordpress-plugin",
	"license": "GPL-2.0-or-later",
	"require": {
		"php": ">=7.4"
	},
	"require-dev": {
		"wp-coding-standards/wpcs": "3.4.1"
	},
	"autoload": {
		"psr-4": {
			"Lumen\\Catalog\\": "src/"
		}
	},
	"config": {
		"platform": {
			"php": "7.4.33"
		},
		"optimize-autoloader": true,
		"allow-plugins": {
			"dealerdirect/phpcodesniffer-composer-installer": true
		}
	}
}

<?php
/**
 * Plugin Name:       Lumen Catalog
 * Plugin URI:        https://lumenpress.example/lumen-catalog/
 * Description:       Book catalogue for Lumen Press: the lp_book post type, its taxonomies, meta and REST API.
 * Version:           0.1.0
 * Requires at least: 6.9
 * Requires PHP:      7.4
 * Author:            Lumen Press
 * Author URI:        https://lumenpress.example/
 * License:           GPL-2.0-or-later
 * License URI:       https://www.gnu.org/licenses/gpl-2.0.html
 * Text Domain:       lumen-catalog
 * Domain Path:       /languages
 * Update URI:        https://plugins.lumenpress.example/lumen-catalog/
 *
 * @package Lumen\Catalog
 */

use Lumen\Catalog\Installer;
use Lumen\Catalog\Plugin;

defined( 'ABSPATH' ) || exit;

define( 'LUMEN_CATALOG_VERSION', '0.1.0' );
define( 'LUMEN_CATALOG_FILE', __FILE__ );

// Release ZIP: the plugin's own vendor/. Composer-managed site: the site's autoloader already knows the classes.
if ( ! class_exists( Plugin::class ) ) {
	if ( ! is_readable( __DIR__ . '/vendor/autoload.php' ) ) {
		add_action(
			'admin_notices',
			static function () {
				echo '<div class="notice notice-error"><p>';
				echo esc_html__( 'Lumen Catalog is missing its vendor/ directory. Run composer install.', 'lumen-catalog' );
				echo '</p></div>';
			}
		);
		return;
	}
	require_once __DIR__ . '/vendor/autoload.php';
}

register_activation_hook( __FILE__, array( Installer::class, 'activate' ) );
register_deactivation_hook( __FILE__, array( Installer::class, 'deactivate' ) );

add_action( 'plugins_loaded', array( Plugin::class, 'boot' ) );

<?php
/**
 * Plugin bootstrap.
 *
 * @package Lumen\Catalog
 */

namespace Lumen\Catalog;

defined( 'ABSPATH' ) || exit;

/**
 * Wires the plugin's services to WordPress hooks.
 */
final class Plugin {

	/**
	 * Runs once per request on plugins_loaded.
	 */
	public static function boot(): void {
		Installer::maybe_upgrade();

		add_action( 'init', array( self::class, 'register_post_types' ) );
	}

	/**
	 * Registers lp_book (taxonomies and meta are added later). Also called on activation.
	 */
	public static function register_post_types(): void {
		register_post_type(
			'lp_book',
			array(
				'label'        => __( 'Books', 'lumen-catalog' ),
				'public'       => true,
				'show_in_rest' => true,
				'has_archive'  => true,
				'rewrite'      => array( 'slug' => 'books' ),
				'supports'     => array( 'title', 'editor', 'excerpt', 'thumbnail', 'custom-fields', 'revisions' ),
			)
		);
	}
}

<?php
/**
 * Activation, deactivation, upgrade and uninstall routines.
 *
 * @package Lumen\Catalog
 */

namespace Lumen\Catalog;

defined( 'ABSPATH' ) || exit;

/**
 * Owns everything the plugin stores outside its own files.
 */
final class Installer {

	const DB_VERSION     = 2; // Schema version this code expects; bump it with every migration.
	const VERSION_OPTION = 'lumen_catalog_db_version';

	/**
	 * Activation: install or upgrade the data, then rebuild the rewrite rules once.
	 */
	public static function activate(): void {
		self::upgrade();

		// The post type must exist before the rules are rebuilt, or /books/ returns 404.
		Plugin::register_post_types();
		flush_rewrite_rules( false );
	}

	/**
	 * Deactivation: stop scheduled work and drop the rules. Never delete data here.
	 */
	public static function deactivate(): void {
		wp_clear_scheduled_hook( 'lp_catalog_sync_stock' );

		unregister_post_type( 'lp_book' );
		flush_rewrite_rules( false );
	}

	/**
	 * Runs on every request (one autoloaded option read) and upgrades when needed.
	 */
	public static function maybe_upgrade(): void {
		if ( (int) get_option( self::VERSION_OPTION, 0 ) < self::DB_VERSION ) {
			self::upgrade();
		}
	}

	/**
	 * Applies every migration newer than the installed schema version, in order.
	 */
	public static function upgrade(): void {
		$installed = (int) get_option( self::VERSION_OPTION, 0 );

		if ( $installed < 1 ) {
			self::create_tables();
			add_option( 'lp_catalog_settings', array( 'isbn_prefix' => '978' ) );
		}

		if ( $installed < 2 ) {
			// 0.1.0 replaced the lumen_catalog_isbn_prefix option with a settings key.
			$settings                = (array) get_option( 'lp_catalog_settings', array() );
			$settings['isbn_prefix'] = (string) get_option( 'lumen_catalog_isbn_prefix', $settings['isbn_prefix'] ?? '978' );
			update_option( 'lp_catalog_settings', $settings );
			delete_option( 'lumen_catalog_isbn_prefix' );
		}

		update_option( self::VERSION_OPTION, self::DB_VERSION, true );
	}

	/**
	 * Creates or updates the stock movement history table with dbDelta(), which is safe to run again.
	 * The current stock of a book is its lp_stock post meta; this table keeps one row per change.
	 */
	private static function create_tables(): void {
		global $wpdb;
		require_once ABSPATH . 'wp-admin/includes/upgrade.php';

		$table   = $wpdb->prefix . 'lp_stock';
		$charset = $wpdb->get_charset_collate();

		dbDelta(
			"CREATE TABLE {$table} (
  id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  book_id bigint(20) unsigned NOT NULL,
  distributor_sku varchar(64) NOT NULL DEFAULT '',
  delta int(11) NOT NULL DEFAULT '0',
  quantity int(11) NOT NULL DEFAULT '0',
  changed_at datetime NOT NULL,
  PRIMARY KEY  (id),
  KEY book_changed (book_id,changed_at)
) {$charset};"
		);
	}

	/**
	 * Uninstall: remove the plugin's options and table from one site.
	 */
	public static function uninstall_site(): void {
		global $wpdb;

		delete_option( self::VERSION_OPTION );
		delete_option( 'lp_catalog_settings' );
		$wpdb->query( "DROP TABLE IF EXISTS {$wpdb->prefix}lp_stock" ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery,WordPress.DB.PreparedSQL.InterpolatedNotPrepared
	}
}

<?php
/**
 * Runs when an administrator deletes the plugin from the Plugins screen or with WP-CLI.
 *
 * @package Lumen\Catalog
 */

if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
	exit;
}

if ( ! class_exists( Lumen\Catalog\Installer::class ) ) {
	require_once __DIR__ . '/vendor/autoload.php';
}

if ( is_multisite() ) {
	foreach ( get_sites( array( 'fields' => 'ids' ) ) as $lumen_catalog_site_id ) {
		switch_to_blog( $lumen_catalog_site_id );
		Lumen\Catalog\Installer::uninstall_site();
		restore_current_blog();
	}
} else {
	Lumen\Catalog\Installer::uninstall_site();
}

<?xml version="1.0"?>
<ruleset name="Lumen Catalog">
	<file>.</file>
	<exclude-pattern>/vendor/*</exclude-pattern>

	<config name="minimum_wp_version" value="6.9"/>

	<rule ref="WordPress"/>

	<!-- PSR-4 file names (src/Plugin.php) instead of class-plugin.php. -->
	<rule ref="WordPress.Files.FileName">
		<exclude-pattern>/src/*</exclude-pattern>
	</rule>

	<rule ref="WordPress.NamingConventions.PrefixAllGlobals">
		<properties>
			<property name="prefixes" type="array">
				<element value="Lumen\Catalog"/>
				<element value="lumen_catalog"/>
			</property>
		</properties>
	</rule>
</ruleset>

wp option add lumen_catalog_isbn_prefix 979
wp plugin activate lumen-catalog
wp option get lumen_catalog_db_version
wp option get lp_catalog_settings --format=json
wp db query "SHOW TABLES LIKE 'lp_lp_stock'" --skip-column-names
wp rewrite list --format=csv --fields=match | grep -c '^books/'
wp plugin deactivate lumen-catalog
wp rewrite list --format=csv --fields=match | grep -c '^books/'
wp option get lumen_catalog_db_version

Success: Added 'lumen_catalog_isbn_prefix' option.
[28-Oct-2026 14:37:47 UTC] [lifecycle] activate_plugin lumen-catalog/lumen-catalog.php
[28-Oct-2026 14:37:47 UTC] [lifecycle] activated_plugin lumen-catalog/lumen-catalog.php
Plugin 'lumen-catalog' activated.
Success: Activated 1 of 1 plugins.
2
{"isbn_prefix":"979"}
lp_lp_stock
18
[28-Oct-2026 14:37:50 UTC] [lifecycle] deactivate_plugin lumen-catalog/lumen-catalog.php
[28-Oct-2026 14:37:50 UTC] [lifecycle] deactivated_plugin lumen-catalog/lumen-catalog.php
Plugin 'lumen-catalog' deactivated.
Success: Deactivated 1 of 1 plugins.
0
2

wp plugin activate lumen-catalog
wp eval 'update_option( "lumen_catalog_db_version", 1 ); update_option( "lumen_catalog_isbn_prefix", "977" );'
wp option get lumen_catalog_db_version
wp option get lp_catalog_settings --format=json

wp plugin uninstall lumen-catalog --deactivate
wp option list --search='lumen_catalog*' --format=count
wp db query "SHOW TABLES LIKE 'lp_lp_stock'" --skip-column-names
wp db query "SELECT COUNT(*) FROM lp_posts WHERE post_type = 'lp_book'" --skip-column-names

Deactivating 'lumen-catalog'...
[28-Oct-2026 14:37:54 UTC] [lifecycle] deactivate_plugin lumen-catalog/lumen-catalog.php
[28-Oct-2026 14:37:54 UTC] [lifecycle] deactivated_plugin lumen-catalog/lumen-catalog.php
Plugin 'lumen-catalog' deactivated.
[28-Oct-2026 14:37:54 UTC] [lifecycle] pre_uninstall_plugin lumen-catalog/lumen-catalog.php
[28-Oct-2026 14:37:54 UTC] [lifecycle] delete_plugin lumen-catalog/lumen-catalog.php
[28-Oct-2026 14:37:54 UTC] [lifecycle] deleted_plugin lumen-catalog/lumen-catalog.php
Uninstalled and deleted 'lumen-catalog' plugin.
Success: Uninstalled 1 of 1 plugins.
0
1