ENCODING CORRUPTION - DOCUMENTATION AND SOLUTION GUIDE
========================================================
This document explains the encoding issue that affected this project and how to prevent recurrence.

PROBLEM DIAGNOSED
=================
Three PHP files contained encoding corruption:
- app/Models/ChartOfAccount.php
- app/Http/Controllers/Accounting/ChartOfAccountController.php
- database/migrations/2023_06_02_000002_create_chart_of_accounts_table.php

Symptoms of Corruption:
• BOM (Byte Order Mark) at file beginning: EF BB BF hex bytes
• Invisible control characters in line breaks
• PHP parse errors despite clean appearance in IDE
• Cannot manually edit without propagating corruption

ROOT CAUSE
==========
PowerShell's Set-Content with -Encoding UTF8 parameter automatically adds:
1. BOM (3 bytes) - a signature marker at file start
2. Control characters and escape sequences
3. These become embedded in the actual file bytes

PowerShell did this even though the file appeared normal in VS Code and PhpStorm.

SOLUTION APPLIED
=================
All affected files were repaired using PHP's file functions (not PowerShell):
1. Detected and removed BOM marker (EF BB BF)
2. Removed control/escape characters
3. Normalized line endings to LF (Unix standard)
4. Verified PHP syntax validity

Files are now CLEAN and ready for use.

VERIFICATION
============
To verify a file has no BOM corruption:
php -r "echo (ord(file_get_contents('app/Models/ChartOfAccount.php',0,null,0,1)) === 60 ? 'CLEAN' : 'CORRUPTED');"

Output should be: CLEAN
(meaning file starts with '<' character, not BOM)

DEVELOPER GUIDELINES - REQUIRED
================================

✅ SAFE METHODS (Approved):

1. Edit in VS Code:
   • Settings → File Encodings: utf8
   • Settings → End of Line: LF
   • Settings → Insert Final Newline: true
   • Save the file normally

2. Edit in PhpStorm:
   • Settings → File Encodings: UTF-8
   • Settings → Line Ending: Unix (LF)
   • Edit and save normally

3. Use Git:
   • git add .
   • git commit -m "message"
   • git checkout HEAD -- filename (to recover from corruption)

4. Use Laravel CLI:
   • php artisan make:model ModelName
   • php artisan make:controller ControllerName
   • php artisan make:migration name

5. Create via PHP applications:
   • Files created by Laravel, PHP scripts use correct encoding

❌ FORBIDDEN METHODS (Never use these):

• PowerShell Set-Content:
  Set-Content -Path 'file.php' -Encoding UTF8  ← WRONG
  Out-File -Path 'file.php' -Encoding UTF8    ← WRONG

• Notepad for PHP/config files
• Copying code directly from web browsers
• FTP text mode (use binary)
• Mixing line endings (CRLF vs LF)

RECOVERY IF CORRUPTION RETURNS
================================

Option 1 - Restore from Git:
git checkout HEAD -- app/Models/ChartOfAccount.php
git checkout HEAD -- app/Http/Controllers/Accounting/ChartOfAccountController.php
git checkout HEAD -- database/migrations/2023_06_02_000002_create_chart_of_accounts_table.php

Option 2 - Run fix script:
php fix.php  (creates a fresh copy from repository)

Option 3 - Contact development team

TECHNICAL DETAILS
===================

BOM (Byte Order Mark):
- 3 invisible bytes: EF BB BF in hexadecimal
- UTF-8 signature/marker that some tools add
- PHP does NOT want BOM before "<?php"
- Results in: Parse error: syntax error, unexpected character

Line Endings:
- LF (0x0A) = Unix/Linux standard ← CORRECT for this project
- CRLF (0x0D 0x0A) = Windows DOS standard ← Can cause Git issues
- CR (0x0D) = Old Mac = Deprecated

Project Configuration (.gitattributes):
- All PHP files use LF line endings
- Automatic conversion on checkout prevents issues
- Committed files always have LF

Best Practices Summary
======================

Before making any file edits:
1. Verify your editor encoding settings are UTF-8 without BOM
2. Verify line endings are set to LF
3. Make your changes
4. Save the file
5. Test locally before committing

When committing:
1. Check git status: git status
2. Add files: git add .
3. Commit: git commit -m "Clear message describing changes"
4. Push: git push origin branch-name

If something goes wrong:
1. Check this documentation
2. Run verification command above
3. Use git to restore file if needed
4. Contact team if issue persists

ENCODING SETTINGS FOR .gitattributes
=====================================
The repository includes .gitattributes with:
* text=auto
*.php text eol=lf
*.js text eol=lf
*.json text eol=lf

This ensures all developers have consistent encoding.

For questions or issues:
1. Review this file first
2. Check VS Code/PhpStorm settings
3. Try: git checkout HEAD -- filename
4. Ask development team

Documentation updated: 2025-11-02 20:09:00