README

A professional Laravel package for syncing with upstream repositories (GitHub, GitLab, Bitbucket, etc.) with comprehensive testing, modern architecture, and enterprise-grade features. Perfect for keeping your Laravel starter kit projects up to date!

🚀 LaravelPlus Community

Welcome to the LaravelPlus community! We're building tools that make Laravel development more enjoyable and productive. Join our community and help shape the future of Laravel tooling.

🌟 Star us on GitHub - Help us grow the community
🐛 Report issues - Help us improve the tools
💡 Suggest features - Share your ideas
🤝 Contribute - Make Laravel better for everyone

✨ Features

🔄 Core Functionality

Universal Git Support - GitHub, GitLab, Bitbucket, Azure DevOps, self-hosted
Multiple Strategies - Support for both merge and rebase strategies
Smart Branch Management - Automatic branch detection and creation
Safe Operations - Dry-run mode and comprehensive error handling

🧪 Testing & Quality

Comprehensive Test Suite - 97 test cases covering all functionality
Built-in Testing - Validate configuration and connectivity before syncing
Code Quality Tools - PHPStan, Rector, and Laravel Pint integration
Modern Testing - Pest PHP with Laravel Testbench

🎯 Starter Kit Support

Pre-configured Presets - Vue, React, Livewire starter kits
Auto-detection - Automatically detect and configure your starter kit
Custom Repositories - Support for any custom Laravel starter kit
Easy Setup - Interactive setup command with beautiful prompts

🔀 Advanced Workflows

Pull Request Workflow - Create PRs instead of direct merges for safer updates
GitHub Integration - Automatic PR creation with GitHub API
Pre/Post Hooks - Run custom commands before and after sync
Flexible Configuration - Environment variables and command-line overrides

🏗️ Modern Architecture

PHP 8.4 Features - Strict types, readonly properties, constructor promotion
Interface-based Design - Clean contracts and abstractions
Service Layer - Separated business logic from commands
Exception Handling - Custom exceptions with detailed error messages
Laravel Prompts - Beautiful command-line interfaces with fallbacks

🚀 Production Ready

Timeout Protection - Prevents hanging operations
Memory Management - Optimized for large repositories
Error Recovery - Graceful handling of network and Git issues
Logging & Debugging - Comprehensive logging for troubleshooting

Installation

composer require laravelplus/laravel-updater

Quick Setup

For Laravel Starter Kits

Use the interactive setup command for quick configuration:

# Interactive setup
php artisan laravelplus:setup

# Or specify your starter kit directly
php artisan laravelplus:setup --preset=vue
php artisan laravelplus:setup --preset=react
php artisan laravelplus:setup --preset=livewire

For Custom Repositories

php artisan laravelplus:setup --preset=custom --url=https://github.com/your-org/your-repo.git

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="LaravelPlus\LaravelUpdater\LaravelUpdaterServiceProvider" --tag="config"

This will create config/upstream.php with the following options:

return [
    'upstream_url'    => env('UPSTREAM_URL', 'https://github.com/laravel/vue-starter-kit.git'),
    'upstream_branch' => env('UPSTREAM_BRANCH', 'main'),
    'local_branch'    => env('UPSTREAM_LOCAL_BRANCH', 'main'),
    'strategy'        => env('UPSTREAM_STRATEGY', 'merge'),
    'git_binary'      => env('GIT_BINARY', 'git'),
    'working_dir'     => base_path(),
    'commit_message'  => env('UPSTREAM_COMMIT_MESSAGE', 'chore(upstream): sync from upstream'),
    'allow_unrelated_histories' => (bool) env('UPSTREAM_ALLOW_UNRELATED', true),
    
    'pre_update' => [
        // 'php artisan down',
        // 'php artisan cache:clear',
    ],
    
    'post_update' => [
        // 'composer install --no-interaction --prefer-dist --optimize-autoloader',
        // 'npm ci',
        // 'npm run build',
        // 'php artisan migrate --force',
        // 'php artisan up',
    ],
];

Environment Variables

Add these to your .env file:

UPSTREAM_URL=https://github.com/your-upstream/repo.git
UPSTREAM_BRANCH=main
UPSTREAM_LOCAL_BRANCH=main
UPSTREAM_STRATEGY=merge
UPSTREAM_COMMIT_MESSAGE="chore(upstream): sync from upstream"
UPSTREAM_ALLOW_UNRELATED=true
UPSTREAM_DEFAULT_PRESET=vue
UPSTREAM_AUTO_DETECT=true
UPSTREAM_CREATE_PR=false
UPSTREAM_PR_BRANCH_PREFIX=upstream-sync-
UPSTREAM_PR_TITLE="chore: sync from upstream"
UPSTREAM_PR_BODY="Automated upstream sync from {upstream_url}"
GITHUB_TOKEN=your_github_token
GITHUB_OWNER=your_username
GITHUB_REPO=your_repo
GIT_BINARY=git

Usage

Recommended Workflow

The recommended workflow is to check for updates first, then upgrade:

# 1. Check if updates are available
php artisan laravelplus:check

# 2. If updates are available, upgrade your project
php artisan laravelplus:update

# 3. Or create a pull request for safer updates
php artisan laravelplus:update --pr

Quick Start Examples

Vue Starter Kit

# Setup for Vue starter kit
php artisan laravelplus:setup --preset=vue

# Check for updates
php artisan laravelplus:check

# Upgrade with updates
php artisan laravelplus:update

React Starter Kit

# Setup for React starter kit
php artisan laravelplus:setup --preset=react

# Check for updates
php artisan laravelplus:check

# Upgrade with updates
php artisan laravelplus:update

Livewire Starter Kit

# Setup for Livewire starter kit
php artisan laravelplus:setup --preset=livewire

# Check for updates
php artisan laravelplus:check

# Upgrade with updates
php artisan laravelplus:update

Custom Repository

# Setup for custom repository
php artisan laravelplus:setup --preset=custom --url=https://github.com/your-org/your-repo.git

# Check for updates
php artisan laravelplus:check

# Upgrade with updates
php artisan laravelplus:update

Using Default Presets

You can set a default preset in your .env file to automatically use a specific starter kit configuration:

# Set Vue as the default preset
UPSTREAM_DEFAULT_PRESET=vue

# Or React
UPSTREAM_DEFAULT_PRESET=react

# Or Livewire
UPSTREAM_DEFAULT_PRESET=livewire

With a default preset configured, you can simply run:

# Check for updates (uses default preset automatically)
php artisan laravelplus:check

# Upgrade if updates are available
php artisan laravelplus:update

Pull Request Workflow

For safer updates in production environments, you can create pull requests instead of direct merges:

Setup GitHub Integration

Create a GitHub Personal Access Token:
- Go to GitHub Settings → Developer settings → Personal access tokens
- Generate a new token with repo permissions
- Add it to your .env file
Configure GitHub settings:

GITHUB_TOKEN=ghp_your_token_here
GITHUB_OWNER=your_username
GITHUB_REPO=your_repo_name

Create Pull Requests

# Check for updates first
php artisan laravelplus:check

# Create a PR with upstream updates
php artisan laravelplus:update --pr

# Or use the direct PR command
php artisan laravelplus:pr --test

# Create PR with custom branch name
php artisan laravelplus:pr --pr-branch=update-vue-starter-kit

# Create PR with custom title and body
php artisan laravelplus:pr --pr-title="Update from Vue starter kit" --pr-body="Sync latest changes from upstream"

PR Workflow Benefits

🔒 Safer Updates - Review changes before merging
📝 Better Documentation - PR descriptions and commit history
👥 Team Collaboration - Multiple reviewers can approve
🔄 Easy Rollback - Simple to revert if issues arise
📊 Change Tracking - Clear history of what changed and when

Advanced Usage

Basic Sync

php artisan laravelplus:sync

Test Before Sync

php artisan laravelplus:sync --test

Dry Run (See What Would Happen)

php artisan laravelplus:sync --dry-run

Use Rebase Strategy

php artisan laravelplus:sync --strategy=rebase

Override Upstream URL

php artisan laravelplus:sync --upstream=https://github.com/other/repo.git

Skip Hooks

php artisan laravelplus:sync --no-pre --no-post

Custom Remote Name

php artisan laravelplus:sync --remote-name=upstream

Supported Laravel Starter Kits

This package comes with pre-configured support for all official Laravel starter kits:

Official Laravel Starter Kits

Vue Starter Kit - laravel/vue-starter-kit
- Vue 3 + Inertia.js + TypeScript + Tailwind CSS
- Perfect for modern SPA applications
React Starter Kit - laravel/react-starter-kit
- React 19 + Inertia.js + TypeScript + Tailwind CSS
- Ideal for React-based applications
Livewire Starter Kit - laravel/livewire-starter-kit
- Livewire 3 + Laravel Volt + TypeScript + Tailwind CSS
- Great for teams preferring PHP over JavaScript

Custom Starter Kits

The package also supports any custom Laravel starter kit or repository:

Custom Repositories - Any Git repository URL
Private Repositories - GitHub, GitLab, Bitbucket private repos
Self-hosted Git - Your own Git server

Supported Platforms

This package works with any Git-based repository hosting service:

GitHub - https://github.com/user/repo.git
GitLab - https://gitlab.com/user/repo.git
Bitbucket - https://bitbucket.org/user/repo.git
Azure DevOps - https://dev.azure.com/org/project/_git/repo
Self-hosted Git - Any Git server with HTTP/SSH access
GitLab Self-hosted - https://your-gitlab.com/user/repo.git
Gitea/Gogs - https://your-gitea.com/user/repo.git

Testing

The package includes comprehensive testing functionality:

✅ Git Binary - Verifies git is installed and accessible
✅ Working Directory - Checks if the working directory exists and is writable
✅ Configuration - Validates all required config values and strategy
✅ Remote Connectivity - Tests if the upstream URL is reachable
✅ Branch Validation - Verifies the upstream branch exists
✅ Local Repository - Checks if current directory is a git repo

Hooks

Configure pre and post-update hooks in your config/upstream.php:

'pre_update' => [
    'php artisan down',
    'php artisan cache:clear',
],

'post_update' => [
    'composer install --no-interaction --prefer-dist --optimize-autoloader',
    'npm ci',
    'npm run build',
    'php artisan migrate --force',
    'php artisan up',
],

Authentication

HTTPS

Uses your stored credentials or personal access tokens.

SSH (Recommended)

Uses your SSH keys for authentication. Set up SSH keys for your Git hosting service.

Personal Access Tokens

For CI/CD environments, use personal access tokens in your repository URL:

https://username:token@github.com/user/repo.git

Available Commands

`laravelplus:check`

Check if there are updates available from upstream repository.

`laravelplus:update`

Upgrade your project with the latest changes from upstream (recommended).

`laravelplus:update --pr`

Create a pull request with upstream updates (safer for production).

`laravelplus:sync`

Direct sync with upstream repository (merges directly to your branch).

`laravelplus:pr`

Create a pull request with upstream updates (alternative to update --pr).

`laravelplus:setup`

Interactive setup wizard for configuring the package.

Command Options

Option	Description
`--dry-run`	Show what would happen without executing
`--test`	Test configuration and connectivity before sync
`--no-pre`	Skip pre_update hooks
`--no-post`	Skip post_update hooks
`--strategy=`	Override strategy (merge\|rebase)
`--upstream=`	Override upstream URL
`--branch=`	Override upstream branch
`--local=`	Override local branch
`--remote-name=`	Remote name to use (default: upstream)
`--pr-branch=`	Override PR branch name (laravelplus:pr only)
`--pr-title=`	Override PR title (laravelplus:pr only)
`--pr-body=`	Override PR body (laravelplus:pr only)

🧪 Testing

This package includes a comprehensive test suite with 97 test cases covering all functionality:

Test Coverage

Unit Tests - Core components, services, and utilities
Feature Tests - Command integration and Laravel functionality
Integration Tests - Service provider and configuration
Exception Tests - Error handling and edge cases

Running Tests

# Run all tests
composer test

# Run specific test suites
composer test:unit
composer test:lint
composer test:types

# Run with coverage
vendor/bin/pest --coverage

Code Quality

The package maintains high code quality standards with:

PHPStan - Static analysis (Level 8) with strict type checking
Rector - Code modernization and PHP 8.4 feature adoption
Laravel Pint - Code style enforcement with Laravel standards
Pest PHP - Modern testing framework with Laravel integration

Architecture Highlights

Strict Types - declare(strict_types=1) throughout the codebase
Interface-based Design - Clean contracts for all major components
Service Layer - Separated business logic from command classes
Custom Exceptions - Detailed error handling with specific exception types
Trait-based Reusability - Common functionality extracted into traits
Constructor Property Promotion - Modern PHP 8.4 syntax
Readonly Properties - Immutable data structures where appropriate

🛠️ Development

Prerequisites

PHP 8.4+
Composer
Git

Development Setup

# Clone the repository
git clone https://github.com/LaravelPlus/laravel-updater.git
cd laravel-updater

# Install dependencies
composer install

# Run tests
composer test

# Check code quality
composer test:lint
composer test:types

Contributing

We welcome contributions! Please see our Development Guide for detailed information on:

Code style and standards
Testing requirements
Pull request process
Issue reporting

Requirements

PHP 8.4+ - Latest PHP features and performance
Laravel 12.0+ - Latest Laravel framework
Git - Installed and accessible in PATH
Valid Git Repository - Working directory must be a Git repository

License

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

📊 Package Statistics

97 Test Cases - Comprehensive test coverage
Modern Architecture - PHP 8.4 + Laravel 12
Code Quality - PHPStan Level 8 + Rector + Pint
Zero Dependencies - Only Laravel framework dependencies
Universal Support - Works with any Git hosting service

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Ways to Contribute

🐛 Report Bugs - Help us identify and fix issues
💡 Suggest Features - Share your ideas for improvements
📝 Improve Documentation - Help others understand the package
🧪 Add Tests - Increase test coverage and reliability
🔧 Fix Issues - Submit pull requests for bug fixes

Development Process

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request

📈 Roadmap

Upcoming Features

🔄 GitLab Integration - Direct GitLab API support
📊 Analytics Dashboard - Track sync history and statistics
🔔 Notifications - Slack/Discord integration for sync events
🎨 Custom Themes - Beautiful command-line interfaces
🔐 Enhanced Security - GPG signing and verification

🏆 Credits

LaravelPlus - The LaravelPlus community
All Contributors - Thank you to everyone who contributes
Laravel Framework - Built on the amazing Laravel framework

📞 Support

Getting Help

📖 Documentation - Check this README and DEVELOPMENT.md
🐛 Bug Reports - GitHub Issues
💬 Discussions - GitHub Discussions
⭐ Star the Project - Show your support!

Community

Join the LaravelPlus community and help us build amazing Laravel tools:

🌟 Star us on GitHub - Help us grow
🐦 Follow us - Stay updated on new features
💡 Share feedback - Help us improve

Made with ❤️ by the LaravelPlus community

laravelplus / laravel-updater

Maintainers

Details