Skip to content

Commit a1b5e9a

Browse files
ThavarshanThavarshan
committed
docs: update README.md for version 1.11.0 — add new features and commands
1 parent fda23d1 commit a1b5e9a

1 file changed

Lines changed: 151 additions & 36 deletions

File tree

‎README.md‎

Lines changed: 151 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414

1515
```sh
1616
$ phpvm version
17-
phpvm version 1.10.0
17+
phpvm version 1.11.0
1818

1919
PHP Version Manager for macOS and Linux
2020
Author: Jerome Thayananthajothy <tjthavarshan@gmail.com>
@@ -38,11 +38,21 @@ PHP 8.1.13
3838

3939
- Install and manage multiple PHP versions.
4040
- Seamlessly switch between installed PHP versions.
41+
- **Run commands with a specific PHP version** without globally switching (`phpvm exec`, `phpvm run`).
42+
- **List available remote PHP versions** from your system package manager (`phpvm ls-remote`).
43+
- **Resolve version descriptors and aliases** to installed version numbers (`phpvm resolve`).
4144
- Auto-switch PHP versions based on project `.phpvmrc` (configurable depth via `PHPVM_PHPVMRC_MAX_DEPTH`).
4245
- Automatic directory-based switching via built-in cd hook (`PROMPT_COMMAND` for bash, `chpwd` for zsh).
46+
- **Auto-set `default` alias** on first `phpvm install` (matches nvm behaviour).
4347
- Alias management for versions (`phpvm alias`, `phpvm unalias`).
4448
- Built-in version shortcuts: `latest`, `stable`, and user-defined aliases.
45-
- Cache directory inspection (`phpvm cache dir`).
49+
- **Bash tab completion** — context-aware completions for commands, versions, and aliases (auto-loaded on source).
50+
- **`--no-use` flag** for sourcing without auto-switch or cd hook registration (`source phpvm.sh --no-use`).
51+
- **Unload phpvm** from the current shell session (`phpvm unload`).
52+
- Cache management: inspect (`phpvm cache dir`) and clear (`phpvm cache clear`).
53+
- **`PHPVM_BIN` export** — active PHP binary directory exported after every version switch.
54+
- **`XDG_CONFIG_HOME` fallback** — `PHPVM_DIR` respects `$XDG_CONFIG_HOME/phpvm` when set.
55+
- **Improved `phpvm list` output** with `->` marker for the active version and `(default)` annotation.
4656
- System information and debugging (`phpvm info`).
4757
- Supports macOS (via Homebrew) and Linux distributions including WSL.
4858
- **Smart repository detection** for RHEL/Fedora systems with automatic setup guidance.
@@ -95,24 +105,29 @@ If the installation was successful, it should output the path to `phpvm`.
95105

96106
### Available Commands
97107

98-
| Command | Description |
99-
| --------------------------- | ------------------------------------------------------------------------- |
100-
| `phpvm install [version]` | Install a PHP version (reads `.phpvmrc` if no version given) |
101-
| `phpvm use [version]` | Switch PHP version (reads `.phpvmrc` → default alias if no version given) |
102-
| `phpvm uninstall <version>` | Remove a specific PHP version |
103-
| `phpvm current` | Display the currently active PHP version |
104-
| `phpvm which [version]` | Show the path to PHP binary for a version |
105-
| `phpvm deactivate` | Temporarily disable phpvm and restore PATH |
106-
| `phpvm system` | Switch to system/Homebrew default PHP |
107-
| `phpvm auto` | Auto-switch based on `.phpvmrc` file |
108-
| `phpvm list` or `phpvm ls` | List all installed PHP versions |
109-
| `phpvm alias [name] [ver]` | Create, update, or list version aliases |
110-
| `phpvm unalias <name>` | Remove version alias |
111-
| `phpvm cache dir` | Show phpvm cache directory |
112-
| `phpvm info` | Show system information for debugging |
113-
| `phpvm version` | Show version information |
114-
| `phpvm --version` / `-v` | Show version information (aliases) |
115-
| `phpvm help` | Show help message |
108+
| Command | Description |
109+
| ------------------------------------------ | ------------------------------------------------------------------------- |
110+
| `phpvm install [version]` | Install a PHP version (reads `.phpvmrc` if no version given) |
111+
| `phpvm use [version]` | Switch PHP version (reads `.phpvmrc` → default alias if no version given) |
112+
| `phpvm uninstall <version>` | Remove a specific PHP version |
113+
| `phpvm current` | Display the currently active PHP version |
114+
| `phpvm which [version]` | Show the path to PHP binary for a version |
115+
| `phpvm exec <version> <command> [args...]` | Run a command with a specific PHP version (subshell isolation) |
116+
| `phpvm run <version> [script] [args...]` | Run a PHP script with a specific version |
117+
| `phpvm deactivate` | Temporarily disable phpvm and restore PATH |
118+
| `phpvm unload` | Remove phpvm from the current shell session |
119+
| `phpvm system` | Switch to system/Homebrew default PHP |
120+
| `phpvm auto` | Auto-switch based on `.phpvmrc` file |
121+
| `phpvm list` or `phpvm ls` | List all installed PHP versions |
122+
| `phpvm ls-remote [pattern]` | List available remote PHP versions |
123+
| `phpvm resolve <version\|alias>` | Resolve a version descriptor to an installed version |
124+
| `phpvm alias [name] [ver]` | Create, update, or list version aliases |
125+
| `phpvm unalias <name>` | Remove version alias |
126+
| `phpvm cache <dir\|clear>` | Show or clear the phpvm cache directory |
127+
| `phpvm info` | Show system information for debugging |
128+
| `phpvm version` | Show version information |
129+
| `phpvm --version` / `-v` | Show version information (aliases) |
130+
| `phpvm help` | Show help message |
116131

117132
### Installing PHP Versions
118133

@@ -236,7 +251,17 @@ To list all installed PHP versions:
236251
phpvm list
237252
```
238253

239-
This will show all installed PHP versions and indicate the currently active one.
254+
The active version is marked with `->` and highlighted in green. If a `default` alias is set, it is annotated inline:
255+
256+
```
257+
Installed PHP versions:
258+
-> 8.2 (default)
259+
8.1
260+
8.0
261+
system
262+
263+
Active version: 8.2
264+
```
240265

241266
### Managing Aliases
242267

@@ -274,14 +299,20 @@ phpvm use latest
274299
phpvm use stable
275300
```
276301

277-
### Cache Directory
302+
### Cache Management
278303

279304
Show the phpvm cache directory:
280305

281306
```sh
282307
phpvm cache dir
283308
```
284309

310+
Clear all cached files:
311+
312+
```sh
313+
phpvm cache clear
314+
```
315+
285316
### System Information
286317

287318
Show system details for debugging:
@@ -300,14 +331,97 @@ To remove a specific PHP version:
300331
phpvm uninstall 7.4
301332
```
302333

303-
### Planned Commands (Coming Soon)
334+
### Running Commands with a Specific PHP Version
335+
336+
Use `phpvm exec` to run any command with a specific PHP version without globally switching. The command executes in a subshell, so your current shell session is unaffected:
337+
338+
```sh
339+
# Run composer install with PHP 8.2
340+
phpvm exec 8.2 composer install
341+
342+
# Run a linter with PHP 8.1
343+
phpvm exec 8.1 ./vendor/bin/phpstan analyse
344+
```
345+
346+
Use `phpvm run` as a shortcut for `phpvm exec <version> php`:
347+
348+
```sh
349+
# Run a PHP script with PHP 8.1
350+
phpvm run 8.1 script.php arg1 arg2
351+
352+
# Equivalent to:
353+
phpvm exec 8.1 php script.php arg1 arg2
354+
```
355+
356+
Both commands resolve aliases and keywords (`default`, `latest`, `stable`) before execution.
357+
358+
### Listing Available Remote Versions
359+
360+
List PHP versions available for installation from your system package manager:
361+
362+
```sh
363+
phpvm ls-remote
364+
```
365+
366+
Filter by pattern:
367+
368+
```sh
369+
phpvm ls-remote 8.2
370+
```
371+
372+
Supported package managers: Homebrew, apt, dnf, yum, and pacman.
373+
374+
### Resolving Versions
375+
376+
Resolve a version descriptor, alias, or keyword to a locally installed version number:
377+
378+
```sh
379+
# Resolve an alias
380+
phpvm resolve default # → 8.2
381+
382+
# Resolve a keyword
383+
phpvm resolve latest # → 8.3
384+
385+
# Pass through a concrete version (if installed)
386+
phpvm resolve 8.1 # → 8.1
387+
```
388+
389+
This is useful in CI scripts or tooling that needs to know which version an alias points to.
390+
391+
### Unloading phpvm
304392

305-
The following commands are in progress and may return a "not yet implemented" message:
393+
Remove phpvm from the current shell session entirely:
394+
395+
```sh
396+
phpvm unload
397+
```
398+
399+
This deactivates phpvm, removes the cd hook, and unsets all phpvm functions and variables. To use phpvm again, re-source it:
400+
401+
```sh
402+
source ~/.phpvm/phpvm.sh
403+
```
404+
405+
### Tab Completion
406+
407+
phpvm includes built-in bash tab completion that is automatically loaded when phpvm is sourced. It provides context-aware completions for:
408+
409+
- All phpvm commands
410+
- Installed PHP versions (for `use`, `uninstall`, `which`, `exec`, `run`, `resolve`)
411+
- Alias names (for `unalias`)
412+
- Cache subcommands (`dir`, `clear`)
413+
414+
No additional setup is required — completions are loaded from `$PHPVM_DIR/completions/phpvm.bash`.
415+
416+
### Sourcing with `--no-use`
417+
418+
Load phpvm functions without triggering auto-switch or registering the cd hook:
419+
420+
```sh
421+
source ~/.phpvm/phpvm.sh --no-use
422+
```
306423

307-
- `phpvm exec <version> <command> [args...]` — execute a command with a specific PHP version
308-
- `phpvm run <version> [script] [args...]` — run a PHP script with a specific version
309-
- `phpvm ls-remote [pattern]` — list available remote PHP versions
310-
- `phpvm cache clear` — clear the phpvm cache
424+
This is useful for lazy-loading setups where you want phpvm functions available but don't want automatic version switching on shell startup.
311425

312426
### Exit Codes
313427

@@ -336,14 +450,15 @@ fi
336450

337451
## Environment Variables
338452

339-
| Variable | Default | Description |
340-
| ------------------------- | ---------- | ---------------------------------------------------------------- |
341-
| `PHPVM_DIR` | `~/.phpvm` | Installation directory |
342-
| `PHPVM_AUTO_USE` | `true` | Enable automatic `.phpvmrc` detection when sourced |
343-
| `PHPVM_PHPVMRC_MAX_DEPTH` | `25` | Max parent directories to traverse when searching for `.phpvmrc` |
344-
| `PHPVM_DEBUG` | `false` | Enable debug logging with timestamps |
345-
| `NO_COLOR` | _(unset)_ | Disable color output ([no-color.org](https://no-color.org/)) |
346-
| `PHPVM_LOG_TIMESTAMPS` | `false` | Always show timestamps in log output |
453+
| Variable | Default | Description |
454+
| ------------------------- | ---------- | ---------------------------------------------------------------------------------------- |
455+
| `PHPVM_DIR` | `~/.phpvm` | Installation directory (falls back to `$XDG_CONFIG_HOME/phpvm` if `XDG_CONFIG_HOME` set) |
456+
| `PHPVM_BIN` | _(export)_ | Active PHP binary directory (set after version switch, unset on deactivate) |
457+
| `PHPVM_AUTO_USE` | `true` | Enable automatic `.phpvmrc` detection when sourced |
458+
| `PHPVM_PHPVMRC_MAX_DEPTH` | `25` | Max parent directories to traverse when searching for `.phpvmrc` |
459+
| `PHPVM_DEBUG` | `false` | Enable debug logging with timestamps |
460+
| `NO_COLOR` | _(unset)_ | Disable color output ([no-color.org](https://no-color.org/)) |
461+
| `PHPVM_LOG_TIMESTAMPS` | `false` | Always show timestamps in log output |
347462

348463
## Uninstallation
349464

0 commit comments

Comments
 (0)