Skip to content

Latest commit

 

History

History
323 lines (231 loc) · 7.87 KB

CONTRIBUTING.md

File metadata and controls

323 lines (231 loc) · 7.87 KB

Contributing to pxp-cli

Thank you for considering contributing to pxp-cli! We welcome contributions from the community to make this tool better.

Table of Contents

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:

  • Use a clear and descriptive title
  • Describe the exact steps to reproduce the problem
  • Provide specific examples (commands you ran, expected vs actual results)
  • Include system information (Windows version, PowerShell version, XAMPP version)
  • Add relevant logs (Apache error logs, PowerShell error messages)

Example Bug Report

**Title:** Switch command fails with PHP 8.3.15

**Description:**
When trying to switch to PHP 8.3.15, the command fails with an error.

**Steps to Reproduce:**
1. Install PHP 8.3.15 using `pxp install 8.3.15`
2. Run `pxp switch 8.3.15`
3. Error occurs

**Expected behavior:**
PHP version should switch successfully

**Actual behavior:**
Error: "Cannot find PHP directory"

**System Info:**
- Windows 11 Pro (Version 23H2)
- PowerShell 5.1
- XAMPP 8.2.12
- pxp version 1.3.0

**Logs:**
[Paste relevant error messages]

Suggesting Enhancements

Enhancement suggestions are welcome! Before creating an enhancement suggestion:

  • Check if the feature already exists in a newer version
  • Check existing feature requests to avoid duplicates
  • Explain the use case - why would this feature be useful?
  • Provide examples of how the feature would work

Example Enhancement Suggestion

**Title:** Add support for PHP extensions management

**Description:**
Add commands to enable/disable PHP extensions without manually editing php.ini

**Use Case:**
Developers often need to toggle extensions like xdebug, opcache, etc. Having CLI commands would simplify this process.

**Proposed Commands:**
- `pxp extension list` - List all available extensions
- `pxp extension enable xdebug` - Enable an extension
- `pxp extension disable xdebug` - Disable an extension

**Additional Context:**
Similar to how pecl works on Linux systems.

Pull Requests

  1. Fork the repository and create your branch from main
  2. Follow the coding guidelines (see below)
  3. Test your changes thoroughly
  4. Update documentation if needed
  5. Write clear commit messages
  6. Create the pull request

Pull Request Checklist

  • Code follows the project's coding style
  • Changes have been tested locally
  • Documentation has been updated (if applicable)
  • Commit messages are clear and descriptive
  • No unnecessary files included (temp files, IDE configs, etc.)

Development Setup

Prerequisites

  • Windows 10/11
  • PowerShell 5.1 or higher
  • XAMPP installed at C:\xampp
  • Git
  • .NET SDK 6.0+ (for building MSI installer)
  • WiX Toolset (for MSI builds)

Getting Started

  1. Clone the repository:

    git clone https://github.com/pphatdev/pxp-cli.git
cd pxp-cli

  2. Test the script locally:

    # Run directly without installing
.\pxp.ps1 help

# Or use the batch file
.\pxp.bat help

  3. Make your changes in pxp.ps1

  4. Test your changes with various commands:

    .\pxp.ps1 list
.\pxp.ps1 switch 8.0.30
.\pxp.ps1 install 8.3.15
# etc.

Building the MSI Installer

# Install WiX as a .NET tool (first time only)
dotnet tool restore

# Build the installer
dotnet build ./installer/Pxp.wixproj -c Release

# Output will be in: installer\bin\Release\

Coding Guidelines

PowerShell Style

  • Indentation: 4 spaces (no tabs)
  • Line length: Aim for 100 characters max, but not strict
  • Variable naming: Use PascalCase for script variables, $camelCase for local variables
  • Functions: Use Verb-Noun naming convention (e.g., Get-PhpVersion, Stop-ApacheService)
  • Comments: Add comments for complex logic, but prefer self-documenting code
  • Error handling: Use try/catch blocks and provide helpful error messages

Example Code Style

function Get-PhpVersion {
    <#
    .SYNOPSIS
        Retrieves the PHP version from a PHP directory.
    .PARAMETER PhpDir
        Path to the PHP installation directory
    #>
    param(
        [Parameter(Mandatory = $true)]
        [string]$PhpDir
    )
    
    $exe = Join-Path $PhpDir "php.exe"
    if (-not (Test-Path $exe)) {
        Write-Warning "PHP executable not found at: $exe"
        return $null
    }
    
    return [System.Diagnostics.FileVersionInfo]::GetVersionInfo($exe).FileVersion
}

Testing

Manual Testing

Before submitting a PR, test the following scenarios:

  1. List commands:

    • pxp list
    • pxp list -php -local
    • pxp list -php -global

  2. Version display:

    • pxp -v
    • pxp --version
    • pxp current

  3. Switch commands:

    • Switch between PHP 7.x and 8.x
    • Switch to a version that doesn't exist (should error)
    • Verify Apache restarts correctly
    • Check httpd-xampp.conf is updated properly

  4. Install commands:

    • Install a new PHP version
    • Try installing an invalid version (should error)
    • Verify downloaded files

  5. Uninstall commands:

    • Uninstall a non-active PHP version
    • Try uninstalling active version (should error)

Testing Checklist

  • Tested on Windows 10
  • Tested on Windows 11
  • Works in PowerShell 5.1
  • Works in PowerShell 7+
  • Works through batch file wrapper
  • Apache starts/stops correctly
  • No data loss during switches
  • Error messages are helpful

Documentation

When adding new features or changing behavior:

  1. Update README.md with new commands/options
  2. Add troubleshooting docs if the feature might cause issues
  3. Update help text in pxp.ps1 (the Show-Help function)
  4. Add examples showing how to use the new feature

Documentation Standards

  • Use clear, concise language
  • Include code examples
  • Add screenshots if helpful (for troubleshooting guides)
  • Link related documentation

Commit Messages

Write clear, descriptive commit messages:

Format

<type>: <subject>

<body>

<footer>

Types

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, no logic change)
  • refactor: Code refactoring
  • test: Adding or updating tests
  • chore: Maintenance tasks

Examples

feat: add support for PHP extension management

- Added extension list command
- Added extension enable/disable commands
- Updated help documentation

Closes #42

fix: switch command fails with PHP 8.3.15

The version detection was not handling 3-digit builds correctly.
Fixed by updating the regex pattern in Get-PhpVersion.

Fixes #38

docs: improve troubleshooting guide for Apache errors

- Added more detailed steps
- Included common error messages
- Added links to Apache documentation

Questions?

If you have questions about contributing, feel free to:

  • Open an issue with the question label
  • Start a discussion in GitHub Discussions
  • Check existing documentation in the docs/ folder

Thank You!

Your contributions make pxp-cli better for everyone. We appreciate your time and effort! 🙏

Happy Coding! 🚀