The perfect starting point to analyse the PHP quality of our Algolia Magento 2 extension

💡 Getting Started

First, install globally the magento2-tools:

composer global require algolia/magento2-tools

Make sure to place Composer's system-wide vendor bin directory in your $PATH so the magento2-tool executable can be located by your system.

Finally, you can launch the quality tools with:

{command} path/to/magento/extension [vendor/bin/path/]

The second argument is optional. If omitted, the scripts will attempt to auto-resolve the vendor bin directory by checking for a local vendor/bin/ install (e.g. after running composer install in the package directory) and then falling back to the global Composer vendor bin. If neither is found, the tools are expected to be on your $PATH.

Here is the list of available commands:

• magento2-lint: Runs the linter and fixes the found issues - configuration file under algoliasearch-magento-2/.php-cs-fixer.php.

• magento2-analyse: Runs PHPStan static analysis. Uses phpstan.neon or phpstan.neon.dist from the extension directory if present; otherwise runs at level 1 with sensible defaults.

• magento2-php-compatibility: Checks if your code is compatible across all PHP versions supported by Magento.

• magento2-test: Runs all previous commands in --dry-run / read-only mode (coding style, PHP compatibility, and PHPStan analysis).

Optional patch: bitexpert/phpstan-magento autoloader collision

Under specific conditions (PHPStan parallel-worker mode with a warm cache, certain symlinked install layouts), bitexpert/phpstan-magento's Extension*Autoloader classes can collide with phpstan/phpstan-phpunit's MockObjectTypeNodeResolverExtension. Symptoms include a hard ExtensionInterfaceAutoloader.php line 93 crash or silent false-positive return statement is missing errors. Tracked upstream in bitExpert/phpstan-magento#297.

magento2-analyse mitigates the most common trigger automatically, so most users will never see this. Only apply the patch below if you actually encounter the crash or false positives.

This package ships patches/bitexpert-phpstan-magento-skip-phpstan-namespace.patch, which makes both autoloaders skip classes in the PHPStan\ namespace. Apply it manually against your global Composer install:

COMPOSER_HOME=$(composer global config --absolute home) && \
  patch -d "$COMPOSER_HOME/vendor/bitexpert/phpstan-magento" -p1 \
    < "$COMPOSER_HOME/vendor/algolia/magento2-tools/patches/bitexpert-phpstan-magento-skip-phpstan-namespace.patch"

If the patch reports "Reversed (or previously applied) patch detected" it has already been applied; answer n to skip. The patch needs to be reapplied after every composer global update of algolia/magento2-tools. If patch fails for any other reason, bitexpert/phpstan-magento has been updated and the patch needs revisiting.

Development

When working on this repository directly (rather than as a globally-installed package), run composer install to populate vendor/, then apply the bitexpert patch via the bundled Composer script:

composer install
composer dev:patch

composer dev:patch is idempotent: it greps for the patch marker first and prints Patch already applied. if the local vendor is up to date, otherwise it runs patch(1) against vendor/bitexpert/phpstan-magento. Re-run it any time bitexpert/phpstan-magento is reinstalled (e.g. after composer update).

The script only runs when invoked manually on this repository - it is not registered against any Composer event and has no effect when this package is installed as a dependency.

Release process

• Clear your the local repository with: git add . && git reset --hard
• Make sure you are on the latest master branch: git checkout master && git pull

Note: make sure that there is no breaking changes and you may use git tag --list to check the latest release

• Bump version in the file bin/magento2-update
• Commit the bin/magento2-update with the message: git commit -m "chore: bumps version to vX.X.X"
• git push
• git tag vX.X.X
• git push --tags
• Create a new release with the name vX.X.X under https://github.com/algolia/magento2-tools/releases/new.

Developers will get the new version via the auto-update mechanism of this tool.

📄 License

magento2-tools is an open-sourced software licensed under the MIT license.