PHP, Node, Python and Ruby versions

This handbook covers MixEngine through the mix command line. If you would rather work in a graphical interface, download the MixDB app at https://lab.mixnz.com/#mixdb. MixDB drives the same MixEngine, so everything in this handbook still applies.

MixEngine installs language runtimes into its own directory, one immutable folder per version, and never touches whatever your operating system already has. Installing a version never modifies a version already installed, so nothing you have working can be broken by adding something new.

Four languages are managed: PHP, Node.js, Python and Ruby.

Installing a version

mix runtime available --kind php
mix runtime install php 8.3.33
mix runtime list

The version is exact, and that is deliberate rather than an omission. 8.3 asks "choose one for me", and there is nothing to choose from until something is installed — choosing between versions is what resolution does, and resolution answers with what is on the machine. mix runtime available is where a range belongs.

An install is a job, and mix waits for it by default: mix runtime install php 8.3.33 && … is a sentence about PHP being there. --no-wait returns as soon as the daemon has accepted the work and hands you a job id, which mix job wait can be pointed at later.

Installing a PHP also creates its php-fpm pool — php-fpm@8.3.33, a service like any other, in mix service list. Node, Python and Ruby are invoked per command and have nothing supervised.

On a Windows PC with an ARM processor

Some versions have no build made for that processor — nobody publishes an ARM64 Windows PHP, for instance. Where that is so, MixEngine installs the x86_64 build instead and Windows runs it for you. It works; it is a little slower than a build made for your machine would be.

You are never left to guess which is which. mix runtime available and mix package available grow a RUNS column on that machine, saying native or emulated per version, and the install says so before it starts downloading. On every other machine the column is not there, because there is nothing for it to say.

Choosing which one a directory uses

Nothing here changes a shell, patches a profile, or asks you to type an activate command. A directory resolves to a version, and the shims do the rest.

mix runtime default php 8.3.33      # the machine-wide fallback
mix project update blog --pin php=^8.1
mix runtime resolve php             # what does *this* directory get, and why?

mix runtime resolve is the command to remember. It answers what php -v would answer, without running anything, and it names which of four sources decided it:

1. An explicit flag or environment variable on the command being run.
2. The nearest mixengine.toml that names this language, walking up from where you are.
3. The registered project covering this directory.
4. The global default.

A mixengine.toml that says nothing about PHP is not an answer about PHP, so a pin further up still applies.

Writing a constraint

Pins and --version accept three shapes, all resolved against installed versions and never silently against downloadable ones:

A constraint with no pre-release in it never selects one. 8.5 and ^8.5 both pass over 8.5.0RC1; naming it exactly is how you ask for it.

The shims

mix path install fills <root>/bin and puts that one directory on your PATH. It holds a small program per command — php, php-config, pecl, composer, node, npm, npx, python, pip, ruby, gem, bundle — and each one works out which version this directory wants and hands over to the real binary.

Two things follow that are worth knowing:

• It works with the daemon stopped. A shim reads what it needs directly rather than asking over a socket, which is why php -v in a project still answers when MixEngine is not running.
• There is nothing to refresh after an install. The list of commands is fixed, so <root>/bin does not depend on what you have installed. A node shim on a machine with no Node.js resolves nothing and tells you which command to type.

Only <root>/bin goes on your PATH — one entry, never a directory per version.

mix path status
mix path uninstall

mix path uninstall takes the directory back off your PATH and leaves the commands where they are: they live inside MixEngine's own home, and removing the home is what removes them.

PHP extensions

Extensions are per installed version, because that is what they are compiled against:

mix runtime ext list --php 8.3.33
mix runtime ext enable redis --php 8.3.33
mix runtime ext disable xdebug --php 8.3.33

list says which extensions the build has and why each one is on or off, which is usually the question. Leaving --php out means the version this directory resolves to.

Enabling loads the extension on every PHP process of that version, the pool included.

Removing a version

mix runtime uninstall php 8.1.31

This is refused while a registered project pins that version — the projects are named — and while the php-fpm pool running out of it is running. --force crosses the first of those and never the second.

This page as Markdown: https://mixnz.github.io/mixengine/en/runtimes.md