Download the PHP package vormiaphp/vormia without Composer

Vormia - Laravel Package

Introduction

A comprehensive Laravel development package that streamlines media handling, notifications, and role management with a modular, maintainable approach.

VormiaPHP offers robust tools for handling media, managing notifications, and implementing essential features like user roles and permissions. The package is designed with a modular structure, separating concerns through dedicated namespaces for models, services, middleware, and traits.

Dependencies

Required Dependencies

• intervention/image: Required for MediaForge image processing functionality
  • Used for image resizing, compression, format conversion, watermarking, and avatar generation
  • Install with: composer require intervention/image

The package will automatically check for required dependencies during installation and usage, and provide helpful error messages if they're missing.

Features

• File & Image Processing
• Notification System
• Role-Based Access Control
• Modular Architecture
• Livewire Integration
• Database Organization
• Uniform Meta Management
• Robust Database Handling
• API Authentication Middleware

What's New in v4.3.0 🎉

✨ New Features

• API Authentication Middleware: New ApiAuthenticate middleware for protected API routes
• AI Documentation Guides: Comprehensive guides for developers and AI assistants
• Cache Management: Enhanced utility service with cache clearing and fresh data methods

🔧 Improvements

• Database Protection: Service providers now handle database connection issues gracefully
• Meta Methods: Unified setMeta/getMeta across all models for consistency
• Error Handling: Better error handling and troubleshooting documentation

🐛 Bug Fixes

• Type System Confusion: Clarified utilities table structure and usage patterns
• Service Provider Errors: Fixed crashes that occurred before migrations run
• Test Failures: Resolved PHPUnit test issues

📚 Documentation

• Enhanced README: Added troubleshooting section and usage examples
• AI Assistant Guides: Created LLMFLOW.md and LLMRULES.md for AI integration
• Usage Patterns: Clear examples and best practices for all features

Previous Version

Key Improvements

🔄 Uniform Meta Methods

All models now use consistent method names for managing meta data:

• setMeta($key, $value, $is_active = 1) - Set or update meta values
• getMeta($key, $default = null) - Retrieve meta values
• deleteMeta($key) - Remove meta values

This eliminates confusion between different method names like setMetaValue vs setMeta across models.

🛡️ Database Dependency Protection

Service providers now gracefully handle scenarios where:

• Database doesn't exist yet
• Migrations haven't been run
• Running in console during migrations

This prevents errors when cloning a project before running php artisan migrate.

🔐 API Authentication Middleware

New api-auth middleware for Sanctum-based API authentication:

• Automatically checks user authentication via Sanctum
• Returns proper 401 responses for unauthenticated requests
• Seamlessly integrates with existing Vormia installation

Installation

Before installing Vormia, ensure you have Laravel installed. Note: Inertia is not yet supported.

Step 1: Install Laravel

OR Using Laravel Installer

Step 2: Install Vormia

Note: The MediaForge image processing functionality requires the intervention/image package. If you plan to use image processing features, install it with:

The installation process will check for this dependency and provide helpful warnings if it's missing.

Step 3: Run Vormia Installation

• All notification stubs will be copied to app/Notifications.
• All jobs in stubs/jobs/Vrm will be copied to app/Jobs/Vrm.

If you want API support, run:

• All notification stubs will be copied to app/Notifications.
• All jobs in stubs/jobs/Vrm will be copied to app/Jobs/Vrm.
• All jobs in stubs/jobs/V1 will be copied to app/Jobs/V1.
• All API controllers in stubs/controllers/Api will be copied to app/Http/Controllers/Api.
• The API routes file in stubs/routes/api.php will be copied to routes/api.php (you may be prompted to overwrite).
• The Postman collection in stubs/public/Vormia.postman_collection.json will be copied to public/Vormia.postman_collection.json.
• You must add the HasApiTokens trait to your User model (app/Models/User.php) for API authentication.

Then, you must install Sanctum yourself:

This will install Laravel Sanctum and set up API authentication.

2. If you see a message like:

then open bootstrap/app.php and add the above lines to the appropriate arrays.

open bootstrap/providers.php and add the above lines to the appropriate arrays.

3. Configure your .env file as needed.

4. Run migrations:

🟢 API-first Vormia version If you want to bootstrap your project with API support, use:

Then, install Sanctum manually:

Usage

Meta Data Management

All models with meta support now use uniform methods:

API Authentication

Use the new api-auth middleware for protected API routes:

Or apply to individual routes:

Uninstallation

1. Run the uninstall command:

7. Troubleshooting Section

Common Issues

Database Connection Issues

Problem: Service providers throw database errors before migrations Solution: The package automatically handles this. Ensure migrations are run:

Meta Methods Not Working

Problem: setMeta() or getMeta() methods not found Solution: Ensure your models use the correct traits:

API Authentication Failing

Problem: 401 errors on protected routes Solution:

1. Ensure Sanctum is installed: php artisan install:api
2. Add HasApiTokens trait to User model
3. Check middleware alias: 'api-auth' => \App\Http\Middleware\Vrm\ApiAuthenticate::class

Utilities Service Not Working

Problem: app('vrm.utilities')->type('public')->get('theme') returns unexpected results

Root Cause: There's a conceptual mismatch between table design and service implementation:

• Table type column: Stores data types (string, integer, boolean, json)
• Service ->type('public') method: Suggests filtering by category that doesn't exist

Solutions:

Debug Utilities: