Nix (PHP) Shell

Description

This package provides a Nix flake ready to use for PHP development, using the Nix package manager which can be installed on (almost) any operating system.

Available stable PHP versions from 5.6 to 8.4.

To list the available PHP versions, run:

nix flake show github:loophp/nix-shell

The added value of this package is the ability to create custom PHP builds based on your project's composer.json file. This way, you can be sure that the PHP extensions you need are available in your development environment.

The PHP extensions to use are automatically inferred from the composer.json file.

...8<...

"require": {
  "ext-intl": "*",
},
"require-dev": {
  "ext-xdebug": "*",
  "ext-pcov": "*",
}

...>8...

To load extensions from the require and required-dev sections, using the flag --impure is required. Example:

nix develop github:loophp/nix-shell#php82 --impure

How it works

This project is built on top of fossar/nix-phps, which provides a comprehensive collection of PHP versions for Nix.

The key differentiator of this project is its ability to automatically configure your PHP environment based on your project's composer.json file. It parses the require and require-dev sections of composer.json to identify required PHP extensions and compiles a custom PHP binary with exactly those extensions enabled.

Technically, this leverages a Nix feature called IFD (Import From Derivation), allowing the Nix expression to dynamically depend on the content of the composer.json file during evaluation time.

[!NOTE] IFD is a feature that is not allowed in NixOS/nixpkgs because it prevents evaluation of the Nix expression without building the derivation first.

Usage

While being extremely stable for years, flakes is an upcoming feature of the Nix package manager.

However, enabling experimental features is not mandatory. Thanks to flake-compat, you can use legacy Nix commands (like nix-shell or nix-build) which will transparently fetch and use the flake outputs.

In a shell

To work with PHP 8.2 only:

# 1. Clone the repository
# 2. Run in the repository directory
# 3. Replace `x86_64-linux` with your architecture
nix-shell -A devShells.x86_64-linux.php82

Or with flakes experimental feature enabled:

nix develop github:loophp/nix-shell#php82

or with PHP 8.2 and a couple of useful tools:

nix develop github:loophp/nix-shell#env-php82

Since the 14th of November 2022, PHP is in NTS mode by default (see #154774).

To list the available PHP versions and environments, run:

nix flake show github:loophp/nix-shell

In another flake

Step 1

Import the input:

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    nix-shell.url = "github:loophp/nix-shell";
  };

Step 2

Import the overlay:

pkgs = import inputs.nixpkgs {
  inherit system;
  overlays = [
    inputs.nix-shell.overlays.default
  ];
};

Step 3

Use the packages:

  # PHP 8.2
  pkgs.nix-shell.php82

To create your own version of PHP, use the available API function buildPhpFromComposer.

With direnv

direnv is an extension for your shell. It augments existing shells with a new feature that can load and unload environment variables depending on the current directory. You can use it within Nix (nix-direnv) and load a development environment just by changing directory.

Edit the file .envrc and add the following line:

use flake github:loophp/nix-shell#env-php-master-snapshot --impure

And it's done.

Customize PHP

To customize the PHP configuration, you can do it like this:

nix develop github:loophp/nix-shell#php82
php -c /path/to/the/config.ini <<command>>

Another option would be to create a .user.ini file within your current working directory before running the PHP environment, as such:

max_execution_time = 0
memory_limit = 2048M

Then run:

nix develop github:loophp/nix-shell#php82 --impure

The --impure flag is important to make sure that your custom .user.ini file is correctly taken in account.

Contributing

Feel free to contribute by sending pull requests. We are a usually very responsive team and we will help you going through your pull request from the beginning to the end.

For some reasons, if you can't contribute to the code and are willing to help, sponsoring is a good, sound, and safe way to show us some gratitude for the hours we invested in this package.

Sponsor me on Github and/or any of the contributors.

Thanks

• Jan Tojnar for assisting me into incorporating his own package.
• Aaron Anderse for improving the code and giving some tips.

Changelog

See CHANGELOG.md for a changelog based on git commits.

For more detailed changelogs, please check the release changelogs.