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
📦 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

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

Interactive CLI Workflow (Recommended)

The easiest way to generate packages is to use the interactive wizard. Simply run the command without any arguments:

php artisan update:generate

The command will then guide you step-by-step through the process:

Start Date: Enter the beginning date for finding changed files (YYYY-MM-DD). (Note: Skipped if generating a new package only).
End Date: Enter the ending date for finding changed files (YYYY-MM-DD). (Note: Skipped if generating a new package 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 what type of packages to generate (both, update, or new).

Once all inputs are provided, a Summary will be displayed for your confirmation before generation begins.

Inline Options (Backward Compatibility)

For automated systems or advanced users, you can still pass parameters directly. If all required parameters are provided, the interactive prompts will be bypassed automatically:

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

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.
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 Start Date and End Date.
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

🔒 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