README

A robust Laravel package for generating update ZIP files and new installation packages based on Git repository changes.

Features

🚀 Git Integration: Automatically detects files changed between specified dates or commit ranges
💻 Modern Interactive CLI: Stunning, boxed UI with radio-style selections for a premium developer experience
📦 Multiple Package Types: Generate update packages, new installation packages, or both
🛡️ Security: Safe Git command execution with proper validation
🔒 Environment Sanitization: Automatically sanitizes sensitive data in .env files for new installations
🧹 Cache Management: Automatic cache clearing before package generation
📝 Logging: Comprehensive logging for debugging and monitoring
⚙️ Configurable: Easy configuration for excluded paths and settings
🎯 Type Safety: Full PHP 8.1+ type safety with strict typing
📁 Custom File Inclusion: Explicitly include custom packages and essential files in updates
🗂️ Smart Exclusions: Wildcard patterns for excluding directory contents while preserving structure
🔄 Commit-Based Support: Generate updates based on specific Git SHAs (full/short)

Minimum Requirements

Requirement	Version
PHP	8.1+
Laravel	9.x+
Git	2.0+

Installation

1. Install the package

composer require mahesh-kerai/update-generator

System Requirements

PHP: 8.1 or higher
Laravel: 9.0 or higher
PHP Extensions:
- zip extension (for creating ZIP archives)
- fileinfo extension (for file type detection)
Operating Systems: Windows, Linux, macOS (cross-platform compatible)

Note: The package now uses PHP's built-in ZipArchive instead of external zip commands, making it fully compatible across all operating systems.

2. Publish configuration

php artisan vendor:publish --tag=config

This creates the configuration file at config/update-generator.php

3. Configure excluded paths and additional files

Edit config/update-generator.php to customize excluded paths and include additional files:

return [
    'exclude_update' => [
        'storage',
        'vendor',
        '.env',
        'node_modules',
        '.git',
        '.idea',
        'composer.lock',
        'package-lock.json',
        'yarn.lock',
        'public/storage',
        'public/uploads',
        'tests',
        'phpunit.xml',
        '.gitignore',
        '.env.example',
        'README.md',
        'CHANGELOG.md',
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Additional files to include in update packages
    |--------------------------------------------------------------------------
    |
    | These files/folders will be explicitly included in update packages
    | even if they are in excluded paths (e.g., custom vendor packages)
    |
    */
    'add_update_file' => [
        'vendor/autoload.php',
        'vendor/mahesh-kerai',
        'vendor/composer',
    ],
    
    /*
    |--------------------------------------------------------------------------
    | Exclude paths for new installation packages
    |--------------------------------------------------------------------------
    |
    | These paths will be excluded when generating new installation packages
    | Note: .env file is included for fresh installations as it's required
    | Use wildcard patterns (*) to exclude contents while preserving directories
    |
    */
    'exclude_new' => [
        'storage/app/public',
        'storage/logs/*',           // Excludes log files, keeps directory
        'storage/framework/cache/data', // Excludes cache data, keeps directory
        'storage/framework/sessions/*', // Excludes session files, keeps directory
        'storage/framework/views/*',    // Excludes compiled views, keeps directory
        'storage/debugbar/*',           // Excludes debugbar files, keeps directory
        '.git',
        '.idea',
        'node_modules',
        'public/storage',
        'public/uploads',
        '.vscode',
        'storage/installed',
    ],
    
    'output_directory' => 'storage/app/update_files',
    'git_timeout' => 300,
    'enable_logging' => true,
    
    /*
    |--------------------------------------------------------------------------
    | Clear cache before generation
    |--------------------------------------------------------------------------
    |
    | Whether to clear all cache files before generating packages
    | This ensures no cached data is included in the packages
    |
    */
    'clear_cache_before_generation' => true,
    
    /*
    |--------------------------------------------------------------------------
    | Sanitize .env file
    |--------------------------------------------------------------------------
    |
    | Whether to sanitize the .env file by replacing sensitive values
    | with default values or null before generating packages
    |
    */
    'sanitize_env_file' => true,
    
    /*
    |--------------------------------------------------------------------------
    | .env file sanitization rules
    |--------------------------------------------------------------------------
    |
    | Define which environment variables should be sanitized and their
    | replacement values for new installation packages
    |
    */
    'env_sanitization_rules' => [
        'APP_KEY' => 'base64:your-app-key-here',
        'DB_PASSWORD' => '',
        'DB_USERNAME' => 'root',
        'DB_DATABASE' => 'laravel',
        'DB_HOST' => '127.0.0.1',
        'DB_PORT' => '3306',
        'MAIL_PASSWORD' => '',
        'MAIL_USERNAME' => '',
        'MAIL_HOST' => 'smtp.mailgun.org',
        'MAIL_PORT' => '587',
        'MAIL_ENCRYPTION' => 'tls',
        'MAIL_FROM_ADDRESS' => 'hello@example.com',
        'MAIL_FROM_NAME' => 'Laravel',
        'PUSHER_APP_KEY' => '',
        'PUSHER_APP_SECRET' => '',
        'PUSHER_APP_ID' => '',
        'PUSHER_APP_CLUSTER' => 'mt1',
        'MIX_PUSHER_APP_KEY' => '',
        'MIX_PUSHER_APP_CLUSTER' => 'mt1',
        'AWS_ACCESS_KEY_ID' => '',
        'AWS_SECRET_ACCESS_KEY' => '',
        'AWS_DEFAULT_REGION' => 'us-east-1',
        'AWS_BUCKET' => '',
        'REDIS_PASSWORD' => '',
        'REDIS_HOST' => '127.0.0.1',
        'REDIS_PORT' => '6379',
        'CACHE_DRIVER' => 'file',
        'SESSION_DRIVER' => 'file',
    ],
];

Usage

Modern Interactive CLI Workflow (Recommended)

The easiest way to generate packages is to use the interactive wizard, which features a modern, boxed UI inspired by Laravel's official tools. Simply run the command without any arguments:

php artisan update:generate

The command will guide you through a structured, interactive process:

Filtering Method: Select between Date Range or Commit Range using arrow keys.
Instructional Notes: Contextual help will appear (e.g., format reminders).
Conditional Inputs:
- Date Range Mode: Enter Start Date and End Date (YYYY-MM-DD).
- Commit Range Mode: Enter Starting Commit Reference and Ending Commit Reference (Strictly SHAs only).
Current Version: Enter your system's current version (e.g., 1.0.0).
Update Version: Enter the target update version (e.g., 1.1.0).
Type Selection: Choose both, update, or new using the interactive radio-style selection.

Once all inputs are provided, a Confirmation Summary will be displayed inside a structured box for your final approval.

Commit Range Mode Guidelines

When using Commit Range Mode, please note the following:

Important

Supported References: Only Full Git SHAs and Short Git SHAs (e.g., a1b2c3d) are supported.

Unsupported References: You cannot use full commit messages as references. Ensure the starting commit precedes the ending commit in the repository's history.

Inline Options (Backward Compatibility & Automation)

For automated systems or advanced users, you can pass parameters directly. Providing these options will automatically bypass the interactive prompts:

Date-Based Example:

php artisan update:generate \
    --start_date=2025-01-01 \
    --end_date=2025-03-31 \
    --current_version=1.0.0 \
    --update_version=1.1.0 \
    --type=both

Commit-Based Example:

php artisan update:generate \
    --start_commit=a1b2c3d \
    --end_commit=e5f6g7h \
    --current_version=1.0.0 \
    --update_version=1.1.0 \
    --type=update

Input Parameters Explanation

Parameter	Format / Options	Description
Start Date	`YYYY-MM-DD`	The beginning date to check Git history for modified or created files.
End Date	`YYYY-MM-DD`	The ending date to check Git history.
Start Commit	Full/Short SHA	The starting commit SHA reference (Full or Short). Commit messages not allowed.
End Commit	Full/Short SHA	The ending commit SHA reference. Commit messages not allowed.
Current Version	e.g. `1.0.0`	The current operational version of the project. Added to the generated `version_info.php`.
Update Version	e.g. `1.1.0`	The target version after the update.
Type	`both`, `update`, `new`	Defines the output. `update` extracts only changed files. `new` bundles the entire project.

How It Works (Workflow)

Git Diff Analysis: If generating an update package, the system runs local Git commands to identify exactly which files were modified, created, or deleted between the provided Date Range or Commit Range.
File Filtering: Identified files are cross-referenced with your exclude_update and add_update_file configuration to ensure absolute correctness.
Packaging Update Files: All applicable files are replicated into a temporary environment and bundled into a source_code.zip archive.
Packaging New Installation: If requested, the system zips the entire project directory, cleanly bypassing paths marked in exclude_new. Furthermore, sensitive values inside .env are automatically sanitized.
Versioning Details: A version_info.php is generated containing the input versions to assist the end-user upgrade systems.

Requirements & Prerequisites

Before running the command, ensure your environment is fully prepared:

Git Context: Must be run from within an initialized Git repository.
Project Setup: Ensure composer dependencies are properly resolved and the application is structurally sound.
Correct File Permissions: Write permissions are required at the output_directory path (default: storage/app/update_files).
Dependencies: Standard PHP zip extension (ext-zip) is required for compression, and git CLI must be accessible in your system paths.
Valid Inputs: Dates must stringently match the YYYY-MM-DD format.

Output Structure

Depending on your selected Type, the following files and folders will be created inside the configured output directory (storage/app/update_files by default):

Update Package

Generates only changed and new files:

Update 1.0.0-to-1.1.0.zip
├── source_code.zip (contains only changed project files)
└── version_info.php (version information)

New Installation Package

Generates a full installation bundle with sanitized credentials:

New_Installation_V1.1.0.zip
└── [all project files except excluded] (includes sanitized .env)

Version Info File

<?php
return [
    'current_version' => '1.0.0',
    'update_version' => '1.1.0',
];

Important Notes

Seamless Backward Compatibility: Existing CI/CD scripts using inline parameters remain 100% operational. The new interactive wizard only activates for missing inputs.
Intact Core Functionality: Only the command's input collection methodology was improved. File resolution, Git extraction, and ZIP compression logic remain fundamentally unchanged.
Smart Validation: The interactive wizard validates date formats and version inputs iteratively, rejecting incorrect strings and asking again without crashing.

Configuration Options

Option	Description	Default
`exclude_update`	Paths to exclude from update packages	See config
`add_update_file`	Files/folders to explicitly include in update packages	See config
`exclude_new`	Paths to exclude from new installation packages	See config
`output_directory`	Directory for generated packages	`storage/app/update_files`
`git_timeout`	Git command timeout in seconds	`300`
`enable_logging`	Enable logging for debugging	`true`
`clear_cache_before_generation`	Clear cache before generating packages	`true`
`sanitize_env_file`	Sanitize .env file for new installations	`true`
`env_sanitization_rules`	Rules for sanitizing environment variables	See config

Additional Files Configuration

The add_update_file option allows you to explicitly include specific files or folders in your update packages, even if they're in excluded paths. This is particularly useful for:

Custom vendor packages that need to be included in updates
Essential configuration files like vendor/autoload.php
Composer files required for proper package management
Any specific files that should always be included

Example:

'add_update_file' => [
    'vendor/autoload.php',           // Essential for Composer autoloading
    'vendor/mahesh-kerai',           // Your custom package
    'vendor/composer',               // Composer configuration
    'config/custom-config.php',      // Custom configuration
    'app/Services/CustomService.php' // Custom service
],

Environment File Sanitization

The package automatically sanitizes sensitive data in .env files when generating new installation packages. This ensures that:

Sensitive credentials are removed or replaced with safe defaults
API keys and passwords are cleared
Database credentials are reset to default values
A new APP_KEY is generated for each installation
Mail settings are reset to safe defaults

Before Sanitization:

DB_PASSWORD=my_secret_password
MAIL_PASSWORD=my_email_password
APP_KEY=base64:actual_encryption_key
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

After Sanitization:

DB_PASSWORD=
MAIL_PASSWORD=
APP_KEY=base64:new_generated_key_here
AWS_ACCESS_KEY_ID=

Wildcard Exclusion Patterns

Use wildcard patterns (*) to exclude directory contents while preserving the directory structure:

'exclude_new' => [
    'storage/logs/*',           // Excludes all files in logs directory
    'storage/framework/sessions/*', // Excludes session files, keeps directory
    'storage/debugbar/*',       // Excludes debugbar files, keeps directory
],

This ensures that:

✅ Directory structure is preserved - Laravel can create files in these directories
✅ Contents are excluded - No sensitive or temporary files are included
✅ No runtime errors - Essential directories exist for the application to function

Cache Management

The package automatically clears various cache types before generating packages:

Application cache (storage/framework/cache)
View cache (storage/framework/views)
Session files (storage/framework/sessions)
Bootstrap cache (bootstrap/cache)
Laravel Artisan caches (cache:clear, view:clear, config:clear, route:clear)

This ensures that no cached data is included in your packages, keeping them clean and up-to-date.

Best Practices

Version Naming: Use semantic versioning (e.g., 1.0.0, 1.1.0)
Date Format: Always use YYYY-MM-DD format for dates
Git Repository: Ensure you're in a Git repository before running commands
Exclusions: Configure appropriate exclusions for your project
Custom Files: Use add_update_file to include essential custom packages and dependencies
Testing: Test generated packages in a staging environment before production use
Environment Security: Always enable .env sanitization for production packages
Wildcard Patterns: Use wildcard patterns (*) to exclude directory contents while preserving structure
Cache Clearing: Keep clear_cache_before_generation enabled to ensure clean packages
Sanitization Rules: Customize env_sanitization_rules to match your application's needs

Recent Updates

💻 Modern Interactive CLI UI

Stunning Visuals: Completely redesigned interactive experience with boxed inputs and bordered containers.
Radio-Style Selections: Select filtering methods and package types using keyboard arrow keys (↑/↓) for a seamless workflow.
Instructional Hints: Built-in helper text and placeholders (e.g., e.g. 1.0.0) to guide users in real-time.
Inline Validation: Immediate, formatted error feedback without breaking the visual flow.

🔄 Commit-Based Generation

SHA Support: Ability to generate updates between two specific commit references.
Support: Compatible with both Full SHAs and Short SHAs.
Range Validation: Automatic validation to ensure the starting reference precedes the ending reference.

🔒 Security Enhancements

Environment File Sanitization: Automatically removes sensitive data from .env files in new installation packages
Smart Exclusion Patterns: Wildcard patterns (*) for excluding directory contents while preserving structure
Cache Management: Automatic cache clearing before package generation

🛠️ Technical Improvements

ZIP Creation: Uses PHP's built-in ZipArchive for cross-platform compatibility (Windows, Linux, macOS)
Infinite Loop Prevention: Fixed recursive copying issues in new installation generation
File System Safety: Enhanced file copying with proper path validation and error handling
Logging Enhancement: Improved logging with masked sensitive values for security

📦 Package Generation

Essential Files: Automatic inclusion of vendor/autoload.php, vendor/composer, and custom packages
Directory Structure: Preserved essential Laravel directories (storage/framework/sessions, etc.)
Clean Packages: No cached data or temporary files included in packages

⚙️ Configuration Options

sanitize_env_file: Enable/disable .env file sanitization
env_sanitization_rules: Customize which environment variables to sanitize
clear_cache_before_generation: Control automatic cache clearing
Wildcard Exclusions: Use storage/logs/* patterns for smart exclusions

Troubleshooting

Common Issues

Q: Getting "Failed to create ZIP archive" error? A: This has been fixed by using PHP's built-in ZipArchive. Ensure the PHP zip extension is installed and enabled on your system.

Q: New installation packages missing essential directories? A: Use wildcard patterns like storage/logs/* instead of storage/logs to preserve directory structure.

Q: Sensitive data in .env files? A: Enable sanitize_env_file and configure env_sanitization_rules to automatically clean sensitive data.

Q: Package generation in infinite loop? A: This has been fixed by using system temp directory and proper path validation.

Q: Missing vendor files in new installations? A: The package now automatically includes essential vendor files like vendor/autoload.php and vendor/composer.

License

This package is open-sourced software licensed under the MIT license.

💡 Support

👨‍💻 Created by Mahesh Kerai – A passionate Laravel developer who loves building clean and scalable solutions.
🌟 “Helping developers save time with automation and smarter workflows.”

📬 For questions, feedback, or support:

✉️ Email: wrteam.mahesh@gmail.com

✨ Made with ❤️, ☕, and a lot of Laravel magic by Mahesh Kerai.

Made with ❤️ by Mahesh Kerai

mahesh-kerai / update-generator

Maintainers

Package info

Statistics

Security