Skip to main content

Changelog - Version 6.0

Overview​

Version 6.0 represents a major upgrade focused on modernizing the codebase, improving developer experience, and maintaining compatibility with the latest PHP versions and dependencies.

New Features​

Built-in CLI Tool​

  • Standalone CLI without external dependencies: Pure PHP implementation without requiring Symfony Console
  • Environment variable support: Configure migrations using MIGRATION_CONNECTION, MIGRATION_PATH, and MIGRATION_TABLE
  • Comprehensive help system: Multiple verbosity levels (-v, -vv, -vvv) for detailed output
  • Available commands:
    • version/status - Show current database version
    • create/install - Create migration tracking table
    • reset - Reset database to base schema
    • up - Migrate to a specific or latest version
    • down - Migrate down to a specific version or version 0
    • update - Automatically update to latest version
  • Composer bin integration: Automatically available as vendor/bin/migrate
  • Comprehensive CLI tests: Full test coverage for CLI functionality

Enhanced Documentation​

  • Complete documentation restructure with separate guides:
    • Getting Started guide
    • Database Setup guide
    • Migration Scripts guide
    • CLI Usage guide
    • API Reference guide
  • Docusaurus-ready documentation format
  • Improved accuracy and examples throughout

Database Handling Improvements​

  • Better database name extraction for SQL Server (support for dbname and Database query parameters)
  • Improved database preparation methods across all database drivers
  • Enhanced SQL statement parsing for SQL Server
  • Type safety improvements with PHP 8.3+ attributes

Development Environment Enhancements​

  • Gitpod configuration for cloud-based development
  • VS Code launch configurations
  • Enhanced GitHub Actions CI workflow with SQL Server support
  • Improved Docker Compose setup

Bug Fixes​

  • Fixed Psalm static analysis issues
  • Improved SQL statement splitting for SQL Server to handle edge cases
  • Fixed database name extraction for SQL Server connections
  • Enhanced type checking and error handling throughout the codebase
  • Better handling of file operations with proper false checks

Breaking Changes​

ComponentBefore (5.x)After (6.x)Description
PHP Version>=8.1 <8.4>=8.3 <8.6Minimum PHP version raised to 8.3, added support for PHP 8.4 and 8.5
PHPUnit^9.6^10.5|^11.5Upgraded to PHPUnit 10/11 for PHP 8.3+ compatibility
Psalm^5.9^6.13Upgraded to Psalm 6 for better PHP 8.3+ analysis
byjg/anydataset-db^5.0^6.0Updated dependency to match version
Import pathsuse ByJG\AnyDataset\Db\DbDriverInterfaceuse ByJG\AnyDataset\Db\Interfaces\DbDriverInterfaceInterface namespace changed in anydataset-db 6.0
Type declarationsPHP version requirement was in require-devNow in requirePHP version is now a production requirement

Upgrade Path from 5.x to 6.x​

Step 1: Check PHP Version​

Ensure you're running PHP 8.3 or higher:

php -v

If you're on PHP 8.1 or 8.2, you need to upgrade PHP before proceeding.

Step 2: Update composer.json​

Update your composer.json to require the new version:

{
  "require": {
    "byjg/migration": "^6.0"
  }
}

Step 3: Update Dependencies​

Run composer update:

composer update byjg/migration

This will automatically update byjg/anydataset-db to version 6.0 as well.

Step 4: Update Import Statements (If Using Library Directly)​

If you're using the library programmatically and importing DbDriverInterface, update the import:

Before:

use ByJG\AnyDataset\Db\DbDriverInterface;

After:

use ByJG\AnyDataset\Db\Interfaces\DbDriverInterface;

Note: This change is in the byjg/anydataset-db package, not in the migration package itself.

Step 5: Update Dev Dependencies (If Applicable)​

If you have PHPUnit or Psalm in your project, you may need to update them as well:

composer update --with-dependencies phpunit/phpunit vimeo/psalm

Step 6: Test Your Migrations​

Run your test suite to ensure everything works:

vendor/bin/phpunit

Test your migrations in a development environment:

# Using the new CLI tool
vendor/bin/migrate version -c <your-connection-string>
vendor/bin/migrate update -c <your-connection-string> -p ./migrations

Step 7: Optional - Migrate to Built-in CLI​

If you were using a custom CLI solution, you can now use the built-in CLI tool:

Old approach (custom script):

#!/usr/bin/env php
<?php
require 'vendor/autoload.php';

$migration = new \ByJG\DbMigration\Migration($uri, $path);
$migration->update();

New approach (built-in CLI):

vendor/bin/migrate update -c <connection-uri> -p ./migrations

Or use environment variables:

export MIGRATION_CONNECTION="mysql://user:pass@localhost/mydb"
export MIGRATION_PATH="./migrations"
vendor/bin/migrate update

Known Issues & Compatibility Notes​

  1. SQL Server Connections: If you're using SQL Server, ensure your connection string includes the database name in the query parameters (?dbname=mydb or ?Database=mydb) in addition to or instead of the path component.

  2. Database Interface Changes: If you've implemented custom database adapters, you may need to update them to match the new interface signatures and add #[\Override] attributes for PHP 8.3+ compatibility.

  3. Namespace Changes: The primary breaking change comes from the byjg/anydataset-db v6.0 dependency, which moved interfaces to an Interfaces namespace. This is handled internally by the migration library, but may affect you if you're using these interfaces directly.

Performance & Quality Improvements​

  • Enhanced static analysis with Psalm 6
  • Improved test infrastructure with PHPUnit 10/11
  • Better type safety with PHP 8.3+ features
  • More robust error handling
  • Enhanced CI/CD pipeline with SQL Server testing

Migration Statistics​

  • 42 files changed
  • 2,218 insertions(+)
  • 597 deletions(-)
  • Major commits: 17

Contributors​

This release includes contributions and improvements from:

  • Joao Gilberto Magalhaes (@byjg)
  • Community contributors

Support​

For issues or questions about this release:

License​

This project continues to be licensed under the MIT License.