Feat/v3

.gitattributes

@@ -0,0 +1,11 @@
+# Exclude development-only files from Composer dist tarballs.
+/.github                  export-ignore
+/.gitattributes           export-ignore
+/.gitignore               export-ignore
+/.php-cs-fixer.dist.php   export-ignore
+/.phpunit.cache           export-ignore
+/docs                     export-ignore
+/tests                    export-ignore
+/phpstan.neon.dist        export-ignore
+/phpunit.xml.dist         export-ignore
+/CHANGELOG.md             export-ignore

.github/workflows/ci.yml

@@ -0,0 +1,133 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "*.x"]
+  pull_request:
+    branches: [main, "*.x"]
+
+jobs:
+  validate:
+    name: composer validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.2"
+          coverage: none
+          tools: composer:v2
+      - run: composer validate --strict
+
+  cs:
+    name: PHP-CS-Fixer
+    runs-on: ubuntu-latest
+    needs: validate
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.2"
+          coverage: none
+          tools: composer:v2
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-interaction
+      - name: Check coding standards
+        run: composer cs-check
+
+  stan:
+    name: PHPStan
+    runs-on: ubuntu-latest
+    needs: validate
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.2"
+          coverage: none
+          tools: composer:v2
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-interaction
+      - name: Run PHPStan
+        run: composer stan
+
+  tests:
+    name: PHPUnit (PHP ${{ matrix.php }}, ${{ matrix.deps }})
+    runs-on: ubuntu-latest
+    needs: validate
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ["8.0", "8.1", "8.2", "8.3", "8.4"]
+        deps: ["highest"]
+        include:
+          - php: "8.0"
+            deps: "lowest"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up PHP ${{ matrix.php }}
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+          tools: composer:v2
+
+      - name: Validate composer.json
+        run: composer validate --no-check-publish
+
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
+
+      - name: Cache composer dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: composer-${{ matrix.php }}-${{ matrix.deps }}-${{ hashFiles('**/composer.json') }}
+          restore-keys: composer-${{ matrix.php }}-${{ matrix.deps }}-
+
+      - name: Install highest dependencies
+        if: matrix.deps == 'highest'
+        run: composer update --prefer-dist --no-progress --no-interaction
+
+      - name: Install lowest dependencies
+        if: matrix.deps == 'lowest'
+        run: composer update --prefer-dist --no-progress --no-interaction --prefer-lowest --prefer-stable
+
+      - name: Run PHPUnit
+        run: vendor/bin/phpunit
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    needs: tests
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.2"
+          coverage: pcov
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-progress --no-interaction
+
+      - name: Run PHPUnit with coverage
+        run: vendor/bin/phpunit --coverage-clover=coverage.xml
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-clover
+          path: coverage.xml
+          retention-days: 14
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.xml
+          flags: phpunit
+          fail_ci_if_error: false

.gitignore

@@ -2,4 +2,8 @@
 /.vs/
 /.vscode/
 /vendor/
-/composer.lock
+/composer.lock
+/build/
+/.phpunit.cache/
+/.phpunit.result.cache
+/.php-cs-fixer.cache

.php-cs-fixer.dist.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+$finder = PhpCsFixer\Finder::create()
+    ->in([__DIR__ . '/src', __DIR__ . '/tests'])
+    ->name('*.php');
+
+return (new PhpCsFixer\Config())
+    ->setRiskyAllowed(true)
+    ->setRules([
+        '@PSR12'                      => true,
+        '@PSR12:risky'                => true,
+        '@PHP80Migration'             => true,
+        '@PHP80Migration:risky'       => true,
+        'array_syntax'                => ['syntax' => 'short'],
+        'declare_strict_types'        => true,
+        'native_function_invocation'  => [
+            'include' => ['@compiler_optimized'],
+            'scope'   => 'namespaced',
+            'strict'  => true,
+        ],
+        'no_unused_imports'           => true,
+        'ordered_imports'             => [
+            'imports_order'  => ['class', 'function', 'const'],
+            'sort_algorithm' => 'alpha',
+        ],
+        'single_quote'                => true,
+        'trailing_comma_in_multiline' => ['elements' => ['arrays']],
+    ])
+    ->setFinder($finder)
+    ->setCacheFile(__DIR__ . '/build/php-cs-fixer.cache');

CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to `initphp/dotenv` are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.0]
+
+A maintenance-focused major release: real bug fixes, corrected value
+semantics, a modern PHP 8 codebase, full tests, static analysis, CI and
+documentation. The public API (`DotENV::create`, `get`, `env`, and the global
+`env()` helper) is unchanged.
+
+### Requirements
+
+- **Raised the minimum PHP version to 8.0** (was 5.6). The whole library now
+  uses `declare(strict_types=1)` and native type declarations.
+
+### Fixed
+
+- **Directory-path loading.** `create('/some/dir')` was broken by a
+  `rtrim($dir . '\\/')` typo and always threw "could not be found in the
+  directory". It now correctly finds `.env` / `.env.php` inside a directory.
+- **Multiple `${VAR}` references on one line.** A greedy pattern matched
+  across two references and resolved the value to an empty string. `${A}:${B}`
+  now expands both.
+- **Quoted values with whitespace around `=`.** `KEY = "value"` kept its
+  quotes because the quote check ran on the untrimmed value. Quotes are now
+  stripped regardless of spacing.
+- **Values beginning with `#`.** A value such as `#ffffff` was swallowed
+  entirely as a comment. An inline comment now only starts at a `#` preceded
+  by whitespace, so leading-`#` values survive.
+- **Lines without `=`.** A non-comment line with no `=` raised PHP 8
+  "undefined array key" / "passing null" warnings and stored a junk key. Such
+  lines are now ignored.
+- **Circular `${VAR}` references** (`A=${A}`, or `B=${C}` / `C=${B}`) recursed
+  until the stack overflowed. They now resolve to an empty string while keeping
+  any literal text around the reference (`D=${D}-tail` → `-tail`), and the
+  result no longer depends on which name is read first.
+
+### Changed
+
+- **Loss-free numeric coercion.** Numbers are coerced to `int`/`float` only
+  when the conversion round-trips exactly. `007`, `+905551112233`,
+  values beyond `PHP_INT_MAX`, and `1e3` now stay strings instead of being
+  silently mangled. `13` and `3.14` still coerce as before.
+- **Immutability check** now uses `array_key_exists()` instead of `isset()`
+  (so a pre-existing name whose value is `null` is still respected) and also
+  consults `getenv()`. Previously a real environment variable visible only via
+  `getenv()` (when `variables_order` excludes `E`) could be silently
+  overwritten by a `.env` file.
+- Renamed the internal worker class `Lib` to **`Repository`**. `Lib` remains
+  available as a deprecated alias.
+- Documentation, comments and PHPDoc are now in English and match the actual
+  behaviour.
+
+### Added
+
+- **`Repository::flush()`** and **`DotENV::flush()` / `DotENV::reset()`** to
+  unload values and reset the shared instance (useful in tests and workers).
+- **`DotENV::instance()`** to access the shared repository.
+- An optional leading **`export `** prefix on a key is now stripped.
+- A full **PHPUnit** test suite, **PHPStan** (max level) configuration,
+  **PHP-CS-Fixer** configuration, a **GitHub Actions CI** workflow (PHP
+  8.0–8.4), and a **`docs/`** directory.
+
+## [2.0.1]
+
+- Inline comment parsing fix.
+
+## [2.0]
+
+- Support for `.env.php` files and `${VAR}` interpolation.
+
+## [1.0]
+
+- Initial release.
+
+[3.0.0]: https://github.com/InitPHP/DotENV/releases/tag/3.0.0
+[2.0.1]: https://github.com/InitPHP/DotENV/releases/tag/2.0.1
+[2.0]: https://github.com/InitPHP/DotENV/releases/tag/2.0
+[1.0]: https://github.com/InitPHP/DotENV/releases/tag/1.0