Merge branch '1.x' into feature/transformer-loader-add-closure

.nix/php/lib/.gitignore

@@ -0,0 +1,3 @@
+php.ini
+blackfire.ini
+xdebug.ini

.nix/php/lib/blackfire.ini.dist

@@ -0,0 +1,40 @@
+[blackfire]
+; On Windows use the following configuration:
+; extension=php_blackfire.dll
+
+; Sets fine-grained configuration for Probe.
+; This should be left blank in most cases. For most installs,
+; the server credentials should only be set in the agent.
+;blackfire.server_id =
+
+; Sets fine-grained configuration for Probe.
+; This should be left blank in most cases. For most installs,
+; the server credentials should only be set in the agent.
+;blackfire.server_token =
+
+; Log verbosity level:
+;   4: debug
+;   3: info
+;   2: warning;
+;   1: error
+;blackfire.log_level = 1
+
+; Log file (STDERR by default)
+;blackfire.log_file = /tmp/blackfire.log
+
+; Add the stacktrace to the probe logs when a segmentation fault occurs.
+; Debug option inactive on Windows and Alpine.
+;blackfire.debug.sigsegv_handler = 0
+
+; Sets the socket where the agent is listening.
+; Possible value can be a unix socket or a TCP address.
+; Defaults values are:
+;   - Linux: unix:///var/run/blackfire/agent.sock
+;   - macOS amd64: unix:///usr/local/var/run/blackfire-agent.sock
+;   - macOS arm64 (M1): unix:///opt/homebrew/var/run/blackfire-agent.sock
+;   - Windows: tcp://127.0.0.1:8307
+;blackfire.agent_socket = unix:///var/run/blackfire/agent.sock
+
+; Enables Blackfire Monitoring
+; Enabled by default since version 1.61.0
+;blackfire.apm_enabled = 1

.nix/php/lib/pcov.ini.dist

@@ -0,0 +1,6 @@
+[pcov]
+; pcov.enabled=1
+; pcov.directory=.
+; pcov.exclude=
+; pcov.initial.memory=65536
+; pcov.initial.files=64

.nix/php/lib/php.ini.dist

@@ -0,0 +1,10 @@
+date.timezone = UTC
+max_execution_time = 1800
+max_input_time = 3600
+max_input_nesting_level = 64
+memory_limit = -1
+post_max_size = 200M
+upload_max_filesize = 150M
+file_uploads = On
+max_file_uploads = 20
+short_open_tag = off

.nix/php/lib/xdebug.ini.dist

@@ -0,0 +1,2 @@
+[xdebug]
+xdebug.mode=debug

.nix/pkgs/flow-php/package.nix

@@ -0,0 +1,68 @@
+{
+    php,
+    php-snappy,
+    php-lz4,
+    php-brotli,
+    php-zstd,
+    with-pcov ? true,
+    with-xdebug ? false,
+    with-blackfire ? false
+}:
+
+let
+    flowPHP = php.withExtensions (
+    { enabled, all }:
+    with all;
+    enabled
+        ++ [
+            bcmath
+            dom
+            mbstring
+            (php-brotli.override { inherit php; })
+            (php-lz4.override { inherit php; })
+            (php-snappy.override { inherit php; })
+            (php-zstd.override { inherit php; })
+            xmlreader
+            xmlwriter
+            zlib
+        ]
+        ++ (if with-xdebug then [xdebug] else [])
+        ++ (if with-pcov then [pcov] else [])
+        ++ (if with-blackfire then [blackfire] else [])
+    );
+in
+flowPHP.buildEnv {
+    extraConfig = ""
+    + (
+        if builtins.pathExists ./../../php/lib/php.ini
+            then builtins.readFile ./../../php/lib/php.ini
+            else builtins.readFile ./../../php/lib/php.ini.dist
+    )
+    + "\n"
+    + (
+        if with-xdebug
+        then
+            if builtins.pathExists ./../../php/lib/xdebug.ini
+            then builtins.readFile ./../../php/lib/xdebug.ini
+            else builtins.readFile ./../../php/lib/xdebug.ini.dist
+        else ""
+      )
+    + "\n"
+    + (
+        if with-blackfire
+        then
+            if builtins.pathExists ./../../php/lib/blackfire.ini
+                then builtins.readFile ./../../php/lib/blackfire.ini
+                else builtins.readFile ./../../php/lib/blackfire.ini.dist
+        else ""
+      )
+    + "\n"
+    + (
+        if with-pcov
+        then
+            if builtins.pathExists ./../../php/lib/pcov.ini
+                then builtins.readFile ./../../php/lib/pcov.ini
+                else builtins.readFile ./../../php/lib/pcov.ini.dist
+        else ""
+      );
+}

.nix/pkgs/php-brotli/package.nix

@@ -0,0 +1,17 @@
+{
+  php,
+  fetchFromGitHub,
+}:
+
+php.buildPecl {
+  pname = "brotli";
+  version = "0.13.1";
+
+  src = fetchFromGitHub {
+    owner = "kjdev";
+    repo = "php-ext-brotli";
+    tag = "0.13.1";
+    hash = "sha256-bdnTEEJUPe+VvXjncKbIi4wfnEn9UH7OBTKiUCET+qQ=";
+    fetchSubmodules = true;
+  };
+}

.nix/pkgs/php-lz4/package.nix

@@ -0,0 +1,14 @@
+{ php, fetchFromGitHub }:
+
+php.buildPecl {
+  pname = "lz4";
+  version = "0.4.4";
+
+  src = fetchFromGitHub {
+    owner = "kjdev";
+    repo = "php-ext-lz4";
+    tag = "0.4.4";
+    hash = "sha256-iKgMN77W5iR3jwOwKNwIpuLwkeDkQVTIppEp4fF1oZw=";
+    fetchSubmodules = true;
+  };
+}

.nix/pkgs/php-snappy/package.nix

@@ -0,0 +1,16 @@
+{ php, fetchFromGitHub }:
+
+php.buildPecl {
+  pname = "snappy";
+  version = "0.2.1";
+
+  src = fetchFromGitHub {
+    owner = "kjdev";
+    repo = "php-ext-snappy";
+    tag = "0.2.1";
+    hash = "sha256-PAKdIcpJKH6d74EulYQepP4XbQvccrj1nEuir47vro4=";
+    fetchSubmodules = true;
+  };
+
+  env.NIX_CXXFLAGS_COMPILE = "-std=c++11";
+}

.nix/pkgs/php-zstd/package.nix

@@ -0,0 +1,14 @@
+{ php, fetchFromGitHub }:
+
+php.buildPecl {
+  pname = "zstd";
+  version = "0.14.0";
+
+  src = fetchFromGitHub {
+    owner = "kjdev";
+    repo = "php-ext-zstd";
+    tag = "0.14.0";
+    hash = "sha256-oIbvaLYQ6Tp20Y/UEN7i1dtMnxGdMNcIjv6xRCyVYdE=";
+    fetchSubmodules = true;
+  };
+}

.nix/shell/.gitignore

@@ -0,0 +1 @@
+starship.toml

.nix/shell/starship.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+# Directory of this script
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Check if starship.toml exists, otherwise use starship.toml.dist
+if [ -f "$SCRIPT_DIR/starship.toml" ]; then
+  export STARSHIP_CONFIG="$SCRIPT_DIR/starship.toml"
+else
+  export STARSHIP_CONFIG="$SCRIPT_DIR/starship.toml.dist"
+fi
+
+# Initialize Starship prompt
+eval "$(${pkgs.starship}/bin/starship init bash)"

.nix/shell/starship.toml.dist

@@ -0,0 +1,10 @@
+[php]
+style = "blue"
+format = 'via [$symbol($version )]($style)'
+
+[aws]
+disabled = true
+[azure]
+disabled = true
+[gcloud]
+disabled = true

CHANGELOG.md

@@ -1,6 +1,7 @@
-## [Unreleased] - 2025-02-21
+## [Unreleased] - 2025-02-23
 
 ### Added
+- [#1468](https://github.com/flow-php/flow/pull/1468) - **Nix - for local development environment** - [@norberttech](https://github.com/norberttech)
 - [#1492](https://github.com/flow-php/flow/pull/1492) - **Respect limit/offset from query builder in dbal query loader** - [@norberttech](https://github.com/norberttech)
 - [#1491](https://github.com/flow-php/flow/pull/1491) - **Added missing tests to string functions** - [@f-lapinski](https://github.com/f-lapinski)
 - [#1488](https://github.com/flow-php/flow/pull/1488) - **DataStream builder** - [@norberttech](https://github.com/norberttech)
@@ -171,6 +172,7 @@
 - [#1240](https://github.com/flow-php/flow/pull/1240) - **Update Homebrew TAP formula: flow-php to version: 0.10.0** - [@norberttech](https://github.com/norberttech)
 
 ### Fixed
+- [457164](https://github.com/flow-php/flow/commit/457164b233c9168df44ccf298a777121e1891861) - **broken upsert example** - [@norberttech](https://github.com/norberttech)
 - [#1482](https://github.com/flow-php/flow/pull/1482) - **JSON was being double encoded.** - [@jmortlock](https://github.com/jmortlock)
 - [#1483](https://github.com/flow-php/flow/pull/1483) - **Fix typo in README.md** - [@jmortlock](https://github.com/jmortlock)
 - [#1475](https://github.com/flow-php/flow/pull/1475) - **Incosistency between XMLEntry::toString and Casting XML's to strings** - [@norberttech](https://github.com/norberttech)

documentation/contributing.md

@@ -4,14 +4,16 @@ To run tests locally, please make sure you have [docker](https://www.docker.com/
 You also need [PHP 8.2](https://www.php.net/) and [composer](https://getcomposer.org/) to be available from your CLI.
 Even though we are supporting 3 PHP versions at the time, we are using the lowest supported one for development, currently it's PHP 8.2.
 
-
 ## Before you change anything
 
 Please make sure that you are aware of our [Architecture Decision Records](/documentation/adrs.md).
 It's mandatory to follow all of them without any exceptions unless explicitly overridden by a new ADR.
 
 ## Prepare Project:
 
+**HEADS UP** - instead of using php installed on your host machine, consider using Nix Shell. 
+You can find detailed instructions how to use Nix in the [Nix Development Environment](/documentation/contributing/nix.md) section.
+
 ```shell
 cp compose.yml.dist compose.yml
 composer install 

documentation/contributing/nix.md

@@ -0,0 +1,117 @@
+# Nix - Development Environment
+
+Nix is probably the easiest way of setting up the development environment.
+
+Before you start please make sure you have Nix installed. 
+If you don't have it installed, you can install it by following official documentation.
+
+[Nix installation instructions](https://nixos.org/download/)
+
+Once you have Nix installed, you can start your development environment
+by going to the project folder and running following command:
+
+```bash
+nix-shell
+```
+
+> If you are using Nix for the first time, it might take a while to download all the dependencies.
+
+> To achieve full isolation, use `nix-shell --pure` command. This way nix will isolate your development environment from the system.
+
+That's all, after running this command you will have all the necessary tools and dependencies.
+Nix will create a new shell with all the necessary tools and dependencies for the project.
+
+By default, we’re using [Starship](https://starship.rs/) to provide a nice bash prompt.
+You can override it by creating `/.nix/shell/starship.toml` based on `/.nix/shell/starship.toml.dist` 
+file. 
+
+Once you apply your modification you can run `nix-shell` again to apply changes.
+
+To use the php version from nix inside your IDE please start a nix shell `nix-shell`
+and type: 
+
+```shell
+type php
+```
+
+This should return you path to your php version that is used inside of the nix shell.
+It will look like this: 
+
+```shell
+php is /nix/store/p2m5bamh01ncpwjxscdl11p2m9xy8aq6-php-with-extensions-8.2.27/bin/php
+```
+
+## php.ini
+
+Nix shell comes with predefined php.ini, but if for any reason
+it wouldn't be enough for you, you can create your own php.ini file in path:
+
+`./.nix/php/lib/php.ini`
+
+If that file is not present, the default php.ini.dist from the same location will be used.
+
+## Pcov
+
+- `pcov` - required for code coverage
+
+To skip installing pcov extension, you can run nix shell with `--arg with-pco false` flag:
+
+```shell
+
+nix-shell --arg with-pcov false
+```
+
+To configure pcov, you can create a file `./.nix/php/lib/pcov.ini` with your xdebug configuration.
+
+## Xdebug
+
+- `xdebug` - required for debugging
+
+To install xdebug extension, you can run nix shell with `--arg with-xdebug true` flag:
+
+```shell
+nix-shell --arg with-xdebug true
+```
+
+To configure xdebug, you can create a file `./.nix/php/lib/xdebug.ini` with your xdebug configuration.
+
+## Blackfire
+
+- `blackfire` - required for profiling
+
+To install blackfire extension, you can run nix shell with `--arg with-blackfire true` flag:
+
+```shell
+nix-shell --arg with-blackfire true
+```
+
+To configure blackfire, you can create a file `./.nix/php/lib/blackfire.ini` with your blackfire configuration.
+
+## Changing PHP Versions
+
+To change the PHP version, you can run nix shell with `--arg php-version 8.3` flag:
+
+```shell
+nix-shell --arg php-version 8.3
+```
+
+> In general, it's not recommended to change the PHP version, as development should always
+> be done on the lowest supported PHP version. 
+>
+> This feature is mostly for testing new integrations
+> or lowest/highest versions of dependencies.
+
+## Local Webserver
+
+To run the local webserver for Flow Website development, please use Symfony CLI app
+that is also available in nix shell.
+
+```shell
+cd web/landing
+symfony proxy:start
+symfony server:start -d 
+```
+
+You can read more about it here: 
+
+- [How to use .wip domain for development](https://symfony.com/doc/current/setup/symfony_server.html#setting-up-the-local-proxy)