[PR #42] [MERGED] Documentation: Align structure with .NET version #42

New issue

Closed

opened 2026-02-26 17:32:17 +03:00 by kerem · 0 comments

kerem commented

2026-02-26 17:32:17 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/Corsinvest/cv4pve-api-php/pull/42
Author: @franklupo
Created: 12/9/2025
Status: ✅ Merged
Merged: 12/9/2025
Merged by: @franklupo

Base: master ← Head: docs/align-with-dotnet-structure

📝 Commits (1)

db9bb7f docs: Align documentation structure with .NET version

📊 Changes

15 files changed (+3278 additions, -2814 deletions)

View changed files

📝 .gitignore (+44 -1)
📝 README.md (+122 -62)
➕ docs/advanced.md (+439 -0)
📝 docs/api.md (+479 -93)
➕ docs/apistructure.md (+126 -0)
📝 docs/authentication.md (+245 -225)
📝 docs/common-issues.md (+544 -349)
➖ docs/configuration-guide.md (+0 -288)
➖ docs/error-handling.md (+0 -708)
➕ docs/errorhandling.md (+274 -0)
➕ docs/examples.md (+474 -0)
➕ docs/results.md (+305 -0)
➖ docs/task-management.md (+0 -532)
➕ docs/tasks.md (+226 -0)
➖ docs/usage-examples.md (+0 -556)

📄 Description

📚 Documentation Alignment

This PR aligns the PHP documentation structure with the .NET version (cv4pve-api-dotnet) for consistency across the cv4pve suite.

✨ Key Changes

📁 Documentation Structure

✅ Reorganized to match .NET repository structure
✅ Renamed files for consistency:
- error-handling.md → errorhandling.md
- task-management.md → tasks.md
- usage-examples.md → examples.md
✅ Added comprehensive documentation:
- advanced.md - Enterprise patterns, resilient operations, architecture
- apistructure.md - API navigation and structure guide
- examples.md - Practical usage examples with all major operations
- results.md - Result handling patterns and best practices
- tasks.md - Complete task management guide

📖 Content Improvements

Indexed Parameters (netN, scsiN, ipconfigN)

Added detailed explanation section matching .NET docs
Tables with all common parameters and values
Examples for Network, Disk (SCSI/VirtIO/SATA/IDE), Cloud-Init
Complete VM creation example with VirtIO and Cloud-Init

Code Quality

Fixed incorrect $vm->set([]) usage → $vm->getConfig()->updateVmAsync()
Corrected indexed parameter syntax: arrays [0 => 'value'] for updateVmAsync()
All examples use PHP 8.0+ named parameters
HTTP method mapping tables updated

Readability

Removed excessive isSuccessStatusCode() checks from basic examples:
- README: 5 → 2 occurrences (-60%)
- examples.md: 22 → 13 occurrences (-41%)
Kept checks only in error handling sections where appropriate

🛠️ Infrastructure

Enhanced .gitignore with standard PHP patterns:
- IDE files (PhpStorm, VSCode)
- OS files (Mac, Windows)
- Testing, build artifacts, environment files

📊 Statistics

+3,278 lines of new documentation
-2,814 lines of reorganized/improved content
15 files changed (6 added, 4 removed, 5 modified)

🎯 Result

All documentation now follows the same structure, organization, and quality as the .NET version while being properly adapted for PHP syntax and conventions.

🔍 Files Changed

.gitignore - Enhanced with PHP project patterns
README.md - Simplified examples, improved readability
docs/api.md - Fixed method signatures, improved examples
docs/authentication.md - Aligned structure
docs/common-issues.md - Major expansion with indexed parameters guide
docs/advanced.md - ✨ New comprehensive guide
docs/apistructure.md - ✨ New API navigation guide
docs/errorhandling.md - Renamed and improved
docs/examples.md - ✨ New practical examples
docs/results.md - ✨ New result handling guide
docs/tasks.md - Renamed and improved

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Corsinvest/cv4pve-api-php/pull/42 **Author:** [@franklupo](https://github.com/franklupo) **Created:** 12/9/2025 **Status:** ✅ Merged **Merged:** 12/9/2025 **Merged by:** [@franklupo](https://github.com/franklupo) **Base:** `master` ← **Head:** `docs/align-with-dotnet-structure` --- ### 📝 Commits (1) - [`db9bb7f`](https://github.com/Corsinvest/cv4pve-api-php/commit/db9bb7fcddc9c77c21001536901c7dac7bb725a2) docs: Align documentation structure with .NET version ### 📊 Changes **15 files changed** (+3278 additions, -2814 deletions) <details> <summary>View changed files</summary> 📝 `.gitignore` (+44 -1) 📝 `README.md` (+122 -62) ➕ `docs/advanced.md` (+439 -0) 📝 `docs/api.md` (+479 -93) ➕ `docs/apistructure.md` (+126 -0) 📝 `docs/authentication.md` (+245 -225) 📝 `docs/common-issues.md` (+544 -349) ➖ `docs/configuration-guide.md` (+0 -288) ➖ `docs/error-handling.md` (+0 -708) ➕ `docs/errorhandling.md` (+274 -0) ➕ `docs/examples.md` (+474 -0) ➕ `docs/results.md` (+305 -0) ➖ `docs/task-management.md` (+0 -532) ➕ `docs/tasks.md` (+226 -0) ➖ `docs/usage-examples.md` (+0 -556) </details> ### 📄 Description ## 📚 Documentation Alignment This PR aligns the PHP documentation structure with the .NET version (cv4pve-api-dotnet) for consistency across the cv4pve suite. ## ✨ Key Changes ### 📁 Documentation Structure - ✅ Reorganized to match .NET repository structure - ✅ Renamed files for consistency: - `error-handling.md` → `errorhandling.md` - `task-management.md` → `tasks.md` - `usage-examples.md` → `examples.md` - ✅ Added comprehensive documentation: - `advanced.md` - Enterprise patterns, resilient operations, architecture - `apistructure.md` - API navigation and structure guide - `examples.md` - Practical usage examples with all major operations - `results.md` - Result handling patterns and best practices - `tasks.md` - Complete task management guide ### 📖 Content Improvements #### Indexed Parameters (netN, scsiN, ipconfigN) - Added detailed explanation section matching .NET docs - Tables with all common parameters and values - Examples for Network, Disk (SCSI/VirtIO/SATA/IDE), Cloud-Init - Complete VM creation example with VirtIO and Cloud-Init #### Code Quality - Fixed incorrect `$vm->set([])` usage → `$vm->getConfig()->updateVmAsync()` - Corrected indexed parameter syntax: arrays `[0 => 'value']` for `updateVmAsync()` - All examples use PHP 8.0+ named parameters - HTTP method mapping tables updated #### Readability - Removed excessive `isSuccessStatusCode()` checks from basic examples: - README: 5 → 2 occurrences (-60%) - examples.md: 22 → 13 occurrences (-41%) - Kept checks only in error handling sections where appropriate ### 🛠️ Infrastructure - Enhanced `.gitignore` with standard PHP patterns: - IDE files (PhpStorm, VSCode) - OS files (Mac, Windows) - Testing, build artifacts, environment files ## 📊 Statistics - **+3,278 lines** of new documentation - **-2,814 lines** of reorganized/improved content - **15 files changed** (6 added, 4 removed, 5 modified) ## 🎯 Result All documentation now follows the same structure, organization, and quality as the .NET version while being properly adapted for PHP syntax and conventions. ## 🔍 Files Changed - `.gitignore` - Enhanced with PHP project patterns - `README.md` - Simplified examples, improved readability - `docs/api.md` - Fixed method signatures, improved examples - `docs/authentication.md` - Aligned structure - `docs/common-issues.md` - **Major expansion** with indexed parameters guide - `docs/advanced.md` - ✨ New comprehensive guide - `docs/apistructure.md` - ✨ New API navigation guide - `docs/errorhandling.md` - Renamed and improved - `docs/examples.md` - ✨ New practical examples - `docs/results.md` - ✨ New result handling guide - `docs/tasks.md` - Renamed and improved --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>