Skip to main content

Plugin Packaging

Build and create production-ready plugin packages for deployment.

Overview​

The package-plugin.ps1 script creates a production-ready ZIP file of the GSM Middleware plugin that can be installed through the WordPress admin interface.

Requirements​

  • PowerShell 5.1 or higher (Windows PowerShell or PowerShell Core)
  • Node.js and npm (for building React assets)
  • Composer installed and available in PATH
  • Write permissions in the plugin directory

Prerequisites​

IMPORTANT: Before packaging, you must build the React application:

npm install
npm run build

This creates the build/ directory containing compiled React assets required for the Control Panel and other features. The packaging script will fail if the build directory is not found.

Usage​

Basic Packaging​

Run the packaging script from the plugin root directory:

.\package-plugin.ps1

Output​

The script creates a dist/ directory containing:

  • gsm-middleware-{version}.zip - The distributable plugin package

What Gets Included​

The packaged plugin includes only production-ready files:

  • ✅ gsm-middleware.php - Main plugin file
  • ✅ src/ - All source code
  • ✅ assets/ - CSS, JavaScript, images
  • ✅ build/ - Compiled React application assets
  • ✅ templates/ - PHP templates
  • ✅ vendor/ - Production Composer dependencies (optimized)
  • ✅ languages/ - Translation files
  • ✅ README.md - Plugin documentation

What Gets Excluded​

Development and testing files are automatically excluded:

  • ❌ All test scripts (test-*.php, check-*.php, debug-*.php, verify-*.php)
  • ❌ Development tools (node_modules/, .git/, packages/)
  • ❌ Build logs (logs/)
  • ❌ Documentation (docs/, AGENTS.md, SECURITY.md, etc.)
  • ❌ Configuration files (.babelrc, webpack.config.js, composer.json, etc.)
  • ❌ Development dependencies (Composer dev packages)

Installation Instructions​

After packaging, install the plugin on a WordPress site:

  1. Log into WordPress Admin
  2. Navigate to Plugins > Add New
  3. Click Upload Plugin
  4. Choose the generated ZIP file from dist/gsm-middleware-{version}.zip
  5. Click Install Now
  6. Activate the plugin after installation

Continuous Integration​

To integrate this into a CI/CD pipeline:

# Build React assets
npm install
npm run build

# Run packaging script
.\package-plugin.ps1

# The artifact will be at:
# dist/gsm-middleware-{version}.zip

Troubleshooting​

Build Directory Not Found​

If you see "ERROR: Build directory not found!":

  1. Run npm install to install dependencies
  2. Run npm run build to compile React assets
  3. Try packaging again

Composer Install Fails​

If composer install fails during packaging:

  1. Ensure Composer is installed and in your PATH
  2. Check that composer.json is valid
  3. Verify network connectivity for downloading packages
  4. Check PHP version requirements (PHP 8.2+ required)

Missing Files in Package​

If expected files are missing:

  1. Check that files exist in the plugin directory
  2. Verify file paths in the $includePaths array in package-plugin.ps1
  3. Ensure files aren't being filtered by cleanup patterns

ZIP Creation Fails​

If ZIP creation fails:

  1. Check disk space in the dist/ directory
  2. Ensure no files are locked by other processes
  3. Verify write permissions

Version Management​

The version number in the package name is automatically extracted from the main plugin file (gsm-middleware.php). To update the version:

  1. Update the Version: header in gsm-middleware.php
  2. Update the GSM_MIDDLEWARE_VERSION constant
  3. Run the packaging script to create a new versioned package

Security Notes​

  • The packaging script excludes sensitive files (.env, logs, etc.)
  • Production dependencies are installed with --no-dev flag
  • Autoloader is optimized for production use
  • No development credentials or API keys are included

Support​

For issues with the packaging process, contact the development team at [email protected]