All notable changes to the Vormia package will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[5.5.5] - 2026-06-10

Added

• vormia:migrate-api-routes — focused production command to clear route/config caches, enable VORMIA_REGISTER_API_ROUTES, remove duplicate /api/v1 Vormia auth routes from the host routes/api.php, and update the Postman collection after upgrading

Changed

• Breaking: API auth prefix — login, logout, and current-user endpoints moved from /api/v1/* to /api/vrm/* so all Vormia API routes share one prefix and no longer conflict with host-app /api/v1 versioning

[Unreleased]

[5.4.0] - 2026-04-17

Added

• MediaForge fluent URL builder: MediaForge::url($pathOrUrl, $disk = null) now returns a builder that can generate:
  • Public URLs via ->public()
  • Signed temporary URLs via ->private() (prefers temporaryUrl() when supported)
  • Flexible expiry helpers: ->seconds(), ->minutes(), ->hours(), ->days(), ->years(), and ->expiresAt(...)
• Signed URL default lifetime: VORMIA_MEDIAFORGE_PREVIEW_PERIOD (seconds)
  • Missing key: defaults to 86400 (24h)
  • Present but empty (VORMIA_MEDIAFORGE_PREVIEW_PERIOD=): defaults to 3600 (1h)

Changed

• Breaking: MediaForge upload return value: MediaForge::upload(...)->run() and MediaForge::uploadFile(...)->run() now return a storage path/key by default (instead of sometimes returning a URL).
• Installer env block (vormia:install): now includes
  • VORMIA_MEDIAFORGE_STORAGE_RULE=vormia
  • VORMIA_MEDIAFORGE_PREVIEW_PERIOD=86400
• MediaForge preview helper: MediaForge::previewUrl(...) remains as a compatibility wrapper, implemented via the URL builder.

Removing style.scss among imported files

Release Notes

This document contains human-friendly release notes for tagged versions of this package.

v5.5.2

Summary

• AI conversion guides (aiguide/) are organized by topic: Inertia.js guides under aiguide/inertia/, Livewire under aiguide/livewire/, and experimental tracks under aiguide/beta/. Root-level “from scratch” Markdown guides remain at the top of aiguide/.
• New Inertia.js v3 reference: aiguide/inertia/inertiajs-operations.md describes adapter-agnostic behavior (Laravel, visits, Blade root, middleware, forms, testing pointers). Stack-specific React → Inertia guides stay as .mdc files next to it.
• Documentation refresh: README.md AI guide links and the “See also” note now target these paths; aiguide/README.md is the canonical index inside the folder.

Changes

• Relocated Inertia conversion .mdc files and the new operations doc into aiguide/inertia/.
• Relocated the Livewire Volt inline conversion guide into aiguide/livewire/.
• Relocated Laravel → Next.js / React SPA / Expo guides into aiguide/beta/.
• Removed stale references to a non-shipped references/react-laravel.mdc path in favor of the in-repo Livewire Volt inline guide.

Upgrade / Install

composer require vormiaphp/vormia:^5.5
php artisan vormia:install
# Inertia frontend (no prompts):
# php artisan vormia:install --stack=inertia --no-interaction

v5.4.0

Summary

• MediaForge now returns storage paths/keys by default, and provides a fluent URL builder that can generate either public URLs or signed temporary URLs for private buckets (S3, R2, Spaces, etc.).

Breaking Changes

• MediaForge upload return value: MediaForge::upload(...)->run() and MediaForge::uploadFile(...)->run() now return a path/key (e.g. uploads/products/2026/04/17/abc.webp) instead of sometimes returning a URL.
  • Upgrade: If your app previously stored the return value as a URL, update it to store the returned path and build URLs at render time.

Changes

• Fluent URL builder: MediaForge::url($pathOrUrl, $disk = null) now returns a builder (string-castable):
  • Public: MediaForge::url($path)->public()
  • Private/signed: MediaForge::url($path)->private() (uses temporaryUrl() when supported)
  • Expiry helpers: ->seconds(), ->minutes(), ->hours(), ->days(), ->years(), or ->expiresAt(...)
• Preview URL defaults:
  • New env: VORMIA_MEDIAFORGE_PREVIEW_PERIOD (seconds)
    • Missing key: defaults to 86400 (24h)
    • Present but empty (VORMIA_MEDIAFORGE_PREVIEW_PERIOD=): defaults to 3600 (1h)
• Installer env updates (php artisan vormia:install):
  • Adds VORMIA_MEDIAFORGE_STORAGE_RULE=vormia
  • Adds VORMIA_MEDIAFORGE_PREVIEW_PERIOD=86400
• Compatibility:
  • MediaForge::previewUrl(...) remains available as a compatibility helper (internally uses the builder).

Upgrade / Install

composer require vormiaphp/vormia:^5.4
php artisan vormia:install

v5.4.0

Summary

• MediaForge now returns storage paths/keys by default, and provides a fluent URL builder that can generate either public URLs or signed temporary URLs for private buckets (S3, R2, Spaces, etc.).

Breaking Changes

• MediaForge upload return value: MediaForge::upload(...)->run() and MediaForge::uploadFile(...)->run() now return a path/key (e.g. uploads/products/2026/04/17/abc.webp) instead of sometimes returning a URL.
  • Upgrade: If your app previously stored the return value as a URL, update it to store the returned path and build URLs at render time.

Changes

• Fluent URL builder: MediaForge::url($pathOrUrl, $disk = null) now returns a builder (string-castable):
  • Public: MediaForge::url($path)->public()
  • Private/signed: MediaForge::url($path)->private() (uses temporaryUrl() when supported)
  • Expiry helpers: ->seconds(), ->minutes(), ->hours(), ->days(), ->years(), or ->expiresAt(...)
• Preview URL defaults:
  • New env: VORMIA_MEDIAFORGE_PREVIEW_PERIOD (seconds)
    • Missing key: defaults to 86400 (24h)
    • Present but empty (VORMIA_MEDIAFORGE_PREVIEW_PERIOD=): defaults to 3600 (1h)
• Installer env updates (php artisan vormia:install):
  • Adds VORMIA_MEDIAFORGE_STORAGE_RULE=vormia
  • Adds VORMIA_MEDIAFORGE_PREVIEW_PERIOD=86400
• Compatibility:
  • MediaForge::previewUrl(...) remains available as a compatibility helper (internally uses the builder).

Upgrade / Install

composer require vormiaphp/vormia:^5.4
php artisan vormia:install

Changelog

All notable changes to the Vormia package will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[5.3.0] - 2026-04-13

Added

• Non-image file uploads in MediaForge: Added uploadFile() for uploading raw files (PDFs, docs, zips, etc.) without image processing
• MediaForge upload raw-file mode: Enhanced upload() with an isFile() flag to treat uploads as raw files and skip image operations

Changed

• Documentation: Updated MediaForge docs with examples and guidance for non-image uploads
• Tests: Added coverage for uploading non-image files and verifying storage behavior

[5.2.0] - 2026-04-10

Added

• MediaForge URL helpers: New utilities for turning MediaForge outputs into browser-friendly URLs
  • MediaForge::url($urlOrPath, $disk = null) to normalize a MediaForge run() return value (URL-or-path) into a usable URL when possible
  • MediaForge::previewUrl($urlOrPath, $disk = null, $expiresAt = null, array $options = []) to generate previewable URLs, including signed temporary URLs when supported by the disk
• MediaForge proxy preview route (optional): When VORMIA_MEDIAFORGE_PREVIEW_MODE=proxy, Vormia exposes GET /api/vrm/media/preview?disk=...&path=... to stream files for previewing from disks that don’t support url()/temporaryUrl() reliably
• MediaForge URL passthrough config: VORMIA_MEDIAFORGE_URL_PASSTHROUGH controls whether MediaForge::url() returns existing http(s)/data: inputs unchanged

Changed

• Documentation: Expanded MediaForge docs around “URL-or-path” return values, S3/remote disks, and failure handling

[5.1.4] - 2026-04-10

Added

• MediaForge storage rule + date folders: New options to control how MediaForge writes files
  • Supports a YYYY/MM/DD folder structure via useDateFolders()
  • Supports switching between Laravel filesystem disks and legacy webroot behavior via a storage rule

Changed

• Documentation: Updated release notes for v5.1.3 with improved two-factor migration guidance

[5.0.2] - 2025-03-09

Added

• vormia:uninstall: New Artisan command to fully remove Vormia from an application
  • Removes Vormia config, stubs, and public assets
  • Cleans Vormia entries from bootstrap/app.php and bootstrap/providers.php
  • Strips VORMIA_* from .env and .env.example
  • Reverts Vormia CSS/JS in resources/css/app.css and resources/js/app.js
  • Drops all Vormia database tables (vrm_*)
  • Uninstalls Vormia-related npm packages (jquery, flatpickr, select2, sweetalert2)
  • Clears caches via optimize:clear
  • Use --force to skip confirmation prompt

[5.0.1] - 2025-03-09

Changed

• Version patch release.

[4.5.2] - 2025-01-15

Fixed

• PSR-4 Autoloading Compliance: Fixed PSR-4 autoloading warnings for stub files
  • Excluded src/stubs/ directory from Composer autoloading
  • Stub files are template files with App\ namespaces meant for Laravel applications
  • These files should not be autoloaded from the package itself
  • Resolves warnings: Class src\stubs\Controllers\... does not comply with psr-4 autoloading standard

Technical

• Composer Configuration: Added exclude-from-classmap to composer.json autoload section
  • Prevents Composer from scanning stub files during autoload generation
  • Maintains proper PSR-4 compliance for package classes

[4.5.1] - 2025-01-15

Added

• RoleSeeder: New database seeder for initial role setup
  • Automatically creates three default roles: Super Admin, Admin, and Member
  • Seeder is copied to database/seeders during package installation and updates
  • Includes proper role configuration with authority levels and module assignments
  • Seeder follows Laravel conventions and uses the Vrm\Role model

Changed

• Installation Process: Enhanced to include seeder file copying
  • Seeders are now automatically copied during vormia:install command
  • Seeders are updated during vormia:update command
  • Follows the same pattern as migrations for consistency

Documentation

• Seeder Integration: Added RoleSeeder to package stubs for automatic distribution

[4.5.0] - 2025-01-15

Added

• MediaForge Background Fill Color: Resize operations now support background fill color when maintaining aspect ratio
  • Creates exact dimensions with image centered on colored background
  • Empty areas are filled with specified color (e.g., #5a85b9)
• Advanced Thumbnail Controls: Full control over thumbnail generation
  • keepAspectRatio parameter: Control whether thumbnails maintain aspect ratio or use exact dimensions
  • fromOriginal parameter: Choose to generate thumbnails from original uploaded image or processed image
  • fillColor parameter: Fill empty areas with background color when aspect ratio is maintained
• Thumbnail Configuration: New environment variables for thumbnail defaults
  • VORMIA_MEDIAFORGE_THUMBNAIL_KEEP_ASPECT_RATIO (default: true)
  • VORMIA_MEDIAFORGE_THUMBNAIL_FROM_ORIGINAL (default: false)
• Consistent File Naming: Predictable file naming patterns for all processed images
  • Resize: {baseName}-{width}-{height}.{extension}
  • Resize + Convert: {baseName}-{width}-{height}-{format}.{format}
  • Thumbnails: {baseName}_{suffix}.{extension}

Changed

• Resize Operation: Always saves with width-height format for consistent naming
• File Path Handling: Improved path resolution to ensure files are saved in correct directories
• Thumbnail Generation: Enhanced to support multiple control options with config defaults

Fixed

• Resize Directory Issue: Fixed resize operations saving to wrong directory when override=false
• Background Fill Bug: Fixed background fill color hiding the image - now properly creates canvas with fill color
• Thumbnail Source Selection: Fixed fromOriginal parameter to correctly use original uploaded file instead of processed image
• File Naming: Fixed return values to reflect correct file names after resize and convert operations
• Path Consistency: Ensured all processed files (resized, converted, thumbnails) are saved in the same directory

Documentation

• Updated AI/MCP Guide: Added comprehensive MediaForge usage examples and configuration
• Updated AI/MCP Rules: Added MediaForge code patterns and best practices
• Updated README.md: Added MediaForge usage section with examples and configuration
• Updated AI Docs: Enhanced documentation with all new features

[4.3.0] - 2024-12-19

Added

• Version Management: Proper version field in composer.json and consistent versioning
• Tag Cleanup: Resolved git tag organization issues and standardized versioning
• Release Process: Streamlined release process with proper version management

Changed

• Version Bump: Major version bump from 4.2.x to 4.3.0 for better semantic versioning
• Documentation: Updated all version references across the package

[4.2.8] - 2024-12-19

Added

• New API Authentication Middleware: Added ApiAuthenticate middleware with 'api-auth' alias for protected API routes
• Comprehensive AI Documentation: Added dedicated AI guidance for assistants and developers
• Database Dependency Protection: Added error handling in service providers to prevent crashes before migrations run
• Enhanced Troubleshooting: Added comprehensive troubleshooting section in README with cache management instructions
• Cache Management Methods: Added clearCache(), fresh() methods to UtilityService for better performance

Changed

• Meta Methods Standardization: Unified setMeta/getMeta methods across User and Taxonomy models for consistency
• Service Provider Robustness: Enhanced UtilitiesServiceProvider, GlobalDataServiceProvider, and TokenServiceProvider with database connection checks
• Documentation Structure: Reorganized and enhanced README with better examples and usage patterns
• Installation Process: Updated InstallCommand to include new middleware aliases automatically

Fixed

• Type System Confusion: Clarified utilities table structure and corrected usage patterns
• Service Provider Errors: Fixed database connection errors that occurred before migrations
• Meta Method Inconsistency: Resolved confusion between setMeta/setMetaValue methods
• Test Failures: Fixed PHPUnit tests in MediaForgeDependencyTest and InstallationTest

Documentation

• New AI Guides: Created comprehensive guides for LLM models and IDE AI assistants
• Usage Examples: Added practical code examples for all major features
• Troubleshooting: Added common issues and solutions section
• API Documentation: Enhanced API usage examples and middleware documentation

[4.2.7] - Previous Release

Added

• Initial package structure and basic functionality

Changed

• Core package implementation

Fixed

• Basic package setup and configuration

[4.2.6] - Previous Release

Added

• Basic user management features

Changed

• Package structure improvements

Fixed

• Initial package bugs

[4.2.5] - Previous Release

Added

• Role and permission system

Changed

• Enhanced user management

Fixed

• Permission-related issues

[4.2.4] - Previous Release

Added

• Taxonomy system

Changed

• Improved role management

Fixed

• Taxonomy-related bugs

[4.2.3] - Previous Release

Added

• Utility service

Changed

• Enhanced taxonomy system

Fixed

• Utility service issues

[4.2.2] - Previous Release

Added

• Media forge service

Changed

• Improved utility service

Fixed

• Media processing bugs

[4.2.1] - Previous Release

Added

• API authentication

Changed

• Enhanced media forge

Fixed

• API-related issues

[4.2.0] - Previous Release

Added

• Major version features

Changed

• Significant improvements

Fixed

• Major bug fixes

[4.1.2] - Previous Release

Added

• Minor features

Changed

• Small improvements

Fixed

• Minor bugs

[4.1.1] - Previous Release

Added

• Initial features

Changed

• Basic improvements

Fixed

• Basic bugs

Release Notes Format

Breaking Changes

• Any changes that break existing functionality
• Migration steps required

New Features

• What's new in this version
• How to use new features

Improvements

• Performance improvements
• Code quality enhancements
• Better error handling

Bug Fixes

• Issues resolved in this version
• Workarounds no longer needed

Installation & Migration

• How to upgrade from previous versions
• Any new configuration requirements
• Database changes if applicable

Contributing

When adding new entries to this changelog, please follow the established format and include:

• Clear description of changes
• Impact on existing functionality
• Migration steps if breaking changes
• Examples of new features

v5.2.0

Summary

• Feature release focused on MediaForge URL handling for local disks and S3/remote disks: normalize “URL-or-path” return values, generate previewable URLs (including signed URLs when supported), and optionally enable a proxy preview endpoint.

Changes

• MediaForge::url(): helper to turn either a URL or a storage path/key into something safe to use in <img src="..."> when possible.
  • Controlled by VORMIA_MEDIAFORGE_STORAGE_RULE, VORMIA_MEDIAFORGE_DISK, and VORMIA_MEDIAFORGE_URL_PASSTHROUGH.
• MediaForge::previewUrl(): helper to generate a browser-previewable URL for a MediaForge output.
  • Uses temporaryUrl() when available and configured to prefer private previews.
  • Defaults are controlled via:
    • VORMIA_MEDIAFORGE_PREVIEW_MODE (auto|public|private|proxy)
    • VORMIA_MEDIAFORGE_PREVIEW_EXPIRES_MINUTES
• Proxy preview endpoint (optional): when VORMIA_MEDIAFORGE_PREVIEW_MODE=proxy, Vormia enables:
  • GET /api/vrm/media/preview?disk={disk}&path={path}
  • Streams the file from the configured disk for previewing (returns 404 if proxy mode is not enabled).

Upgrade / Install

composer require vormiaphp/vormia:^5.2

Release Notes

This document contains human-friendly release notes for tagged versions of this package.

v5.1.3

Summary

• Patch release: vormia:install is resilient when two-factor columns already exist on users (Fortify, Breeze, or an earlier migration) and when php artisan install:api would otherwise publish a duplicate two-factor migration.

Changes

• TwoFactorMigrationNormalizer (src/Console/Support/TwoFactorMigrationNormalizer.php): runs automatically during vormia:install—before the kit’s migrate, and again before install:api. It finds migrations in database/migrations whose names include two_factor and user, and replaces unconditional Schema::table('users') adds with idempotent Schema::hasColumn checks for two_factor_secret, two_factor_recovery_codes, and two_factor_confirmed_at.
• installSanctum(): skips php artisan install:api when users.two_factor_secret already exists; installs Sanctum via composer require laravel/sanctum and publishes SanctumServiceProvider (including personal_access_tokens migration when missing).
• On duplicate two_factor_* column errors from install:api, the installer re-runs the normalizer, runs migrate --force, then finishes Sanctum setup if Sanctum is still missing.
• install:api is invoked with --no-interaction for predictable scripted installs.
• No separate Artisan command for two-factor patching—behavior is integrated into vormia:install only.

Upgrade / Install

composer require vormiaphp/vormia:^5.1

Manual fix (older installs or failed installs)

1. Upgrade the package, then run php artisan vormia:install again so the normalizer can rewrite unsafe migrations before migrate runs.
2. If a bad migration file remains, delete or hand-edit it under database/migrations/, then run php artisan migrate.

v5.1.2

Summary

• Documentation-focused patch: the copy-paste User example is aligned with Vormia traits and migrations.

Changes

• Expanded examples/User.php with a file-level guide for integrating HasVormiaRoles (roles, permissions, and composed HasUserMeta) and HasSlugs (registry-backed slugs).
• Switched to explicit $fillable / $hidden and added fields that match the Vormia users migration (username, phone, provider, provider_id, avatar), plus SoftDeletes and phone_verified_at casting.
• Exposed the primary slug as a virtual slug attribute via Attribute::get() so route generation and serialization stay consistent with findBySlug() / resolveRouteBinding().
• Added isMember() (role check by slug member) and tightened return types on slug-related methods.

Upgrade / Install

composer require vormiaphp/vormia:^5.1

v5.1.1

Summary

• Patch release to fix a PHP match syntax issue in NotificationService.

Changes

• Fixed invalid match arm for the INFO notification type that could trigger a parse error (unexpected token "default", expecting "=>").

Upgrade / Install

composer require vormiaphp/vormia:^5.1

v5.1.0

Summary

• Maintenance release to align dependencies and keep repository artifacts clean.

Changes

• Synced composer.lock with composer.json after dependency updates.
• Stopped tracking PHPUnit cache artifacts and ignored /.phpunit.cache/.

Upgrade / Install

composer require vormiaphp/vormia:^5.1

Verification

composer validate --strict
composer test

Release Notes

This document contains human-friendly release notes for tagged versions of this package.

v5.1.2

Summary

• Documentation-focused patch: the copy-paste User example is aligned with Vormia traits and migrations.

Changes

• Expanded examples/User.php with a file-level guide for integrating HasVormiaRoles (roles, permissions, and composed HasUserMeta) and HasSlugs (registry-backed slugs).
• Switched to explicit $fillable / $hidden and added fields that match the Vormia users migration (username, phone, provider, provider_id, avatar), plus SoftDeletes and phone_verified_at casting.
• Exposed the primary slug as a virtual slug attribute via Attribute::get() so route generation and serialization stay consistent with findBySlug() / resolveRouteBinding().
• Added isMember() (role check by slug member) and tightened return types on slug-related methods.

Upgrade / Install

composer require vormiaphp/vormia:^5.1

v5.1.1

Summary

• Patch release to fix a PHP match syntax issue in NotificationService.

Changes

• Fixed invalid match arm for the INFO notification type that could trigger a parse error (unexpected token "default", expecting "=>").

Upgrade / Install

composer require vormiaphp/vormia:^5.1

v5.1.0

Summary

• Maintenance release to align dependencies and keep repository artifacts clean.

Changes

• Synced composer.lock with composer.json after dependency updates.
• Stopped tracking PHPUnit cache artifacts and ignored /.phpunit.cache/.

Upgrade / Install

composer require vormiaphp/vormia:^5.1

Verification

composer validate --strict
composer test

Release Notes

This document contains human-friendly release notes for tagged versions of this package.

v5.1.1

Summary

• Patch release to fix a PHP match syntax issue in NotificationService.

Changes

• Fixed invalid match arm for the INFO notification type that could trigger a parse error (unexpected token "default", expecting "=>").

Upgrade / Install

composer require vormiaphp/vormia:^5.1

v5.1.0

Summary

• Maintenance release to align dependencies and keep repository artifacts clean.

Changes

• Synced composer.lock with composer.json after dependency updates.
• Stopped tracking PHPUnit cache artifacts and ignored /.phpunit.cache/.

Upgrade / Install

composer require vormiaphp/vormia:^5.1

Verification

composer validate --strict
composer test

Release Notes

This document contains human-friendly release notes for tagged versions of this package.

v5.1.0

Summary

• Maintenance release to align dependencies and keep repository artifacts clean.

Changes

• Synced composer.lock with composer.json after dependency updates.
• Stopped tracking PHPUnit cache artifacts and ignored /.phpunit.cache/.

Upgrade / Install

composer require vormiaphp/vormia:^5.1

Verification

composer validate --strict
composer test

Support Laravel 13

We fixed the plugin codebase path for App.js and App.css

Vormia Package — Release Notes

Package: vormiaphp/vormia
Description: A comprehensive Laravel package for user management, roles, permissions, and utilities.

What’s New (since v5.0.0)

Latest (unreleased / post-v5.0.2)

• AI conversion guide: React → Laravel Livewire guide updated for Livewire 4 (Blade + Livewire Volt inline/non-class components). The guide in aiguide/react-to-laravel-livewire-inline.mdc is aligned with Livewire 4 patterns and best practices.

v5.0.2 (2025-03-09)

Added

• vormia:uninstall — New Artisan command to fully remove Vormia from an application:
  • Removes Vormia config, stubs, and public assets
  • Cleans Vormia entries from bootstrap/app.php and bootstrap/providers.php
  • Strips VORMIA_* from .env and .env.example
  • Reverts Vormia CSS/JS in resources/css/app.css and resources/js/app.js
  • Drops all Vormia database tables (vrm_*)
  • Uninstalls Vormia-related npm packages (jquery, flatpickr, select2, sweetalert2)
  • Clears caches via optimize:clear
  • Use --force to skip the confirmation prompt

v5.0.1 (2025-03-09)

• Patch release (README and service provider updates for installation instructions; workspace configuration and console commands streamlined).

v5.0.0

• Laravel 12 support.
• Major release aligning the package with Laravel 12 and current tooling.

Quick reference

For a full, version-by-version history, see CHANGELOG.md.

v5.0.0

Laravel 12 Support (as of March 1, 2026)

• Full compatibility with the latest Laravel 12 framework
• Updated documentation and installation guides for Laravel 12 and Livewire 4

Overview

This patch release fixes PSR-4 autoloading compliance warnings that occurred when Composer scanned stub files during autoload generation.

What's Fixed

PSR-4 Autoloading Compliance
Resolved PSR-4 autoloading warnings for stub files in the package
Excluded src/stubs/ directory from Composer autoloading
Stub files are template files with App\ namespaces intended for Laravel applications
These files should not be autoloaded from the package itself
Resolved Warnings:
Class src\stubs\Controllers\Api\v1\AuthLoginController does not comply with psr-4 autoloading standard
Class src/stubs/Controllers\Vrm\PermissionController does not comply with psr-4 autoloading standard
Class src\stubs\Controllers\Vrm\RoleController does not comply with psr-4 autoloading standard
Class src\stubs\Controllers\Vrm\UserRoleController does not comply with psr-4 autoloading standard

• RoleSeeder: New database seeder for initial role setup
  • Automatically creates three default roles: Super Admin, Admin, and Member
  • Seeder is copied to database/seeders during package installation and updates
  • Includes proper role configuration with authority levels and module assignments
  • Seeder follows Laravel conventions and uses the Vrm\Role model

Changed

• Installation Process: Enhanced to include seeder file copying
  • Seeders are now automatically copied during vormia:install command
  • Seeders are updated during vormia:update command
  • Follows the same pattern as migrations for consistency

Vormia v4.5.0 Release Notes

🎉 Major MediaForge Enhancements

This release brings significant improvements to the MediaForge image processing service, including advanced thumbnail controls, background fill color support, and critical bug fixes.

✨ New Features

Background Fill Color for Resize Operations

Resize operations now support background fill color when maintaining aspect ratio. This creates exact dimensions with the image centered on a colored background, perfect for product images and thumbnails.

use App\Facades\Vrm\MediaForge;

// Resize with background fill color
$imageUrl = MediaForge::upload($file)
    ->to('products')
    ->resize(606, 606, true, '#5a85b9')  // Creates exact 606x606 with #5a85b9 background
    ->run();

How it works:

• Image is scaled to fit within target dimensions while maintaining aspect ratio
• Empty areas are filled with the specified color
• Final image is exactly the specified dimensions (e.g., 606x606)

Advanced Thumbnail Controls

Thumbnail generation now offers full control over aspect ratio, source image selection, and fill color:

// Thumbnail with all controls
$imageUrl = MediaForge::upload($file)
    ->to('products')
    ->resize(606, 606, true, '#5a85b9')
    ->thumbnail(
        [[500, 500, 'thumb'], [400, 267, 'featured'], [400, 300, 'product']],
        true,   // keepAspectRatio: true = maintain, false = exact dimensions
        false,  // fromOriginal: false = from processed, true = from original uploaded
        '#ffffff' // fillColor: fill empty areas when aspect ratio maintained
    )
    ->run();

New Parameters:

• keepAspectRatio (bool|null): Control whether thumbnails maintain aspect ratio or use exact dimensions
• fromOriginal (bool|null): Choose to generate from original uploaded image or processed image
• fillColor (string|null): Fill empty areas with background color when aspect ratio is maintained

Configuration Options

New environment variables for thumbnail defaults:

VORMIA_MEDIAFORGE_THUMBNAIL_KEEP_ASPECT_RATIO=true
VORMIA_MEDIAFORGE_THUMBNAIL_FROM_ORIGINAL=false

These can be overridden per-call or set globally via .env file.

🔧 Improvements

Consistent File Naming

All processed images now follow predictable naming patterns:

• Resize only: {baseName}-{width}-{height}.{extension}

  • Example: abc123-606-606.jpg

• Resize + Convert: {baseName}-{width}-{height}-{format}.{format}

  • Example: abc123-606-606-webp.webp

• Thumbnails: {baseName}_{suffix}.{extension}

  • Example: abc123-606-606_thumb.webp

Improved Path Handling

• All processed files (resized, converted, thumbnails) are now saved in the same directory
• File paths are correctly returned after operations
• Directory structure is preserved throughout the processing chain

🐛 Bug Fixes

Resize Directory Issue

Fixed: Resize operations were saving to the wrong directory (public root) when override=false. Now all files are correctly saved to the specified ->to('products') directory.

Background Fill Color Bug

Fixed: Background fill color was hiding the entire image. Now properly creates a canvas with the fill color and places the resized image on top (centered), making the image visible with colored background.

Thumbnail Source Selection

Fixed: The fromOriginal parameter now correctly uses the original uploaded file instead of the processed image, regardless of previous resize/convert operations.

File Naming

Fixed: Return values now correctly reflect the actual file names after resize and convert operations, following the consistent naming patterns.

Exact Dimensions

Fixed: Resize operations now produce exactly the specified dimensions (e.g., 606x606) when background fill color is provided, instead of maintaining aspect ratio without fill.

📚 Documentation Updates

• LLMFLOW.md: Added comprehensive MediaForge usage examples and configuration
• LLMRULES.md: Added MediaForge code patterns and best practices
• README.md: Added MediaForge usage section with examples and configuration
• READMEDOC.md: Enhanced MediaForge documentation with all new features

🔄 Migration Guide

No Breaking Changes

This release is backward compatible. Existing code will continue to work, but you can now take advantage of the new features.

Upgrading

1. Update your package:

   composer update vormiaphp/vormia
   

2. (Optional) Add new environment variables to your .env:

   VORMIA_MEDIAFORGE_THUMBNAIL_KEEP_ASPECT_RATIO=true
   VORMIA_MEDIAFORGE_THUMBNAIL_FROM_ORIGINAL=false
   

3. Run the install command to update configuration:

   php artisan vormia:install
   

Using New Features

Example: Resize with Background Fill

// Old way (still works)
$imageUrl = MediaForge::upload($file)
    ->to('products')
    ->resize(606, 606)
    ->run();

// New way with background fill
$imageUrl = MediaForge::upload($file)
    ->to('products')
    ->resize(606, 606, true, '#5a85b9')  // Adds background fill
    ->run();

Example: Advanced Thumbnails

// Old way (still works)
$imageUrl = MediaForge::upload($file)
    ->to('products')
    ->thumbnail([[500, 500, 'thumb']])
    ->run();

// New way with full control
$imageUrl = MediaForge::upload($file)
    ->to('products')
    ->thumbnail(
        [[500, 500, 'thumb']],
        true,   // keepAspectRatio
        true,   // fromOriginal
        '#ffffff' // fillColor
    )
    ->run();

📋 Full Changelog

See CHANGELOG.md for complete list of changes.

🙏 Thank You

Thank you for using Vormia! If you encounter any issues or have suggestions, please open an issue on GitHub.

Release Date: January 15, 2025
Version: 4.5.0
Compatibility: Laravel 12+, PHP 8.2+

v4.4.0 - Automated Installation & Enhanced Frontend Integration

🎉 Major Release: Fully Automated Installation Process

This release introduces a completely automated installation experience, eliminating manual steps and streamlining the Vormia setup process. Installation now handles everything from dependencies to frontend assets automatically.

✨ New Features

Automated Installation Process

• Complete automation: All dependencies and assets are installed automatically
• One-command setup: php artisan vormia:install handles everything
• Smart dependency management: Automatically detects and installs missing packages

NPM Package Management

• Automatic npm package installation: jquery, flatpickr, select2, sweetalert2
• Package removal on uninstall: Clean uninstallation removes all npm packages
• Graceful error handling: Continues installation even if npm is unavailable

CSS/JS Asset Integration

• Automatic asset copying: CSS/JS plugin files copied to resources/css/plugins and resources/js/plugins
• Automatic app.css updates: Adds required imports for Livewire Flux and Vormia styles
• Automatic app.js updates: Integrates jQuery, Select2, Flatpickr, SweetAlert2, and Livewire hooks
• Seamless frontend integration: No manual configuration needed

Dependency Auto-Installation

• intervention/image: Automatically installed via Composer
• Laravel Sanctum: Automatically installed via php artisan install:api
• CORS configuration: Automatically published via php artisan config:publish cors

Enhanced Uninstallation

• Comprehensive cleanup: Removes all Vormia files, npm packages, and dependencies
• Automatic npm package removal: Uninstalls jquery, flatpickr, select2, sweetalert2
• Automatic dependency removal: Removes intervention/image via Composer
• Clear manual cleanup instructions: Guides users on optional cleanup steps

🔧 Improvements

Streamlined Installation

• Removed --api flag: API support is now always included by default
• Simplified command: No need to remember flags - just run php artisan vormia:install
• Better user experience: Clearer installation steps and progress messages

Frontend Integration

• Zero-configuration setup: CSS/JS assets automatically integrated
• Proper import structure: Follows Laravel best practices for asset management
• Livewire integration: Automatic setup of Livewire hooks

Better Error Handling

• Graceful degradation: Installation continues even if npm or Composer commands fail
• Helpful error messages: Clear instructions for manual installation when needed
• Non-blocking failures: Individual package failures don't stop the entire installation

🐛 Bug Fixes

• Installation consistency: Fixed inconsistencies in installation process
• Documentation accuracy: Updated all documentation to reflect new automated process

📚 Documentation

• Updated README.md: Comprehensive installation and uninstallation documentation
• Updated LLMFLOW.md: Added installation and uninstallation process details
• Updated READMEDOC.md: Added CSS/JS assets section and troubleshooting
• Enhanced troubleshooting: New sections for CSS/JS assets and dependencies

🚀 Migration Guide

For New Installations

Simply run: composer require vormiaphp/vormia php artisan vormia:installEverything is now automated!

For Existing Installations

If you're upgrading from v4.3.x or earlier:

1. Update the package:

   composer update vormiaphp/vormia 2. Re-run installation (if needed): php artisan vormia:update 3. Install npm packages (if not already installed): npm install jquery flatpickr select2 sweetalert2 4. Install dependencies (if not already installed): composer require intervention/image php artisan install:api php artisan config:publish cors

   📦 Breaking Changes

• Removed --api flag: The --api flag is no longer available. API support is always included by default.

⚠️ Important Notes

• HasApiTokens trait: You still need to manually add the HasApiTokens trait to your User model for API authentication
• Manual cleanup: If you uninstall Vormia, you may want to manually remove Sanctum and CORS config if they're no longer needed

🔗 Links

• Full Changelog
• Documentation
• Previous Version

Thank you for using Vormia! 🎉

Added

• New API Authentication Middleware: Added ApiAuthenticate middleware with 'api-auth' alias for protected API routes
• Comprehensive AI Documentation: Created LLMFLOW.md and LLMRULES.md guides for AI assistants and developers
• Database Dependency Protection: Added error handling in service providers to prevent crashes before migrations run
• Enhanced Troubleshooting: Added comprehensive troubleshooting section in README with cache management instructions
• Cache Management Methods: Added clearCache(), fresh() methods to UtilityService for better performance

Changed

• Meta Methods Standardization: Unified setMeta/getMeta methods across User and Taxonomy models for consistency
• Service Provider Robustness: Enhanced UtilitiesServiceProvider, GlobalDataServiceProvider, and TokenServiceProvider with database connection checks
• Documentation Structure: Reorganized and enhanced README with better examples and usage patterns
• Installation Process: Updated InstallCommand to include new middleware aliases automatically

Fixed

• Type System Confusion: Clarified utilities table structure and corrected usage patterns
• Service Provider Errors: Fixed database connection errors that occurred before migrations
• Meta Method Inconsistency: Resolved confusion between setMeta/setMetaValue methods
• Test Failures: Fixed PHPUnit tests in MediaForgeDependencyTest and InstallationTest

Documentation

• New AI Guides: Created comprehensive guides for LLM models and IDE AI assistants
• Usage Examples: Added practical code examples for all major features
• Troubleshooting: Added common issues and solutions section
• API Documentation: Enhanced API usage examples and middleware documentation

Full Changelog: https://github.com/vormiaphp/vormia/compare/v4.2.7...v4.2.9

Solving slug issues while trying to get the slug from the list of Data.

Slug Management Updated This allows for ease of access and updating slug

Full Changelog: https://github.com/vormiaphp/vormia/compare/v4.2.5...v4.2.6

The package is stable for use, and major problems have been solved.

What works?

1. User Management (You can attach roles and use APIs)
2. Taxonomy is easy to use with auto slug and metadata sync
3. Slug registry works well with the default auto update
4. Notification class works as designed
5. Media Manager also works well with GD and Imagick

Features Still Pending

1. Toast notifications are yet to be tested (Do not use)
2. Global Data, though work is yet to be fully tested (add caution if you decide to use) 3: Permission control is yet to be tested (add caution if you decide to use) 4: Utilities class also not yet tested (add caution if you decide to use) 5: The Tokens class is also not tested (Do not use) 6: LLM Guide has not been updated (Do not use)

Apart from the above features, you can start using the package for bootstrapping your projects.

However a piolot use is current in test

The command created an error during installation

Bug for release tag corrected. The package has no Bugs

A comprehensive Laravel development package that streamlines common web application functionalities. Built with Laravel best practices and designed for maintainability and scalability.

Total Package rewrite and upgrades, now stable for production use.

Full Changelog: https://github.com/vormiaphp/vormia/compare/v4.1.0...v4.1.1

This version introduces new way of handling every procces and documentation to support the packages

A minor update to allow custom names on thumbnails.

A bug that was preventing email view templates from being copied during installation has been fixed.