klytron / php-deployment-kit

v1.3.1 2026-10-11 08:52 UTC

Requires

• php: ^8.1
• deployer/deployer: ^7.0

Requires (Dev)

• phpstan/phpstan: ^1.0
• phpunit/phpunit: ^10.0

MIT

• Michael K. Laweh

• php
• api
• laravel
• deployment
• automation
• devops
• yii2
• deployer
• klytron

Published on Packagist.org on 2026-10-11 08:52 UTC

README

A comprehensive deployment library for PHP applications built on Deployer. Supports Laravel, Yii2, API projects, and simple PHP applications with zero boilerplate.

Features

• 🚀 Multi-Framework — Laravel, Yii2, API, and simple PHP deployment recipes
• ⚡ Ultra-Fast Deployments — Hardlink dependency caching for Composer & npm/Vite reduces deploys from 15+ minutes down to 30–60 seconds!
• 🎨 Filament v5 Support — Native publishing and cache-busting for Filament v5 assets
• 🔒 Production Safe — Pre-flight validation, unpushed commit guards, non-destructive git caching, and automated rollback
• 🔑 Laravel Env Encryption — Automatic LARAVEL_ENV_ENCRYPTION_KEY decryption before deploy
• 🌐 Zero Server Literals — Configure hosts dynamically from environment variables (klytron_configure_host_from_env())
• 🧪 CI Smoke Test Mode — Test and preview deployment plans in CI without SSH access via dep klytron:plan
• 🗺️ Asset Mapping — Maps Vite/Mix assets for database URL compatibility
• 🖼️ Image Optimisation — Compress images post-deploy
• 🗂️ Sitemap Generation — Automatic sitemap creation and verification
• 🔤 Font Verification — Checks webfonts are accessible after deploy
• 🕒 Deployment Timing — Built-in timer and metrics with completion timestamps
• 🎛️ Interactive or Unattended — Prompted workflow or fully automated via auto_* flags

Requirements

• PHP 8.1+
• Deployer 7.x (installed automatically as a dependency)
• Git
• SSH access to your deployment server

Installation

Install via Composer:

composer require klytron/php-deployment-kit --dev

Verify the installation:

vendor/bin/dep --version

Optional: Scaffold a deploy.php automatically

# Using the built-in CLI tool:
vendor/bin/klytron init my-app --template=laravel

# Or via Artisan in Laravel projects:
php artisan klytron:init my-app

# Or via install script:
curl -sSL https://raw.githubusercontent.com/klytron/php-deployment-kit/main/install.sh | bash

Quick Start

1. Create deploy.php in your project root

<?php
namespace Deployer;

// Core kit
require __DIR__ . '/vendor/klytron/php-deployment-kit/deployment-kit.php';

// Laravel recipe (omit for simple PHP or use klytron-php-recipe.php)
require __DIR__ . '/vendor/klytron/php-deployment-kit/recipes/klytron-laravel-recipe.php';

// ── Configure ────────────────────────────────────────────────────────────────

klytron_configure_app('my-app', '[e-mail]:your-username/my-app.git');
klytron_set_paths('/var/www', '/var/www/${APP_URL_DOMAIN}/public_html');
klytron_set_domain('production.example.com');
klytron_set_php_version('php8.3');

klytron_configure_project([
    'type'                  => 'laravel',
    'database'              => 'mysql',     // mysql | mariadb | postgresql | sqlite | none
    'supports_vite'         => true,
    'supports_filament'     => true,        // Publish Filament v5 assets
    'supports_storage_link' => true,
    'check_git_pushed'      => true,        // Prevent deploying unpushed commits
]);

// Host credentials read from DEPLOY_HOST env variable with fallback
// (or from .env.deploy / .env.production / .env files — see docs)
klytron_configure_host_from_env('DEPLOY_HOST', 'production.example.com', [
    'remote_user' => 'deploy',
    'branch'      => 'main',
    'http_user'   => 'www-data',
    'http_group'  => 'www-data',
]);

klytron_configure_shared_files(['.env']);
klytron_configure_shared_dirs(['storage', 'bootstrap/cache']);
klytron_configure_writable_dirs([
    'bootstrap/cache',
    'storage',
    'storage/logs',
    'storage/framework/cache',
    'storage/framework/sessions',
    'storage/framework/views',
]);

// ── Deployment Flow ───────────────────────────────────────────────────────────

task('deploy', [
    'klytron:deploy:start_timer',
    'deploy:unlock',
    'klytron:deploy:check_pushed',
    'klytron:validate:basic',
    'deploy:setup',
    'deploy:lock',
    'deploy:release',
    'deploy:update_code',
    'deploy:shared',
    'klytron:laravel:deploy:environment:complete',
    'deploy:vendors',
    'klytron:laravel:node:vite:build',
    'klytron:laravel:deploy:database:complete',
    'deploy:writable',
    'klytron:laravel:deploy:cache:complete',
    'klytron:laravel:filament:assets',
    'deploy:symlink',
    'klytron:laravel:deploy:finalize:complete',
    'deploy:unlock',
    'deploy:cleanup',
    'klytron:deploy:health_check',
    'klytron:laravel:deploy:notify:complete',
    'klytron:deploy:end_timer',
])->desc('Deploy Laravel application');

2. Preview or Dry-Run Plan (CI/CD)

# Smoke test plan without SSH credentials:
vendor/bin/dep klytron:plan

# View Deployer task sequence:
vendor/bin/dep deploy --plan

3. Deploy

vendor/bin/dep deploy

Documentation

Guide	Description
Installation	Prerequisites, install methods, server setup
Quick Start	Step-by-step first deployment
Configuration Reference	All klytron_* functions and options
Function Reference	API reference
Task Reference	All available deployment tasks
Laravel Guide	Laravel-specific configuration
Yii2 Guide	Yii2-specific configuration
Simple PHP Guide	Non-framework PHP projects
Dynamic Configuration	Path templates and placeholders
Troubleshooting	Common issues and fixes

Project Structure

php-deployment-kit/
├── deployment-kit.php          # Main entry point — include this in deploy.php
├── deployment-kit-core.php     # Core helper functions
├── klytron-tasks.php           # Framework-agnostic deployment tasks
├── recipes/
│   ├── klytron-laravel-recipe.php    # Laravel deployment tasks
│   ├── klytron-yii2-recipe.php       # Yii2 deployment tasks
│   ├── klytron-php-recipe.php        # Simple PHP tasks
│   └── klytron-server-recipe.php     # Server provisioning tasks
├── src/
│   ├── Commands/               # Laravel Artisan commands
│   ├── Exceptions/             # Custom exception classes
│   ├── Services/               # Metrics, retry, validation services
│   ├── Tasks/                  # Task classes (AssetMappingTask, SitemapTask, etc.)
│   ├── Validators/             # Configuration validators
│   └── Providers/              # Laravel service provider
├── templates/                  # Starter deploy.php templates
├── examples/                   # Real-world deployment examples
└── docs/                       # Full documentation

Supported Frameworks

Framework	Recipe
Laravel	recipes/klytron-laravel-recipe.php
Yii2	recipes/klytron-yii2-recipe.php
API (Laravel)	recipes/klytron-laravel-recipe.php
Simple PHP	recipes/klytron-php-recipe.php

Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

Security

If you discover a security vulnerability, please see SECURITY.md for how to report it responsibly.

License

MIT — see LICENSE.

📦 klytron/php-deployment-kit on Packagist
⭐ GitHub