Skip to content

v4.0.0

Latest
Latest

Choose a tag to compare

View all tags
@rappasoft rappasoft released this 06 Dec 22:14
v4.0.0
ffe5d24
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Laravel Patches v4.0.0 - Release Notes

🎉 Major Release: Laravel 11 & 12 Support

Laravel Patches v4.0.0 is a major release that brings full support for Laravel 11 and 12, along with comprehensive improvements to testing, error handling, and developer experience.

✨ What is Laravel Patches?

Laravel Patches allows you to run one-time scripts (patches) in your Laravel application, similar to how migrations work. Perfect for data migrations, one-time fixes, or any script that needs to run once and be tracked.

Key Features:

  • Migration-style patches with up() and down() methods
  • Batch tracking for organized rollbacks
  • Comprehensive metadata tracking
  • Event system for monitoring
  • Transaction support
  • Error handling with detailed logging
  • Multiple management commands

🚀 New Features & Enhancements

Laravel 11 & 12 Support

  • Full compatibility with Laravel 11.x and 12.x
  • Updated to use modern Laravel conventions
  • Removed deprecated Model properties
  • Enhanced type casting and attribute handling

Comprehensive Test Suite

  • 151+ test cases covering all functionality
  • Migrated from PHPUnit to Pest PHP for better developer experience
  • Test coverage includes:
    • Repository tests (11 test cases)
    • Patcher tests (12 test cases)
    • Patch base class tests (6 test cases)
    • Model tests (9 test cases)
    • Integration tests (7 test cases)
    • Command tests with extensive coverage

Enhanced Commands

php artisan make:patch

Create timestamped patch files in database/patches:

php artisan make:patch fix_user_data

php artisan patch

Run all pending patches with powerful options:

# Basic usage
php artisan patch

# Production mode
php artisan patch --force

# Step-by-step execution (each patch in its own batch)
php artisan patch --step

# Preview without executing
php artisan patch --dry-run

php artisan patch:rollback

Rollback patches by batch or step:

# Rollback last batch
php artisan patch:rollback

# Rollback specific number of steps
php artisan patch:rollback --step=3

php artisan patch:status

View comprehensive patch status with filtering:

# All patches
php artisan patch:status

# Filter options
php artisan patch:status --pending
php artisan patch:status --ran
php artisan patch:status --batch=5

php artisan patch:list

List patches in table or JSON format:

# Table format
php artisan patch:list

# JSON format
php artisan patch:list --json

# Filter by status
php artisan patch:list --status=pending
php artisan patch:list --status=ran
php artisan patch:list --status=failed

🔧 Core Features

Migration-Style Patches

Each patch file follows Laravel's migration pattern:

<?php

use Rappasoft\LaravelPatches\Patch;

class FixUserData extends Patch
{
    public function up()
    {
        // Your patch logic here
    }

    public function down()
    {
        // Rollback logic here
    }
}

Batch Tracking

Patches are organized into batches, allowing you to:

  • Rollback entire batches at once
  • Track which patches ran together
  • Maintain execution history

Metadata Tracking

Comprehensive metadata is automatically tracked:

  • Execution time - How long each patch took to run
  • Memory usage - Memory consumed during execution
  • User tracking - Who executed the patch
  • Environment - Which environment it ran in
  • Error logs - Detailed error information when patches fail

Event System

Monitor patch execution with Laravel events:

  • PatchExecuting - Fired before a patch runs
  • PatchExecuted - Fired after successful execution
  • PatchFailed - Fired when a patch fails
  • PatchRollingBack - Fired before rollback
  • PatchRolledBack - Fired after successful rollback

Transaction Support

Configure transactions at the global or patch level:

// Global configuration
'use_transactions' => true,

// Per-patch override
class MyPatch extends Patch
{
    public $useTransaction = true; // or false
}

Error Handling

Robust error handling with multiple strategies:

  • Stop on error (default) - Halts execution when a patch fails
  • Continue on error - Logs errors but continues with remaining patches
  • Detailed error logging - Full exception details stored in database
  • Dry run mode - Preview patches without executing

📋 Requirements

  • PHP: 8.2 or higher
  • Laravel: 11.x or 12.x

🔄 Breaking Changes

PHP Version Requirement

  • Minimum PHP version is now 8.2 (previously 8.1)
  • PHP 8.1 and below are no longer supported

Laravel Version Requirement

  • Minimum Laravel version is now 11.0
  • Laravel 10.x and below are no longer supported
  • Supports Laravel 11.x and 12.x

Model Changes

  • Removed deprecated $dates property
  • Updated to use $casts with datetime casting
  • Changed from $fillable to $guarded = [] for mass assignment

🐛 Bug Fixes

  • Fixed deprecated Model property usage for Laravel 11
  • Model now properly casts ran_on as datetime
  • Fixed flaky test in execution time measurement
  • Improved timing assertions to account for CI environment variance

🧪 Testing & CI/CD

Comprehensive Test Coverage

  • 151+ test cases with 390+ assertions
  • Full integration test suite
  • Command testing with various scenarios
  • Error handling and edge case coverage

CI/CD Improvements

  • Updated GitHub Actions workflow for comprehensive testing:

    • PHP 8.2, 8.3, and 8.4
    • Laravel 11.x and 12.x
    • Both prefer-lowest and prefer-stable dependency resolution
    • Windows and Ubuntu test environments

  • Simplified dependency management following Pest CI best practices

  • Flexible dependency versions in composer.json:

    • orchestra/testbench: ^9.0|^10.0
    • pestphp/pest: ^2.0|^3.0
    • pestphp/pest-plugin-laravel: ^3.0
    • phpunit/phpunit: ^10.5|^11.5

Testing Matrix

PHP Version Laravel Version Status
8.2 11.x ✅ Tested
8.3 11.x ✅ Tested
8.4 11.x ✅ Tested
8.3 12.x ✅ Tested
8.4 12.x ✅ Tested

📦 Installation

composer require rappasoft/laravel-patches

Publish and run migrations:

php artisan vendor:publish --provider="Rappasoft\LaravelPatches\LaravelPatchesServiceProvider" --tag="laravel-patches-migrations"
php artisan migrate

📚 Documentation

Full documentation is available at: https://rappasoft.com/docs/laravel-patches

Documentation includes:

  • Installation guide
  • Usage examples
  • Command reference
  • Configuration options
  • Error handling strategies
  • Event system guide
  • Transaction management
  • Metadata tracking

🙏 Credits

📄 License

The MIT License (MIT). Please see License File for more information.

🔗 Links

Full Changelog: See CHANGELOG.md for complete version history.

Assets 2
Loading