Skip to content

Commit 030959e

Browse files
L-SophatL-Sophat
authored
Merge pull request #4 from pphatdev/feature-whereami
Feature whereami
2 parents 9e8c63a + 00f25ea commit 030959e

9 files changed

Lines changed: 711 additions & 1 deletion

‎README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ Download the latest MSI installer from [Releases](https://github.com/pphatdev/ph
3939
phat help
4040
```
4141

42+
> **Note**: Phat is designed for Windows Command Prompt or PowerShell. If using Git Bash or other bash terminals, see the [Git Bash compatibility guide](docs/git-bash-compatibility.md).
43+
4244
## Commands
4345

4446
### Show version
@@ -198,16 +200,32 @@ dotnet build ./installer/Phat.wixproj -c Release -p:ProductVersion=1.0.0
198200

199201
## Troubleshooting
200202

203+
📖 **For detailed troubleshooting solutions, see [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)**
204+
205+
### PowerShell Execution Policy Error
206+
207+
If you see "cannot be loaded. The file is not digitally signed" error:
208+
209+
1. Open PowerShell as Administrator
210+
2. Run: `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`
211+
3. Run: `Unblock-File "C:\Program Files (x86)\Phat\phat.ps1"`
212+
213+
➡️ **[Full solution guide](docs/powershell-execution-policy.md)**
214+
201215
### Permission Errors
202216

203217
Run your terminal as **Administrator** if you encounter permission errors when switching PHP versions.
204218

219+
➡️ **[Full solution guide](docs/permission-denied.md)**
220+
205221
### Apache Won't Start
206222

207223
1. Check Apache error logs at `C:\xampp\apache\logs\error.log`
208224
2. Ensure the correct PHP DLL files exist in the PHP directory
209225
3. Verify `httpd-xampp.conf` has the correct PHP module configuration
210226

227+
➡️ **[Full solution guide](docs/apache-wont-start.md)**
228+
211229
### VHost Warnings
212230

213231
Apache virtual host warnings (e.g., `Could not resolve host name`) are unrelated to PHP switching — they come from your virtual host configuration in `httpd-vhosts.conf`.

‎docs/TROUBLESHOOTING.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Troubleshooting Guide
2+
3+
This guide covers common issues you might encounter when using Phat. Each issue has its own detailed documentation page.
4+
5+
## Quick Navigation
6+
7+
### 🔒 Security & Permissions
8+
- **[PowerShell Execution Policy Error](powershell-execution-policy.md)** - "File cannot be loaded. The file is not digitally signed"
9+
- **[Permission Denied When Installing](permission-denied.md)** - Access denied errors during installation
10+
11+
### ⚙️ Installation & Setup
12+
- **[Download Fails](download-fails.md)** - Issues downloading PHP versions
13+
- **[Git Bash / MINGW64 Compatibility](git-bash-compatibility.md)** - "command not found" in bash terminals
14+
15+
### 🔧 Operation Issues
16+
- **[Apache Won't Start After Switching](apache-wont-start.md)** - Apache fails to start after changing PHP versions
17+
- **[PHP Version Not Found](php-version-not-found.md)** - Version not detected even though it's installed
18+
19+
---
20+
21+
## Most Common Issues
22+
23+
### 1. PowerShell Execution Policy Error
24+
25+
**Symptoms:**
26+
```
27+
phat : File C:\Program Files (x86)\Phat\phat.ps1 cannot be loaded. The file is not digitally signed.
28+
```
29+
30+
**Quick Fix:**
31+
```powershell
32+
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
33+
Unblock-File "C:\Program Files (x86)\Phat\phat.ps1"
34+
```
35+
36+
➡️ **[Full solution guide](powershell-execution-policy.md)**
37+
38+
---
39+
40+
### 2. Command Not Found in Git Bash
41+
42+
**Symptoms:**
43+
```bash
44+
$ phat
45+
bash: phat: command not found
46+
```
47+
48+
**Quick Fix:** Use PowerShell or CMD instead, or add bash alias:
49+
```bash
50+
phat() {
51+
powershell.exe -ExecutionPolicy Bypass -File "C:/Program Files (x86)/Phat/phat.ps1" "$@"
52+
}
53+
```
54+
55+
➡️ **[Full solution guide](git-bash-compatibility.md)**
56+
57+
---
58+
59+
### 3. Permission Denied When Installing
60+
61+
**Symptoms:** Access denied errors during `phat install`
62+
63+
**Quick Fix:** Run PowerShell as Administrator
64+
65+
➡️ **[Full solution guide](permission-denied.md)**
66+
67+
---
68+
69+
## Getting Help
70+
71+
If you're still experiencing issues after checking the guides above:
72+
73+
1. Check the [README.md](../README.md) for usage instructions
74+
2. Verify your XAMPP installation is at `C:\xampp`
75+
3. Run `phat whereami` to verify installation paths
76+
4. Open an issue on GitHub with:
77+
- The exact error message
78+
- Output of `phat whereami`
79+
- Output of `Get-ExecutionPolicy -List` (if PowerShell issue)
80+
- Your Windows version
81+
82+
## Diagnostic Commands
83+
84+
Run these commands to gather diagnostic information:
85+
86+
```powershell
87+
# Check Phat installation
88+
phat whereami
89+
90+
# Check PHP versions
91+
phat list
92+
93+
# Check PowerShell execution policy
94+
Get-ExecutionPolicy -List
95+
96+
# Check if running as administrator
97+
([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
98+
```
99+
100+
## Related Resources
101+
102+
- [PowerShell Execution Policies Documentation](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies)
103+
- [XAMPP Documentation](https://www.apachefriends.org/docs/)
104+
- [PHP Windows Downloads](https://windows.php.net/download/)
105+

‎docs/apache-wont-start.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Apache Won't Start After Switching
2+
3+
## Problem
4+
5+
Apache service fails to start after switching PHP versions.
6+
7+
## Cause
8+
9+
Apache processes may still be running in the background, or there might be configuration issues with the new PHP version.
10+
11+
## Solutions
12+
13+
### Step 1: Check for Running Apache Processes
14+
15+
```powershell
16+
Get-Process -Name httpd -ErrorAction SilentlyContinue
17+
```
18+
19+
### Step 2: Kill Any Remaining Apache Processes
20+
21+
```powershell
22+
Get-Process -Name httpd | Stop-Process -Force
23+
```
24+
25+
### Step 3: Try Switching Again
26+
27+
```powershell
28+
phat switch [version]
29+
```
30+
31+
## Additional Troubleshooting
32+
33+
### Check Apache Error Logs
34+
35+
Look for detailed error messages in:
36+
37+
```
38+
C:\xampp\apache\logs\error.log
39+
```
40+
41+
### Verify PHP DLL Files
42+
43+
Ensure the correct PHP DLL files exist in the PHP directory:
44+
- For PHP 7.x: `php7ts.dll` and `php7apache2_4.dll`
45+
- For PHP 8.x: `php8ts.dll` and `php8apache2_4.dll`
46+
47+
### Verify Apache Configuration
48+
49+
Check that `httpd-xampp.conf` has the correct PHP module configuration:
50+
51+
```
52+
C:\xampp\apache\conf\extra\httpd-xampp.conf
53+
```
54+
55+
Look for lines like:
56+
```apache
57+
LoadFile "C:/xampp/php/php8ts.dll"
58+
LoadModule php_module "C:/xampp/php/php8apache2_4.dll"
59+
```
60+
61+
## Manual Apache Control
62+
63+
If automatic switching fails, you can manually control Apache:
64+
65+
**Stop Apache:**
66+
```powershell
67+
C:\xampp\apache_stop.bat
68+
```
69+
70+
**Start Apache:**
71+
```powershell
72+
C:\xampp\apache_start.bat
73+
```
74+
75+
## Related Resources
76+
77+
- [XAMPP Documentation](https://www.apachefriends.org/docs/)
78+
- [Back to Troubleshooting Index](TROUBLESHOOTING.md)

‎docs/download-fails.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Download Fails
2+
3+
## Problem
4+
5+
Running `phat install [version]` fails to download PHP.
6+
7+
## Common Causes
8+
9+
1. No internet connection
10+
2. PHP version doesn't exist
11+
3. Network firewall blocking the download
12+
4. Windows PHP download site is temporarily down
13+
14+
## Solutions
15+
16+
### Solution 1: Check Your Internet Connection
17+
18+
Verify you can access the internet:
19+
20+
```powershell
21+
Test-NetConnection windows.php.net -Port 443
22+
```
23+
24+
If this fails, check your network connection.
25+
26+
### Solution 2: Verify the Version Exists
27+
28+
Check what versions are actually available:
29+
30+
```powershell
31+
phat list --php --global
32+
```
33+
34+
This fetches the current list of stable PHP versions from windows.php.net.
35+
36+
### Solution 3: Try a Different Version
37+
38+
The version you want might not be available for Windows. Try a different version from the list:
39+
40+
```powershell
41+
# Example: if 8.2.27 doesn't exist, try 8.2.26
42+
phat install 8.2.26
43+
```
44+
45+
### Solution 4: Manual Download
46+
47+
If automatic download fails, you can download manually:
48+
49+
1. Visit [PHP for Windows Downloads](https://windows.php.net/download/)
50+
2. Download the **Thread Safe (TS) x64** version
51+
3. Extract to `C:\xampp\php[version]`
52+
- Example: `C:\xampp\php8.2.27`
53+
4. Run `phat list` to verify it's detected
54+
55+
### Solution 5: Check Firewall/Antivirus
56+
57+
Your firewall or antivirus might be blocking downloads:
58+
59+
1. Temporarily disable your antivirus
60+
2. Try the download again
61+
3. Re-enable your antivirus after installation
62+
63+
### Solution 6: Use Archives
64+
65+
Older PHP versions are in the archives. Check:
66+
- [PHP Release Archives](https://windows.php.net/downloads/releases/archives/)
67+
68+
## Understanding Version Availability
69+
70+
### Thread Safe vs Non-Thread Safe
71+
72+
⚠️ **Important**: Phat only downloads **Thread Safe (TS)** versions because they're required for Apache module mode.
73+
74+
### Compiler Versions
75+
76+
PHP for Windows comes in different compiler versions:
77+
- **VS17** (Visual Studio 2022) - PHP 8.2+
78+
- **VS16** (Visual Studio 2019) - PHP 7.4 - 8.1
79+
- **VS15** (Visual Studio 2017) - Older PHP versions
80+
81+
Phat automatically tries the correct compiler version for your PHP version.
82+
83+
## Checking Download URL
84+
85+
If you want to verify the download URL manually:
86+
87+
For PHP 8.2.27, the URL would be:
88+
```
89+
https://windows.php.net/downloads/releases/php-8.2.27-Win32-vs17-x64.zip
90+
```
91+
92+
Try accessing this in your browser to see if it exists.
93+
94+
## Error Messages
95+
96+
### "Could not find PHP X.X.X for download"
97+
98+
This means the exact version doesn't exist on windows.php.net. Try:
99+
1. Check available versions: `phat list --php --global`
100+
2. Install a version from that list
101+
102+
### "Download failed - Connection refused"
103+
104+
Network issue. Check:
105+
1. Internet connection
106+
2. Firewall settings
107+
3. Proxy settings (if applicable)
108+
109+
### "Extraction failed"
110+
111+
The downloaded file might be corrupted:
112+
1. Delete the temp file: `C:\Users\[YourUser]\AppData\Local\Temp\phat_download\`
113+
2. Try downloading again
114+
115+
## Manual Installation Steps
116+
117+
If all else fails, install manually:
118+
119+
1. Download PHP from [windows.php.net](https://windows.php.net/download/)
120+
- Choose: **Thread Safe (TS) x64**
121+
122+
2. Extract to XAMPP directory:
123+
```
124+
C:\xampp\php8.2.27
125+
```
126+
127+
3. Copy `php.ini-development` to `php.ini`:
128+
```powershell
129+
Copy-Item "C:\xampp\php8.2.27\php.ini-development" "C:\xampp\php8.2.27\php.ini"
130+
```
131+
132+
4. Switch to the new version:
133+
```powershell
134+
phat switch 8.2.27
135+
```
136+
137+
## Related Resources
138+
139+
- [PHP Windows Downloads](https://windows.php.net/download/)
140+
- [PHP Release Archives](https://windows.php.net/downloads/releases/archives/)
141+
- [Back to Troubleshooting Index](TROUBLESHOOTING.md)

0 commit comments

Comments
 (0)