feat(packagist): prepare package for Packagist availability

[faisalahammad]

🎯 Summary

Prepares the gravityforms/gravityformscli package for Packagist publication by adding the required wp-cli/wp-cli dependency, improving metadata for discoverability, and documenting the Packagist installation method.

📋 Issue Reference

Fixes #42

🔍 Problem Description

Current Behavior

The package declares "type": "wp-cli-package" in composer.json but is not available on Packagist. Users who consume it via WPackagist get it installed as a WordPress plugin rather than a proper WP-CLI package. Installing via wp package install gravityforms/gravityformscli fails because Packagist cannot resolve the package.

Expected Behavior

The package should be installable as a WP-CLI package directly from Packagist using:

wp package install gravityforms/gravityformscli

Root Cause

The composer.json is missing the wp-cli/wp-cli dependency, which is the standard requirement for WP-CLI packages listed on Packagist. Without this dependency, Composer cannot properly resolve the package as a WP-CLI extension. Additionally, the package has never been submitted to Packagist.

✨ Solution Overview

Approach Taken

Updated composer.json with the necessary dependency and metadata to make the package Packagist-ready:

1. Added wp-cli/wp-cli ^2.5 as a required dependency
2. Added keywords for search discoverability
3. Added extra.commands to document provided CLI commands
4. Updated PHP minimum to >=5.6 (required by WP-CLI 2.x)
5. Fixed SPDX license identifier
6. Updated .gitattributes for clean distribution
7. Added installation instructions to README.md

Why This Approach

This follows the established pattern used by official WP-CLI packages (e.g., wp-cli/doctor-command, wp-cli/profile-command). The wp-cli/wp-cli dependency is essential for Packagist to properly classify and resolve the package. The extra.commands block is the standard way WP-CLI packages declare their commands for documentation purposes.

Alternatives Considered

1. Only add the dependency: Would work for Packagist but miss the opportunity to improve discoverability with keywords and command metadata.
2. Keep PHP 5.3.29 minimum: Not viable since wp-cli/wp-cli ^2.5 requires PHP 5.6+, and PHP 5.3 has been EOL since 2014.

🔧 Changes Made

Files Modified

• composer.json — Added wp-cli dependency, keywords, commands metadata, fixed license
• .gitattributes — Fixed filename case, added composer.lock exclusion
• README.md — Added Installation section with Packagist method

Detailed Changes

1. composer.json

Before:

{
  "name": "gravityforms/gravityformscli",
  "description": "A set of WP-CLI commands to manage Gravity Forms.",
  "type": "wp-cli-package",
  "homepage": "https://github.com/gravityforms/gravityformscli",
  "support": {
    "issues": "https://gravityforms.com"
  },
  "license": "GPLv3",
  "authors": [
    {
      "name": "Rocketgenius",
      "email": "contact@rocketgenius.com",
      "homepage": "http://www.gravityforms.com"
    }
  ],
  "require": {
    "php": ">=5.3.29"
  },
  "autoload": {
    "files": [ "cli.php" ]
  }
}

After:

{
  "name": "gravityforms/gravityformscli",
  "description": "A set of WP-CLI commands to manage Gravity Forms.",
  "type": "wp-cli-package",
  "keywords": [
    "wp-cli",
    "gravity-forms",
    "cli",
    "wordpress"
  ],
  "homepage": "https://github.com/gravityforms/gravityformscli",
  "support": {
    "issues": "https://gravityforms.com"
  },
  "license": "GPL-3.0-or-later",
  "authors": [
    {
      "name": "Rocketgenius",
      "email": "contact@rocketgenius.com",
      "homepage": "http://www.gravityforms.com"
    }
  ],
  "require": {
    "php": ">=5.6",
    "wp-cli/wp-cli": "^2.5"
  },
  "autoload": {
    "files": [ "cli.php" ]
  },
  "extra": {
    "commands": [
      "gf",
      "gf form",
      "gf field",
      "gf entry",
      "gf license",
      "gf tool"
    ]
  }
}

Why This Works:

• wp-cli/wp-cli ^2.5: This is the critical dependency that enables Packagist to properly resolve the package. When users run wp package install gravityforms/gravityformscli, Composer uses this dependency to verify compatibility with their WP-CLI installation.
• keywords: Packagist indexes these for search. Users searching for "wp-cli gravity forms" will find the package.
• extra.commands: The standard WP-CLI convention for declaring commands. Used by the WP-CLI package index and wp package browse for command documentation.
• GPL-3.0-or-later: Fixes the Composer validation warning. GPLv3 is not a valid SPDX identifier; GPL-3.0-or-later is the correct format per the SPDX specification.
• PHP >=5.6: Required since wp-cli/wp-cli ^2.5 itself requires PHP 5.6+. PHP 5.3 has been end-of-life since August 2014.

Impact:

• ✅ composer validate passes with zero warnings
• ✅ Package becomes installable via wp package install
• ✅ Improved discoverability on Packagist search
• ✅ WP-CLI commands properly documented in package metadata

2. .gitattributes

Before:

# Files
/.gitattributes export-ignore
/.gitignore export-ignore
/change_log.txt export-ignore
/readme.md export-ignore

After:

# Files
/.gitattributes export-ignore
/.gitignore export-ignore
/change_log.txt export-ignore
/README.md export-ignore
/composer.lock export-ignore

Why This Works:

• The actual file is README.md (capital letters), but the export-ignore rule referenced readme.md. Git is case-sensitive on Linux systems, so this rule was silently failing on CI/CD and Linux-based servers.
• composer.lock is excluded because it should not be distributed in library/package archives — only in application repositories.

Impact:

• ✅ README.md correctly excluded from Composer archive downloads
• ✅ composer.lock excluded from distribution archives

3. README.md

Added an Installation section before "Getting started" with three installation methods:

Installation
------------

**As a WP-CLI package (recommended):**

    wp package install gravityforms/gravityformscli

**As a WordPress plugin:**

    wp plugin install gravityformscli --activate

**Or install from GitHub:**

    wp package install https://github.com/gravityforms/gravityformscli.git

Why This Works:
Once published on Packagist, users need clear documentation on the recommended installation method. The Packagist method is listed first as it installs the package correctly as a WP-CLI extension rather than a WordPress plugin.

Impact:

• ✅ Users immediately see how to install via Packagist
• ✅ Alternative methods still documented for flexibility

🧪 Testing Performed

Automated Validation

$ composer validate
./composer.json is valid

✅ composer.json passes validation with zero errors and zero warnings.

Manual Verification

• ✅ Verified only 3 intended files are modified (no unintended changes)
• ✅ Confirmed gravityforms/ directory is not included in any commits
• ✅ Reviewed diff to ensure all changes match the planned implementation
• ✅ Verified .gitattributes case matches actual filename

Post-Merge Verification (for maintainers)

After merging and submitting to Packagist:

wp package install gravityforms/gravityformscli
wp gf --help

📊 Performance Impact

N/A — This PR modifies only metadata and documentation files. No runtime PHP code is changed, so there is zero performance impact on the plugin's execution.

🔒 Security Considerations

• N/A — No runtime code changes. Only composer.json metadata, .gitattributes distribution rules, and README.md documentation are modified.

♿ Accessibility

• N/A — No UI changes.

🌍 Internationalization

• N/A — No translatable strings added or modified.

⚠️ Breaking Changes

✅ No breaking changes — Fully backward compatible.

• The package continues to work as a WordPress plugin
• Existing wp package install https://github.com/gravityforms/gravityformscli.git installation method still works
• The PHP minimum version change from 5.3 to 5.6 has no practical impact since WP-CLI 2.x already requires PHP 5.6+

📋 Post-Merge Steps for Maintainers

After merging this PR, two manual steps are needed:

1. Submit to Packagist: Go to packagist.org/packages/submit and submit https://github.com/gravityforms/gravityformscli
2. Create a v1.8 tag: The codebase is at version 1.8 but the latest tag is v1.7. Creating a new tag ensures Packagist picks up the correct version:

   git tag v1.8
   git push --tags

✅ PR Checklist

• Code follows WordPress Coding Standards
• No runtime PHP code modified
• No breaking changes
• Backward compatible
• composer validate passes clean
• Self-reviewed for quality
• Documentation updated (README.md)
• .gitattributes corrected for distribution

---

Ready for Review ✨

This PR is ready for review and merge. Once merged, the maintainers can submit the package to Packagist and users will be able to install it with wp package install gravityforms/gravityformscli.