Download the PHP package machinjiri/framework without Composer

Machinjiri PHP Framework

Machinjiri is a modular, production-ready PHP framework for building maintainable web applications, APIs, and internal tools with speed and clarity. It combines a resilient service container, expressive routing, database tooling, security helpers, queue processing, task scheduling, and modern developer tooling in a single cohesive platform.

Current stable version: 2.2.6

What’s New in 2.2.6

Machinjiri 2.2.6 focuses on production-readiness, cleaner application startup, and broader infrastructure support. The release strengthens the framework across the core container, CLI tooling, queue system, task scheduler, authentication integrations, and event-driven services.

Highlights from this release include:

• Updated the framework metadata and package versioning so the project is aligned with the current 2.2.6 release
• Confirmed compatibility with PHP 8.3+, including modern PHP 8.4 runtime environments
• Improved application bootstrapping, container binding, and service provider registration for more predictable dependency resolution and startup flow
• Expanded the Artisan CLI and code-generation ecosystem for faster scaffolding, job creation, scheduler administration, and project maintenance
• Strengthened task scheduling with persisted task state, cron triggers, retries, concurrency protection, priority ordering, and health checks
• Improved the queue and worker pipeline for more reliable background processing, delayed jobs, and operational control
• Added richer webhook management with provider subscriptions, signature verification, queued/sync delivery, and idempotency safeguards
• Extended notification delivery across mail, SMS, database, and webhook channels with configurable transport and dispatch control
• Improved enterprise integrations for LDAP, Redis, FTP, and filesystem/cloud adapters for distributed deployments
• Refined request lifecycle management, middleware flow, HTTP utilities, and response handling for more robust web and API orchestration
• Improved exception handling, logging, profiling, and debugging layers to separate diagnostics, rendering, and rate-limited reporting

This release keeps Machinjiri focused on maintainability, modularity, and developer productivity without sacrificing operational safety or enterprise integration depth.

Table of Contents

• Introduction
• Features
• System Requirements
• Installation
• Quick Start
• Project Structure
• Core Components
  • Routing
  • Views & Templates
  • Database
  • Authentication & Security
  • LDAP
  • Forms & Validation
  • Service Providers
  • Mail System
  • Queues & Jobs
  • Task Scheduler
  • Webhooks
  • SMS
• Usage Examples
• Configuration
• API Reference
• Error Handling
• Testing
• Console Commands (Artisan)
• Contributing
• License
• Support

Introduction

Machinjiri is designed to accelerate web development with:

• Modular architecture with service providers and dependency injection
• Elegant routing with middleware, groups, and named routes
• Powerful view templating with inheritance and asset management
• Multi-database support with migrations and query builders
• Built-in authentication with OAuth, sessions, and cookies
• Advanced security with encryption, hashing, CSRF tokens, and SQL injection prevention
• Job queues for background processing
• Task scheduling with cron expressions and persistent execution history
• Webhook handling with signature verification and synchronous or queued dispatch
• SMS transport with configurable providers and asynchronous delivery
• Comprehensive logging and error handling

Features

Core Architecture

• Singleton Application Container: Centralized management of application resources and configuration
• Service Container: Powerful dependency injection with service binding and resolution
• Provider System: Modular service providers with lazy loading and bootstrapping
• Configuration Management: Environment-aware config loading with .env support
• Service Facades: Quick access to complex services with simple syntax
• FTP Filesystem Adapter: Remote storage operations with FTP disk support
• Redis Integration: Distributed cache and queue support for scalable workflows
• Webhook Processing: Signature verification, idempotency, and async dispatch for webhook handling
• ULID & OTP Utilities: ULID generation/validation and OTP/TOTP support for secure workflows

Routing System

• Flexible HTTP Routing: RESTful routes with GET, POST, PUT, DELETE, PATCH methods
• Route Groups: Apply middleware, prefixes, and CORS to multiple routes
• Route Parameters: Capture and validate route parameters
• AJAX Handling: Built-in AJAX-only and traditional route segregation
• Named Routes: Generate URLs using route names and parameters
• CORS Support: Automatic CORS header handling and preflight requests
• Rate Limiting: Configurable request rate limiting per route
• Route Caching: Performance optimization through route caching

View Engine

• Template Inheritance: Blade-like template inheritance with layouts and sections
• Custom Template Tags: <% %> syntax with PHP logic support
• Partial Includes: Component-based development with fragment includes
• Asset Management: Automatic CSS/JS resource loading
• Data Sharing: Share data across multiple views globally
• Loop Directives: Enhanced foreach loops with context variables

Database & ORM

• Multi-Driver Support: MySQL, PostgreSQL, SQLite database drivers
• Query Builder: Expressive, fluent query construction
• Migrations: Built-in migration system for database schema management
• Schema Builder: Create, modify, and drop tables programmatically
• Seeders & Factories: Database seeding and model factories for testing
• Connection Pool: Manage multiple database connections
• Transaction Support: ACID compliance with transaction handling

Authentication & Security

• Session Management: Secure session handling with configurable drivers
• OAuth Integration: Third-party authentication (Google, GitHub, etc.)
• Cookie Management: Secure cookie handling with encryption options
• Password Hashing: Built-in password hashing with bcrypt/Argon2
• CSRF Token Protection: Automatic CSRF token generation and validation
• SQL Injection Prevention: Parameterized queries via query builder
• Encryption: AES encryption/decryption for sensitive data
• JWT Tokens: JSON Web Token support for API authentication

Forms & Validation

• Form Validation: Comprehensive validation rules engine
• Rule Builder: Fluent interface for building complex validation rules
• Password Rules: Special validation rules for password strength
• Error Messages: Custom error messages and localization support
• Form Handler: Server-side form processing and CSRF protection

Queues & Jobs

• Background Job Processing: Defer heavy operations to background queues
• Database Queue Driver: Persist jobs in database for reliability
• Redis Queue Driver: High-performance Redis-backed job queue with delayed dispatch, reservation, and retry handling
• Job Dispatcher: Flexible job scheduling and dispatching
• Workers: Process jobs with configurable retry logic
• Event System: Event listeners and viewers for queue events
• Artisan Commands: Generate jobs and manage queue processing

Task Scheduler

• Persistent schedules: Store scheduled tasks and execution history through the database repository
• Cron expressions: Define when tasks run using standard cron syntax
• Queued execution: Dispatch due tasks to the scheduler queue
• Overlap protection: Lock tasks to prevent concurrent execution
• Task management: Register, sync, enable, disable, run, and delete tasks
• Operational controls: Group and prioritize tasks, configure retries, cache schedule data, and inspect scheduler health

Webhooks

• Provider subscriptions: Register event handlers and provider-specific behavior
• Signature verification: Support HMAC, timestamped HMAC, and custom verification callbacks
• Synchronous or asynchronous processing: Route providers to immediate handling or the webhooks queue
• Idempotency support: Track processed webhook keys through the cache-backed idempotency store
• Response handling: Return accepted, unauthorized, not-found, and other HTTP responses based on processing results

SMS

• Transport registry: Configure and select SMS transports through the SMS manager
• Synchronous delivery: Send messages immediately through the default transport
• Asynchronous delivery: Queue SMS sends on the sms queue when enabled
• Extensible providers: Add custom transports and receive structured delivery responses

Components

• Component Factory: Create UI components programmatically
• Pre-built Components: Alert, Button, Card, Form, Input, Modal, Nav, ProgressBar
• Component Traits: Reusable component functionality
• Attributes Management: Flexible attribute handling for HTML elements
• CSS Classes Builder: Dynamic CSS class generation

HTTP Layer

• Request/Response Objects: Object-oriented HTTP request and response handling
• Request Utilities: Easy access to GET/POST/FILE data, headers, and server info
• Response Types: JSON, redirects, downloads, streaming responses
• Middleware Support: Stack-based middleware pipeline with arguments
• Header Management: Easy header manipulation and CORS configuration
• Status Codes: Comprehensive HTTP status code support

Logging & Monitoring

• Multi-Channel Logging: Database, file, and event-based logging
• Structured Logging: Log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• Event System: Event listeners for application events
• Error Logging: Automatic logging of exceptions and errors
• Environment-Aware: Different logging behavior for dev/production

Date & Time Handling

• DateTime Handler: Unified date/time manipulation
• Timezone Support: Configurable timezone handling
• Format Support: Multiple date format support
• Utility Methods: Common date operations built-in

Network Utilities

• HTTP Client: cURL-based HTTP client for API calls
• Server Management: PHP built-in server management for development
• Connection Handling: Request/response HTTP utilities

System Requirements

• PHP: 8.3 or higher (compatible with PHP 8.4)
• Extensions:
  • PDO (for database support)
  • cURL (for HTTP client)
  • JSON (for API support)
  • OpenSSL (for encryption)
  • ftp (optional, for FTP filesystem support)
  • ldap (optional, for LDAP authentication and directory integration)
• Composer: 2.0 or higher
• Database: MySQL 5.7+, PostgreSQL 10+, or SQLite 3+

Installation

Install with Composer

Install Machinjiri as a dependency in your project:

Local development

To run the framework repository locally:

Recommended setup

• Copy .env.example to .env
• Set APP_KEY, database, and mail credentials
• Run composer test to verify the installation

Quick Start

1. Create Your First Route

2. Create a Controller

3. Create a View

4. Connect Route to Controller

5. Start Development Server

Visit http://localhost:3000 in your browser.

Project Structure

Core Components

Routing System

The router handles all HTTP requests and directs them to appropriate controllers or callbacks.

Basic Routing:

Middleware:

CORS Configuration:

View Engine

Machinjiri provides a powerful templating engine with a clean, readable syntax.

Template Syntax:

Layout Example:

Usage in Controller:

Database & ORM

Machinjiri provides a powerful query builder and migration system for database operations.

Database Configuration:

Query Builder:

Migrations:

Seeders:

Authentication & Security

Machinjiri provides comprehensive authentication and security features.

Session-Based Authentication:

Login/Logout:

OAuth Integration:

Password Security:

CSRF Protection:

Encryption:

LDAP

The LDAP component provides configured connections, escaped query filters, and LDAP entry objects. The PHP LDAP extension must be enabled before using it.

Register an LDAP manager:

Add the provider to config/providers.php, then query the directory from a controller or service:

For LDAP-backed authentication, configure the guard with the ldap provider driver. The provider searches by uid and mail, synchronizes selected attributes to the local user model, and validates passwords by binding with the user DN:

Forms & Validation

Create and validate forms with ease.

Form Validation:

Custom Rules:

Queues & Jobs

Process background jobs asynchronously.

Create a Job:

Dispatch Job:

Process Jobs:

Task Scheduler

Scheduled tasks extend ScheduledTask, define a cron expression, and implement handle(). Register task classes with the task manager or use the generator to create and register one:

The scheduler persists task definitions and execution history, dispatches work to the scheduler queue, prevents overlapping runs by default, and supports task groups, priorities, retries, maintenance-mode behavior, and cached status data. Use scheduler:status, scheduler:stats, scheduler:enable, and scheduler:disable to operate it.

Webhooks

Configure provider subscriptions with their signing secret, verification method, event handlers, and whether processing should be synchronous or queued. Incoming requests are processed through WebhookManager:

Queued providers are dispatched to the webhooks queue and return an accepted response. Synchronous providers invoke all matching handlers and return the first failed response, or the final successful response. HMAC, timestamped HMAC, and custom signature callbacks are supported.

SMS

Configure one or more SMS transports and send through the manager. Delivery can be immediate or queued on the sms queue:

The manager returns a structured response, logs delivery failures, and supports custom transports through the transport registry.

Components

Create reusable UI components programmatically.

Available Components:

⚙️ Configuration

Environment Configuration

Configuration is managed through .env files and config classes:

Application Configuration

Service Provider Configuration

Mail Configuration

API Reference

Application Container

Router API

View API

Request API

Response API

Database API

Error Handling

Machinjiri provides comprehensive error handling with environment-aware output:

Error Handler Features:

• Environment-specific error pages (development vs production)
• Automatic logging of uncaught exceptions
• User-friendly error messages in production
• Detailed stack traces in development
• HTTP status code mapping
• Custom error handlers per exception type
• Request and application context attached to error reports
• Configurable error reporting by email through the mail manager
• Error throttling to prevent repeated failures from overwhelming logs or notifications
• Error, exception, and shutdown handlers for runtime and fatal errors
• Custom exception renderers through ErrorHandler::setExceptionRenderer()

Console Commands (Artisan)

Machinjiri includes an Artisan console for many development workflows. Common commands include:

Testing

Machinjiri ships with an upgraded PHPUnit base test case that mirrors the framework’s newer feature set and makes application-level testing easier without forcing a full app scaffold into every repo.

Base test case

Available test concerns

The upgraded suite exposes helpers for:

• application bootstrapping and app access
• HTTP request dispatching and response assertions
• database assertions with SQLite in-memory testing
• session manipulation and assertions
• authentication helpers such as actingAs(), be(), assertAuthenticated() and assertGuest()
• console command execution via artisan()
• email, queue and event fakes
• factory creation and mocking helpers
• time freezing and faker-based data generation
• snapshot assertions

Running the suite

Best practices

• use RefreshDatabase when you want a fresh SQLite transaction per test
• use withoutMiddleware() when you need to bypass framework middleware in a request test
• use artisan() for command-level validation in console-driven features
• prefer the built-in fake helpers for mail, queue and events instead of hitting real infrastructure

Contributing

We welcome contributions! Here's how to get started:

1. Fork the Repository

2. Create a Feature Branch

3. Make Your Changes

   • Follow PSR-12 coding standards
   • Add tests for new features
   • Update documentation

4. Commit and Push

5. Open a Pull Request
   • Describe your changes clearly
   • Reference any related issues
   • Ensure tests pass

Development Setup

License

This project is licensed under a proprietary license - see the LICENSE file for details.

Support

• GitHub Issues: Report bugs and request features
• Discussions: Ask questions and share ideas
• Email: [email protected]

Authors

• Precious Lyson - GitHub | Email
• Mlangeni Group - Website

Acknowledgments

• Inspired by Laravel's elegant syntax and structure
• Built on modern PHP 8.4+ features
• Community contributions and feedback

Full Documentation:

Built with ❤️ by the Machinjiri Team

Made for developers, by developers.